code-reviewer

Skill: Code Reviewer

审查 AI 生成的代码，基于 OpenLogos 全链路规格（API YAML、时序图 EX 用例、DB DDL）进行系统性校验，确保代码与设计文档完全一致，覆盖所有异常路径，满足安全要求。

触发条件

• 用户要求审查代码或 Code Review
• 用户提到 "Phase 3 Step 5"、"代码审核"、"代码审查"
• AI 刚生成了一段代码，需要验证其质量
• 部署前的最终检查
• 编排测试失败后需要定位代码问题

前置依赖

• logos/resources/api/ 中包含 API YAML 规格
• logos/resources/prd/3-technical-plan/2-scenario-implementation/ 中包含场景时序图（含 EX 用例）
• logos/resources/database/ 中包含 DB DDL
• 待审查的代码已可读取

无 API 的项目（纯 CLI / 库）可省略 API 一致性检查，聚焦时序图覆盖和异常处理。

核心能力

1. 校验代码实现与 API YAML 规格的一致性
2. 检查异常处理是否覆盖所有 EX 用例
3. 检查 DB 操作是否符合 DDL 设计
4. 检查安全策略（认证、RLS、输入校验）
5. 检查代码风格和最佳实践
6. 输出结构化的审查报告

执行步骤

Step 1: 加载规格上下文

前置检查 — YAML 有效性（优先于一切）：

