code-review

代码审查

正确性与安全性门禁。仅报告有充分把握的问题：只标记确定的问题。如有歧义，默认选择“要求修改”。结构性问题（内聚性、抽象层级、循环依赖、死代码）属于结构审查；此处只审查正确性与安全性。

如果仓库针对其技术栈规则（包管理器、CSS 框架、框架版本、UI 库）设有自动合规检查，不要重复标记这些检查已覆盖的问题。

范围

• 输入： 一个差异、分支或 PR。使用只读的 git 和 gh 命令确定范围。
• 输出： 按阻止合并 / 要求修改 / 批准分类的问题列表，每项包含文件、行号和一句话理由，另附单独的 Spec 报告。
• 只读： 此技能只报告问题。不会编辑文件、创建 PR、修改任何内容或部署。所有输出仅供参考；无需确认。
• 边界： 仅针对单个差异或 PR。不要重新审查结构性方面（模块内聚性、抽象层级、循环依赖、引入死代码、API 表面膨胀、架构适配性）；这些应交由结构审查处理。指出差异中明显的安全问题，但不要尝试进行全面审计（OWASP 检查、依赖项 CVE、时序攻击、权限提升路径）；这些应交由专门的安全审计处理。如果问题涉及模块层级或连接点位置，建议进行代码库设计审查。绝不要根据审查请求推断应执行合并或清空队列。

两个维度

以下检查清单属于 Standards 维度（正确性、安全性、仓库规范）。同时执行 Spec 维度，避免遵循所有规范却实现错误内容的变更蒙混过关，也避免符合问题要求却违反约定的变更蒙混过关。

• 遵循所有规范但实现了错误内容：Standards 通过，Spec 不通过。
• 完全按问题要求实现，但违反项目约定：Spec 通过，Standards 不通过。

分别在 ## Standards 和 ## Spec 下报告。不要合并两个维度的问题，也不要跨维度重新排列优先级。

Spec 维度步骤

1. 确定固定点。 用户指定的内容即为固定点：一个提交 SHA、分支、标签、main、HEAD~5。如果用户未指定，请先询问。确认该引用可解析，且差异非空（git diff <fixed-point>...HEAD），然后再开始审查。

2. 确定规格来源，按以下顺序查找：

   1. 提交消息中的 Issue 引用（#123、Closes #45），通过 gh 获取。
   2. 用户作为参数传入的路径。
   3. docs/、specs/ 下的规格文件，或与分支匹配的 Issue 正文。
   4. 如果未找到任何内容，请先询问。如果没有规格，跳过 Spec 维度，并报告“没有可用的规格”。

3. 报告规格问题：

   • 规格要求但缺失或未完整实现的内容
   • 差异中未经要求的行为（范围蔓延）
   • 看似已实现但实现方式有误的要求

   每个问题都要引用对应的规格原文行。遗漏会导致必需行为缺失的规格要求，属于阻止合并。除非用户已接受范围蔓延，否则将其列为要求修改。

关键检查清单（Standards 维度）

1. 安全与数据隔离

• 所有查询都按租户 / 组织过滤（若为多租户）
• 所有查询都过滤软删除记录（若适用）
• 不存在跨租户数据访问
• 受保护路由设有身份验证防护
• 不存在非预期的公开端点：每条路由的身份验证策略都经过有意设计
• 通过 DTO / schema 验证输入
• 不得提交或记录秘密、令牌或凭据

2. TypeScript

• 不使用 any 类型：在 *.types.ts 中定义恰当的接口或命名类型
• 不使用没有类型守卫的裸 unknown（裸 unknown 相当于延迟使用的 any）
• 不使用没有解释性注释的 as X 类型断言
• 接口/props 应放在专用文件中，而非内联在组件或服务文件中
• 所有函数都应声明返回类型
• 不使用 console.log：改用项目日志记录器（LoggerService、pino、winston）
• 不使用没有解释性注释的 @ts-ignore 或 @ts-expect-error

3. 模式合规性

• 遵循现有代码库模式（提出问题前，先核实至少 3 个真实示例）
• 优先使用路径别名，而非相对导入

4. 数据库

• 所有查询都包含租户/组织筛选条件（如适用）
• 所有查询都包含软删除筛选条件（如适用）
• 对大型文档使用投影
• 查询模式对应的索引均已创建
• 差异中没有明显的 N+1 查询
• 如果顺序执行的 await db.update() 调用在失败时可能导致数据库只写入一部分内容，则必须将其放入事务中，或合并为一次原子写入

5. 错误处理

