前端代码评审

评审模式与覆盖范围

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

• 改动审核：仅在明确要求或当前任务已明确最近改动、本次修改、暂存区、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。发现必须具体且可操作；不要写"优化性能"等空泛建议而不指出具体代码模式。

约束

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

预期输出

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

重构边界

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