---
name: 文件预览语法高亮影响分析
description: 代码影响范围、API 变更、数据库变更、风险评估
type: impact-analysis
---

# 影响分析：文件预览语法高亮

## 1. 代码影响矩阵

| 模块 | 文件/类 | 变更类型 | 影响级别 | 备注 |
|------|---------|---------|---------|------|
| **前端 - 组件** | `web/src/features/skill/code-renderer.tsx` | 新增 | 低 | 新增组件，无依赖冲突 |
| **前端 - 工具** | `web/src/features/skill/file-type-utils.ts` | 修改 | 低 | 新增函数，不修改现有函数 |
| **前端 - 弹窗** | `web/src/features/skill/file-preview-dialog.tsx` | 修改 | 中 | 修改渲染逻辑，需回归测试 |
| **前端 - 样式** | `web/src/features/skill/markdown-renderer.tsx` | 只读 | 无 | 复用样式，不修改 |
| **前端 - 依赖** | `web/package.json` | 无变更 | 无 | 复用现有 highlight.js |
| **后端 - API** | 无 | 无变更 | 无 | 复用现有文件读取 API |
| **后端 - 缓存** | 待定 | 后续新增 | 低 | 后续优化阶段实现 |
| **后端 - 限流** | 待定 | 后续新增 | 低 | 后续优化阶段实现 |

## 2. API 影响

### 新增端点
无

### 修改端点
无（复用现有 API）

### 现有端点依赖
| 端点 | 变更 | 是否破坏性 | 备注 |
|------|------|-----------|------|
| `GET /api/v1/reviews/{id}/file?path={filePath}` | 无变更 | 否 | 前端根据响应内容渲染 |
| `GET /api/v1/skills/{namespace}/{slug}/versions/{version}/file?path={filePath}` | 无变更 | 否 | 前端根据响应内容渲染 |

## 3. 数据库影响

### 模式变更
无

### 数据迁移
无

## 4. 前端影响

### 受影响页面
| 页面 | 影响描述 | 测试重点 |
|------|---------|---------|
| 技能详情页 | 文件预览弹窗增强 | 各种文件类型渲染测试 |
| 审核详情页 | 文件预览弹窗增强 | 各种文件类型渲染测试 |

### i18n 变更
无新增翻译键（复用现有错误提示）

### 路由变更
无

## 5. 风险评估

| 风险 ID | 描述 | 概率 | 影响 | 缓解措施 |
|---------|------|------|------|---------|
| R-001 | 大文件语法高亮导致浏览器卡顿 | 中 | 高 | 设置 500KB 阈值，超过则不高亮 |
| R-002 | highlight.js 包体积过大 | 低 | 中 | 按需导入语言包，初始只加载核心 |
| R-003 | 语法高亮样式与 Markdown 不一致 | 低 | 中 | 复用相同的 CSS 类名和样式 |
| R-004 | 某些语言无法识别 | 低 | 低 | 降级到纯文本显示，不报错 |
| R-005 | 渲染失败导致页面崩溃 | 低 | 高 | 使用 Error Boundary 捕获错误 |
| R-006 | 主题切换时样式闪烁 | 低 | 低 | 使用 CSS 变量，确保平滑过渡 |
| R-007 | 后端文件读取性能下降 | 中 | 中 | 后续实现缓存和限流（不在本次范围） |
| R-008 | XSS 安全风险 | 低 | 高 | 确保 highlight.js 输出已转义 |

### 风险详细说明

#### R-001: 大文件语法高亮导致浏览器卡顿
- **触发条件**：用户尝试预览 > 500KB 的代码文件
- **影响范围**：前端渲染性能，用户体验
- **缓解措施**：
  1. 设置 500KB 阈值，超过则显示纯文本
  2. 增加 loading 状态提示用户
  3. 提供"取消加载"按钮（后续优化）
- **监控指标**：前端渲染时间（通过 RUM）

#### R-005: 渲染失败导致页面崩溃
- **触发条件**：highlight.js 渲染异常、内存不足
- **影响范围**：文件预览功能不可用
- **缓解措施**：
  1. 使用 React Error Boundary 捕获渲染错误
  2. 降级到纯文本显示
  3. 记录错误日志，便于排查
- **监控指标**：错误率（通过前端错误监控）

#### R-007: 后端文件读取性能下降
- **触发条件**：大量用户同时预览文件
- **影响范围**：后端 API 响应时间增加，云存储 API 配额消耗
- **缓解措施**：
  1. 后续实现 Redis 缓存（缓存命中率 > 60%）
  2. 后续实现限流（认证用户 60 次/分钟，匿名 20 次/分钟）
  3. 监控云存储 API 调用次数
- **监控指标**：API 响应时间、缓存命中率、限流触发次数

#### R-008: XSS 安全风险
- **触发条件**：恶意用户上传包含 XSS 代码的文件
- **影响范围**：安全漏洞，可能导致用户信息泄露
- **缓解措施**：
  1. 确保 highlight.js 输出已转义（highlight.js 默认转义）
  2. 代码审查确认 `dangerouslySetInnerHTML` 使用安全
  3. 不允许用户自定义语法高亮规则
- **监控指标**：安全审查通过

## 6. 测试影响

### 新增测试
| 测试类 | 覆盖用例 | 描述 |
|--------|---------|------|
| `CodeRenderer.test.tsx` | AC-P-001 ~ AC-P-005 | CodeRenderer 组件单元测试 |
| `file-type-utils.test.ts` | AC-P-006 | 语言映射函数测试 |
| `file-preview-dialog.test.tsx` | AC-P-007 ~ AC-P-010 | 文件预览弹窗集成测试 |

### 修改测试
| 测试类 | 修改原因 | 描述 |
|--------|---------|------|
| `file-preview-dialog.test.tsx` | 新增渲染逻辑 | 更新快照，增加语法高亮测试用例 |

## 7. 部署影响

### 前端部署
- **构建时间**：预计增加 10-20 秒（新增组件编译）
- **包体积**：预计增加 50-80KB（gzipped，按需导入语言包）
- **缓存失效**：文件预览相关页面缓存失效，需重新加载

### 后端部署
- **本次无变更**
- **后续优化**：需要部署缓存和限流逻辑（独立任务）

### 数据库部署
无

## 8. 回滚计划

### 回滚触发条件
- 前端渲染错误率 > 5%
- 用户投诉语法高亮功能异常 > 10 次/天
- 性能指标严重下降（P95 响应时间 > 3s）

### 回滚步骤
1. **前端回滚**：
   - 回滚到上一个稳定版本（git revert）
   - 重新构建和部署前端
   - 验证文件预览功能恢复正常（显示纯文本）
2. **监控验证**：
   - 确认错误率恢复正常
   - 确认性能指标恢复正常
3. **问题排查**：
   - 分析错误日志，定位问题根因
   - 修复问题后重新部署

### 回滚影响
- 用户将无法使用语法高亮功能，回退到纯文本显示
- 不影响文件下载和其他核心功能

---

## 变更日志
| 日期 | 章节 | 变更 | 原因 | 触发者 |
|------|------|------|------|--------|
| 2026-03-22 | 初始版本 | 创建影响分析文档 | 需求澄清完成 | requirements-clarity |