• 包含 try/catch 代码块
• 使用框架专用异常（而非通用 Error）
• 通过日志服务记录错误
• 向客户端返回通用消息（不暴露内部信息）

6. 测试

• 存在单元测试且测试通过
• 测试所有公共方法
• 测试错误场景
• 测试应断言行为，而不只是验证代码能运行（避免空洞的快照测试）

7. 前端

• 对包含异步调用的 useEffect 执行清理（使用 AbortController）
• 处理加载和错误状态
• 添加交互元素时使用语义化 HTML，并提供 ARIA 标签

8. API

• 使用恰当的 HTTP 状态码
• 为请求/响应定义 DTO
• 项目使用 API 文档装饰器时，应添加相应装饰器（例如 @ApiOperation / @ApiResponse）
• 不向 API 使用者泄露内部堆栈跟踪

9. 开发体验（Devex）回退

会悄然破坏其他工程师本地开发循环的变更：

• 环境变量重命名或新增： 是否更新了 .env.example / .env.template？是否公布了重命名信息（迁移说明、变更日志或 PR 描述）？
• 密钥读取变更： 是否在运行时访问了文档所述配置流程中未提及的新密钥？或者是否将访问路径从一个提供方/保管库切换到另一个，却未更新运行手册？
• 端口或网络映射变更： 服务、开发服务器或 docker-compose 端口变更后，是否更新了 README/设置文档和所有依赖配置文件？
• 新增强制设置脚本： 是否必须在应用启动前运行迁移、填充或一次性引导脚本，却未在 PR 描述或设置指南中说明？
• 构建流程变更： 是否新增了必需的构建步骤、更改了输出目录，或在 package.json 中添加了前置/后置脚本，从而破坏现有的开发/构建约定，却没有明确的迁移说明？

未公布的开发体验回退会阻止合并。若变更已有文档说明，但文档位置不正确，则要求修改。

10. 功能标志/门控泄漏

原本应受门控的功能未设置标志或仅部分设置标志便发布：

• 明显泄漏： PR 描述称新增路由、组件或 API 端点受某个标志控制，但缺少标志检查，或只在 UI 中检查，未在 API 处理程序中检查
• 隐蔽泄漏： 正常流程中有标志检查，但错误处理程序、后台任务或调用同一服务方法的管理员专用路径中没有
• 始终启用的常量： 用 const ENABLE_NEW_CHECKOUT = true 代替真正的标志评估；这种做法永远不会被清理，并且绕过了标志服务
• 引入标志但没有清理计划： 没有关联的问题单或用于移除标志的 TODO 注释；标志名称应清楚表明其预期生命周期
• 发布配置不一致： PR 中定义了标志，但缺少发布百分比/目标规则，或默认值为 100%，使门控失去意义

会向所有用户公开未发布功能的标志泄漏属于阻止合并的问题。缺少清理问题单则应“要求修改”。

审批标准

阻止合并

• 存在安全问题
• 缺少租户／组织筛选（如有要求）
• 使用了 any 类型，或使用裸 unknown 却没有类型守卫
• 测试失败，或新增的公共方法完全没有测试
• 构建失败
• 功能标志泄漏，暴露了尚未发布的功能
• 未说明的开发体验回退（环境、端口或构建契约损坏）
• 多步数据库变更不是原子操作，且没有事务

请求修改

• 新增环境变量或设置脚本要求缺少文档
• 差异中明显存在性能问题（N+1 查询、缺少索引）
• 违反代码模式（已导入 UI 库的文件中使用原始 HTML）
• 引入功能标志，却没有清理问题或 TODO
• 测试空洞，只断言执行过程而非行为

批准

• 所有安全检查均通过
• 测试通过，且断言了实际行为
• 遵循代码库模式
• 已记录开发体验影响
• 功能标志有清理计划
• 规格检查项通过，或因不存在规格而跳过

契约

输入：

• 一个待审查的差异、分支或 PR。通过只读 git／gh 命令收集范围信息。

输出：

• 按阻止合并／请求修改／批准分类的问题列表；每项都包含文件、行号和一句话理由。
• 除检查清单外，还要提供一份 规格 报告：指出相对于原始问题缺少的要求、范围蔓延和错误实现。两个维度应分开处理，避免其中一个掩盖另一个。

创建／修改：

• 无。此技能仅提供报告；不会编辑文件或创建 PR。

外部副作用：

• 仅调用只读 git 和 gh 命令。不进行修改，也不部署。

需要确认：

• 无。所有输出仅供参考。

委派给：

• 无。对于此门禁范围之外的问题，建议进行结构、安全或代码库设计审查（例如，已安装时使用上游 pstack 工作流）。