Fec Code Review

---
name: fec-code-review
description: 用于用户要求通用前端代码评审、PR 评审、合并就绪评估、架构可维护性、类型安全、渲染/状态风险、样式一致性、可测性缺口或横向评审总结时。深度安全、无障碍、E2E 或性能问题应委托对应专项 skill；中文触发词包括 代码审查、代码评审、review。
---

# 前端代码评审

## 评审模式与覆盖范围

用户明确指定的范围优先于默认行为。采用以下三种审核模式：

- **改动审核**：仅在明确要求或当前任务已明确最近改动、本次修改、暂存区、PR 或提交上下文时，审核这些改动及必要上下文。本地模式在请求范围内检查暂存、未暂存差异及相关未跟踪项目文件；仅要求暂存区时只审核暂存改动。无改动时说明没有可审核的改动，不自动切换到最近提交或扩大范围。
- **指定范围审核**：用户指定文件或目录时，建立范围内文件清单，审核其中现有代码，包括未改动代码；不要求 Git 差异。
- **全项目审核（默认）**：未指定范围或改动上下文，或明确要求审核整个项目时，建立项目自有前端代码、相关测试、配置和依赖声明的清单，再按模块分批审核，包括未改动代码；不要求 Git 差异。

先选择范围，再收集差异。仅指定文件或目录表示全量审核该范围；路径与明确改动请求同时出现时，仅增量审核该路径的改动。未限定的调用即使存在 Git 改动也默认全项目审核。开始审核时说明选定模式和目标范围。修改后自动委托审核时，显式传入本次改动范围，避免无范围调用触发全项目审核。

默认排除依赖目录、构建产物、缓存、生成文件和第三方代码，并记录排除项。保持前端职责边界，不宣称完成后端专项审核。目标不存在或范围内无相关文件时，明确说明，不替换为其他范围。

跨批次合并同根因发现。报告记录**审核模式、目标范围、已审核文件或模块、排除项、未覆盖文件或模块、完成状态及验证命令和结果**。受上下文或执行预算限制时，标记部分完成并列出剩余模块，不宣称已完成全项目覆盖。为理解上下文而读取调用方或执行全项目 lint/类型检查，不计为完成这些文件的人工审核。

改动审核保留合并建议；指定范围和全项目审核使用风险评估（低 / 中 / 高，并标明阻塞问题），不宣称合并就绪。保留严重程度、证据要求和报告文件命名。除非用户明确要求修复，否则仅输出报告。

## 用途

从架构、类型安全、可访问性、样式一致性、性能和可测试性等 8 个维度审查前端代码质量，输出分级评审报告。

## 流程

1. 先读项目事实：package scripts、框架、目录约定、最近 diff、现有测试和相关规则。
2. 按风险找问题，而不是按个人偏好挑风格；每个发现都要能指向具体文件、行号和用户影响。
3. 用五轴收敛结论：正确性、可维护性、类型/接口、用户体验、验证覆盖。
4. 对安全、无障碍、E2E、性能等深水区只做初筛；需要专项调查时明确分流。
5. 多维评审时先按职责拆分，再合并同类发现；同一文件同一根因只保留一条主发现，避免重复噪声。
6. 报告先列阻塞问题，再列建议项；没有证据的问题不要写成确定结论。

## 多维评审编排

当改动跨越多个质量维度时，按“主评审 + 专项分流”组织，而不是让所有维度重复检查同一处代码。

| 维度                | 触发条件                                             | 分流边界                             |
| ------------------- | ---------------------------------------------------- | ------------------------------------ |
| TypeScript 工程与类型契约 | DTO、泛型、公共类型、类型守卫、`any`、断言、tsconfig | 深入类型建模和 TS 配置交给 TypeScript 流程 |
| 状态管理            | 状态归属、全局 store、URL 状态、派生状态、跨页面同步 | 状态选型与迁移交给状态管理专项流程   |
| 安全                | 用户输入、HTML 渲染、token、上传、第三方脚本         | 漏洞级分析交给安全专项流程           |
| 无障碍              | 弹窗、菜单、表单、键盘操作、焦点管理                 | WCAG 细查交给无障碍专项流程          |
| 性能                | 大列表、重依赖、重复请求、长任务、包体积             | 性能证据与预算交给性能专项流程       |
| E2E                 | 关键用户路径、登录态、支付、跨页面流程               | 浏览器用例与 trace 交给 E2E 专项流程 |

发现合并规则：