在加载 API 规格之前，先验证所有 logos/resources/api/*.yaml 文件是否为有效 YAML 且符合 OpenAPI 3.x 规范。如果任何文件解析失败（例如 description 字段中特殊字符未加引号），立即报告为 Critical 阻塞项——在 YAML 错误修复前不进行后续审查。

然后读取以下文件，建立代码审查的"参照基准"：

• API YAML（logos/resources/api/*.yaml）：提取端点清单，记录每个端点的路径、方法、请求体 schema、响应 schema、状态码
• 场景时序图（logos/resources/prd/3-technical-plan/2-scenario-implementation/）：提取所有 EX 异常用例编号和预期行为
• DB DDL（logos/resources/database/）：提取表结构、字段类型、约束、索引
• logos-project.yaml：读取 tech_stack 确认技术栈，external_dependencies 确认外部依赖

汇总为审查检查清单：

审查范围：S01 相关代码
- API 端点：4 个（auth.yaml）
- EX 异常用例：7 个（EX-2.1 ~ EX-5.2）
- DB 表：2 张（users, profiles）
- 安全策略：RLS 2 条

Step 2: API 一致性审查

逐个端点对比代码实现与 API YAML 规格：

检查项：

检查项	说明	严重程度
路径匹配	代码中的路由路径是否与 YAML 中的 paths 完全一致	Critical
HTTP 方法	GET/POST/PUT/DELETE 是否匹配	Critical
请求体字段	代码是否读取了 YAML 中 requestBody.schema 定义的所有 required 字段	Critical
请求体校验	字段类型、format（email/uuid）、minLength 等约束是否在代码中有校验	Warning
响应字段	代码返回的 JSON 字段名和类型是否与 YAML 中 responses.schema 一致	Critical
状态码	正常和异常情况下返回的 HTTP 状态码是否与 YAML 定义一致	Critical
错误响应格式	错误响应是否遵循 { code, message, details? } 统一格式	Warning
YAML 有效性	logos/resources/api/*.yaml 所有文件是否为有效 YAML 且符合 OpenAPI 3.x 规范——description/summary 值中未加引号的特殊字符（:、→、#）是常见故障点	Critical

输出格式：

### API 一致性

| 端点 | 检查项 | 状态 | 说明 |
|------|--------|------|------|
| POST /api/auth/register | 请求体字段 | ✅ | email, password 均已读取 |
| POST /api/auth/register | 响应状态码 | ❌ Critical | 注册成功返回 200，YAML 定义为 201 |
| POST /api/auth/register | 错误码 | ❌ Warning | 邮箱重复返回通用 400，YAML 定义为 409 |

Step 3: 异常处理覆盖审查

将时序图中的所有 EX 异常用例与代码中的错误处理逐一对应：

1. 列出该场景所有 EX 编号及其预期行为
2. 在代码中查找对应的 try/catch、if/else、error handler
3. 标注未覆盖的 EX 用例

检查重点：

• 每个 EX 用例是否有对应的代码分支
• 异常情况下是否返回了正确的 HTTP 状态码和错误码
• 是否有"静默吞掉异常"的情况（catch 块为空或只打日志不返回错误）
• 外部服务调用（DB、第三方 API）是否都有超时和错误处理
• 是否存在时序图中没有但代码中多出的异常处理（可能意味着时序图遗漏）

输出格式：

### 异常处理覆盖

| EX 编号 | 异常描述 | 代码覆盖 | 说明 |
|---------|---------|---------|------|
| EX-2.1 | 邮箱已注册 | ✅ | 返回 409，格式正确 |
| EX-2.2 | Auth 服务不可用 | ❌ Critical | 无 try/catch 包裹 supabase.auth.signUp 调用 |
| EX-4.1 | profiles 写入失败 | ❌ Critical | INSERT 失败后未回滚 auth.users 记录 |

Step 4: DB 操作审查

检查代码中的数据库操作是否符合 DDL 设计：

检查项：

• 表名和列名：代码中引用的表名/列名是否与 DDL 一致（无拼写错误、大小写差异）
• 字段类型：代码中传入的值类型是否与 DDL 定义匹配（如 DDL 中 INTEGER 的金额字段，代码是否传入分值而非元）
• 约束遵守：NOT NULL 字段是否确保有值、UNIQUE 字段是否做了冲突处理、CHECK 约束中的枚举值是否在代码中有对应常量
• 事务使用：涉及多表写入的操作是否包裹在事务中
• 迁移一致：DDL 中的最新字段是否在代码中已使用（避免 DDL 更新了但代码忘记跟进）

Step 5: 安全审查

检查代码的安全实现：

检查项	说明	严重程度
认证检查	需认证的端点是否在处理逻辑前验证了 token/session	Critical
授权检查	用户是否只能访问自己的数据（owner check）	Critical
输入校验	用户输入是否做了类型校验和长度限制（防注入、防 XSS）	Critical
敏感数据	响应中是否泄露了密码哈希、内部 ID、堆栈信息	Critical
RLS 依赖	如果依赖 PostgreSQL RLS，代码是否正确设置了 auth.uid() 上下文	Warning
SQL 注入	是否使用参数化查询（禁止字符串拼接 SQL）	Critical
速率限制	关键端点（登录、注册）是否有防暴力破解的速率限制	Warning

Step 6: 输出审查报告

按严重程度汇总所有发现，生成结构化报告：

# 代码审查报告：S01 用户注册

## 审查范围
- 场景：S01
- 端点：4 个
- EX 用例：7 个
- 代码文件：src/api/auth/register.ts, src/api/auth/login.ts

## 审查摘要

| 严重程度 | 数量 |
|---------|------|
| ? Critical | 2 |
| ? Warning | 3 |
| ? Info | 1 |

## Critical 发现

### [C1] POST /api/auth/register 状态码不匹配
- **规格来源**：auth.yaml → register → responses.201
- **问题**：代码返回 200，规格定义为 201
- **修复建议**：将 `res.status(200)` 改为 `res.status(201)`

### [C2] EX-2.2 未处理：Auth 服务不可用
- **规格来源**：S01 时序图 → EX-2.2
- **问题**：`supabase.auth.signUp()` 调用未包裹 try/catch
- **修复建议**：添加 try/catch，超时或 5xx 时返回 503

## Warning 发现
...

## Info 发现
...

报告原则：

• Critical 必须修复后才能进入编排验收
• Warning 建议修复，但不阻塞交付
• Info 为改进建议，可后续处理
• 每条发现都必须引用规格来源（API YAML、EX 编号、DDL）

输出规范

• 审查报告直接输出到对话中（不写文件）
• 按严重程度分类：Critical / Warning / Info
• 每条发现格式：编号 + 规格来源 + 问题描述 + 修复建议
• 末尾给出总结和下一步建议（如"修复 2 个 Critical 后可运行编排验收"）

实践经验

• 一致性优先：代码必须与 API YAML 完全一致——字段名、类型、状态码都不能偏差。大部分线上 Bug 来自代码和规格的微妙不一致
• 异常处理是重点：大部分 Bug 都出在异常路径上，仔细检查每个 EX 用例是否有对应的 catch/error handler
• 安全不打折：认证检查、RLS 策略、输入校验，任何一项缺失都是 Critical
• 不要过度审查：代码风格问题标记为 Info，不阻塞交付。审查的核心目标是"代码与规格一致"，不是"代码完美"
• 审查前先跑一遍：如果代码能跑起来，先运行一次编排测试，用失败的 case 反向定位问题，比逐行看代码高效
• 关注补偿逻辑：多步写入（如先创建 auth user 再写 profile）如果中途失败，是否有回滚或补偿机制——这是最容易遗漏的 Critical 问题

推荐提示词

以下提示词可以直接复制给 AI 使用：

• 帮我做代码审查
• 帮我检查这段代码是否符合 API YAML 规格
• Review 一下 S01 相关的代码实现
• 帮我检查异常处理是否完整
• 帮我检查安全策略是否到位