- 同一根因出现在多个维度时，只保留最高严重级别，并在 `Dimension` 中列出相关维度。
- 同一文件多处重复模式，合并为一条模式级发现，列出代表性位置。
- 置信度不足的问题放入 Open Questions，不升级为阻塞项。
- 自动化可稳定捕获的格式问题交给 lint/format，不作为人工评审主发现。

## 评审维度

1. 架构

- 组件边界是否清晰
- 展示逻辑与业务逻辑是否分离
- 是否有可复用抽象
- 是否存在上帝组件

2. 类型安全

- 是否存在不必要的 `any`
- props 类型是否明确
- hooks/composables 返回值是否稳定
- 在可行情况下 API 契约是否有类型约束

3. 渲染与状态

- 是否存在不必要的重复渲染
- key 的使用是否稳定
- 可推导状态是否被重复存储
- 本地状态是否耦合过深
- 全局 store 是否只保存真正跨边界共享的客户端状态
- URL 状态、服务端状态、表单状态和浏览器持久化是否边界清晰

4. 样式

- 已有 Token 时是否还在使用 magic number
- 类名是否与仓库约定一致
- 响应式处理是否明确
- 是否无必要地混用了多套样式体系

5. 可访问性

- 语义结构是否合理
- 是否在需要时正确使用 label 和 aria
- 是否支持键盘操作
- 浮层和菜单的焦点管理是否正确

6. 可维护性

- 组件/页面文件规模是否合理（宜约 **300 行**内；逾 **500 行**或复杂度过高须拆分，见共享 React / Vue 规则中的「组件文件规模」）
- 命名质量是否良好
- 是否有应该提取的重复逻辑
- 是否存在死代码、过期注释或临时性 hack
- 业务状态、类型、标识是否用裸数字/裸字符串（应对齐 `templates/shared/rules/fec-typescript.md`「禁止 Magic Number / Magic String」）

7. 测试

- 是否缺少关键测试覆盖
- 是否存在脆弱的选择器或不稳定的测试模式

8. 安全

- 无明显 XSS 风险（dangerouslySetInnerHTML / v-html 必须审查）
- 无敏感信息硬编码
- 无未校验的用户输入直接渲染

9. 性能与体验证据

- 是否引入首屏重依赖、重复请求、大列表渲染或长任务
- loading、empty、error、disabled、focus 等状态是否完整
- 响应式布局是否有可验证断点和文本溢出保护

10. 必检项（阻塞合并）

- [ ] TypeScript 类型完整，无 `any`
- [ ] 外部输入、DTO、公共类型边界无无守卫断言
- [ ] 无 XSS 风险
- [ ] 无敏感信息硬编码
- [ ] 核心逻辑有单元测试

11. 质量项（建议修改）

- [ ] 组件文件规模符合约定（约 300 行内为佳；逾 500 行或高复杂度已拆子组件 / Hooks / Composables / utils）
- [ ] 无重复代码（DRY 原则）
- [ ] 无未使用的 import

12. 规范项（风格建议）

- [ ] 命名语义清晰
- [ ] 注释覆盖复杂逻辑

## 详细参考

撰写代码评审报告时，加载 [references/report-template.md](references/report-template.md)。发现必须具体且可操作；不要写"优化性能"等空泛建议而不指出具体代码模式。

## 约束

- 不把个人风格偏好写成阻塞问题；阻塞项必须有明确用户影响、运行时风险、安全风险或维护成本证据。
- 缺少文件位置和支持证据时，不要给出确定结论；仅改动审核要求差异。
- 深度安全、无障碍、E2E 和性能问题只做初筛；需要证据链时分流到专项 skill。
- 同一根因不要重复报多条；合并为一条代表性发现并列出影响范围。
- 自动化工具稳定覆盖的格式问题交给 lint/format，不作为人工评审主发现。

## 预期输出

- 分级评审报告（CRITICAL / HIGH / MEDIUM / LOW）
- 每个问题关联具体文件和行号，附修复建议
- 阻塞项（CRITICAL）修复前不建议合并
- 评审报告保存为 `reports/code-review-YYYY-MM-DD-HHmmss.md`
- 多维评审要合并重复发现，并说明已分流到哪些专项能力
- 对不确定项标注需要的验证命令或补充上下文，不把猜测写成事实
## 重构边界

通用 Review 可以发现可维护性证据，但需要系统判断结构问题时，应交给坏味道诊断；需要形成保持行为的有序变化方案时，应交给重构计划。Review 不应静默执行结构修改。