/pdlc-review

name: pdlc-review
description: 代码评审 + 文档评审
argument-hint: <功能ID | PR 描述>
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
layer: 2
stage: review
produces:
  - docs/07_reviews/**
requires: []
next_step: pdlc-ship
terminal_state: review_done
recommended_model: sonnet
recommended_effort: medium

代码评审

<!-- @include templates/prompts/iron-law.md --> <!-- @include templates/prompts/noninteractive.md -->

对指定的服务或应用进行全面的代码评审。

PDLC 前置检查（必须执行，不可跳过）

1. 从用户输入中提取功能名称关键词 2. **检查实现代码是否存在**：在 `backend/` 和 `frontend/` 下搜索与该功能相关的源代码文件（非测试文件） 3. **检查测试是否通过**：找到对应的测试代码并运行，确认测试处于**绿灯状态**（全部通过） 4. **未找到实现代码** → 输出以下信息后**立即停止，不继续执行**：

   ⛔ PDLC 守卫：未找到与「<功能名>」相关的实现代码。
   评审必须基于已有的代码实现。请先运行：
   👉 /pdlc-implement <目标>

5. **测试未通过** → 输出以下信息后**立即停止，不继续执行**：

   ⛔ PDLC 守卫：「<功能名>」的测试未全部通过，无法进行评审。
   请先确保所有测试通过后再提交评审：
   👉 /pdlc-implement <目标>（修复失败的测试）

6. **检查通过** → 提取功能ID（从相关设计文档或 PRD 中），继续执行

评审流程

1. **阅读设计文档**: 先阅读 `docs/02_design/` 对应子目录下的相关设计文档 2. **阅读编码规范**: 阅读 `docs/00_standards/coding/` 目录了解编码规范（未命中 → 报告里提示 `consider /pdlc-standard add coding/<topic>`） 3. **检查代码实现**: 对照设计文档逐一检查实现是否符合 4. **检查测试覆盖**: 确认测试是否充分覆盖 5. **代码质量自动检查与修复**（必须执行）：

• 按 `/pdlc-lint check` 逻辑运行项目 lint 工具
• 若存在可自动修复的问题，按 `/pdlc-lint fix` 逻辑自动修复
• 记录修复前后的问题数变化

评审检查项（逐项检查，发现问题立即修复）

设计一致性（对照设计文档）

• [ ] 每个 API 接口的 URL、方法、参数是否与设计文档一致
• [ ] 数据库表结构、字段名、类型是否与 DB 设计一致
• [ ] 响应格式是否统一遵循 `{ code, message, data }`

代码质量

• [ ] 命名是否规范（变量/函数/类遵循项目命名约定）
• [ ] 是否有重复代码可提取为公共方法
• [ ] 错误处理是否合理（不吞异常、不用空 catch、有意义的错误信息）
• [ ] 日志是否充分（关键操作有日志、不打印敏感信息）

安全检查

• [ ] SQL 注入：是否使用参数化查询/ORM，无字符串拼接 SQL
• [ ] XSS：用户输入是否转义后再输出
• [ ] 权限控制：接口是否有鉴权，敏感操作是否有权限校验
• [ ] 敏感数据：密码是否加密存储、Token 是否有过期机制、日志不含敏感字段

性能检查

• [ ] 数据库查询是否有 N+1 问题
• [ ] 列表接口是否有分页
• [ ] 是否有不必要的全表扫描（缺失索引）
• [ ] 大数据量操作是否有批处理

测试完备性

• [ ] 单元测试覆盖率是否达标（覆盖率达标线**以项目配置为准**：优先取 `docs/00_standards/test-commands.yml` 的 coverage 命令阈值参数（那才是强制点，退出码即判定），其次 `quality-targets.yml`；两者都没有时按 >= 80% 兜底。）
• [ ] 核心业务路径是否有完整的测试
• [ ] CHANGELOG 是否已更新

自动修复（评审中发现的问题，能修则修）

对以下类型的问题**直接修复代码，不仅仅记录**：

1. **lint 问题**：运行 lint fix 自动修复格式、规范问题 2. **命名不规范**：自动重命名为符合项目约定的名称 3. **缺失错误处理**：自动补充 try-catch / 错误码返回 4. **缺失日志**：在关键操作处自动添加日志语句 5. **SQL 注入风险**：自动改写为参数化查询 6. **XSS 风险**：自动添加输出转义 7. **缺失分页**：自动为列表接口补充分页逻辑 8. **缺失 CHANGELOG**：自动追加变更条目

**不可自动修复的问题**（记录到评审报告，标记为需人工处理）：

• 架构层面的设计问题
• 业务逻辑的正确性争议
• 需要重大重构的性能问题

评审报告生成

> ⚠️ **必须创建文件，不可仅在对话中输出。**

**【必须创建文件】** 在 `docs/07_reviews/code/` 下创建评审记录：

• **文件名格式**: `<功能ID>-<功能名>-review.md`（如 `F20260326-090000-user-auth-review.md`）
• **文档顶部必须包含 PDLC 追溯头**：

  <!-- PDLC-TRACE -->
  <!-- 功能ID: F20260326-090000 -->
  <!-- 功能名称: user-auth -->
  <!-- 阶段: 评审 -->
  <!-- 前置文档: docs/02_design/api/F20260326-090000-user-auth-api.md -->
  <!-- 创建时间: 2026-03-26T10:30:00 -->

• **报告内容格式**：

  ## 评审总结
  - 评审时间：<ISO 8601>
  - 评审范围：<涉及的文件数和代码行数>
  - 问题总数：X 项（阻塞: X / 严重: X / 一般: X / 建议: X）
  - 自动修复：X 项
  - 需人工处理：X 项

  ## 自动修复记录
  | # | 问题类型 | 文件 | 修复内容 |
  |---|---------|------|---------|
  | 1 | lint | src/xxx.ts | 修复 XX 规则违规 |

  ## 需人工处理
  | # | 严重程度 | 问题描述 | 建议方案 |
  |---|---------|---------|---------|
  | 1 | 阻塞 | XXX | 建议 XXX |

  ## 评审检查项结论
  - [x] 设计一致性：通过
  - [x] 代码质量：通过（X 项已自动修复）
  - [ ] 安全检查：X 项需人工确认

6. **修复后验证**：自动修复完成后，重新运行全部测试（命令取自 `docs/00_standards/test-commands.yml`），确认修复未引入新问题

• 测试通过 → 评审完成
• 测试失败 → 回滚修复，将问题标记为需人工处理
• **写 `last_phase_result`**：`checks` 取自真跑 test-commands 的 `unit`/`coverage`/`lint` 退出码，不用自检冒充；

退出码三态语义与「命令跑不了 = yml 过期信号」见下方 check 命令规则 7. **`--autonomous` 下的收尾判定**（呼应非交互契约）：

• 「需人工处理/需人工确认」表中存在**阻塞级**项 → 不推进：`last_phase_result.ok=false` + `blocked_reason="评审存在阻塞级待人工项"` + 输出 blocked 哨兵，交还人类
• 仅有非阻塞级人工项 → 记录在案并正常推进到 `review_done`

要求

<!-- @include templates/prompts/output-language.md -->

• 问题按严重程度分级：阻塞 / 严重 / 一般 / 建议
• **能修的问题直接修复**，不仅仅指出问题
• 修复后必须验证测试仍然通过

评审目标: $ARGUMENTS

---

文档评审

对指定的文档进行质量评审，检查完整性、一致性和可操作性。**发现问题直接修复，而非仅列出建议。**

文档评审检查项

完整性

• [ ] 是否覆盖了所有必要章节（对照对应模板 `templates/` 检查）
• [ ] 是否有遗漏的功能点或接口
• [ ] 非功能需求是否有说明
• [ ] 是否有明确的验收标准
• [ ] PDLC 追溯头是否完整（功能ID、功能名称、阶段、前置文档、创建时间）

一致性

• [ ] 术语命名是否前后一致（同一概念不用不同名称）
• [ ] 数据模型是否与 API 设计一致（字段名、类型）
• [ ] 接口参数是否与 PRD 需求对应
• [ ] 版本号和日期是否准确
• [ ] 文档间交叉引用路径是否正确

可操作性

• [ ] 操作步骤是否具体可执行（无模糊表述如「适当配置」「按需调整」）
• [ ] 是否有示例代码或示例数据
• [ ] 错误码是否有清晰的处理建议
• [ ] 部署步骤是否可复现

规范性

• [ ] 是否符合对应模板格式
• [ ] 表格是否完整（无空列、无缺失表头）
• [ ] Markdown 语法是否正确（标题层级、列表缩进、代码块语言标注）
• [ ] 输出语言是否符合用户对话语言（或用户显式指定的语言）

文档自动修复规则（发现即修，不仅记录）

1. **缺失章节**：对照模板自动补充，内容根据文档已有信息合理推断 2. **PDLC 追溯头缺失或不完整**：自动补全缺失字段 3. **术语不一致**：统一为文档中首次出现的术语，全文替换 4. **模糊表述**：自动改写为具体、可度量的描述 5. **表格格式问题**：自动修复空列、对齐问题 6. **Markdown 语法错误**：自动修复标题层级、列表缩进 7. **交叉引用路径错误**：检查引用的文件是否存在，不存在则标注警告 8. **缺失示例**：为 API 接口自动补充请求/响应示例

**不可自动修复的问题**（记录到评审报告）：

• 业务逻辑的正确性争议
• 需要与产品确认的需求歧义
• 涉及跨文档架构调整的问题

文档评审工作流程

1. **识别文档类型**：判断文档属于 PRD / API 设计 / DB 设计 / 架构设计 / 测试计划 / 部署手册 2. **加载对照物**：

• 加载对应的模板（`templates/` 目录）
• 加载前置文档（从 PDLC-TRACE 中获取路径）
• 如是设计文档，同时加载 PRD 进行交叉比对

3. **逐项检查**：按上方检查项逐一执行 4. **自动修复**：发现问题直接修改原文档 5. **【必须创建文件】生成评审记录**：在 `docs/07_reviews/doc/` 下创建评审记录

• **文件名格式**: `<功能ID>-<功能名>-<文档类型>-doc-review.md`
• **报告格式**：

     ## 文档评审报告
     - 评审时间：<ISO 8601>
     - 目标文档：<文档路径>
     - 文档类型：<PRD/API设计/DB设计/...>
     - 问题总数：X 项（必须修改: X / 建议修改: X / 可选: X）
     - 自动修复：X 项
     - 需人工确认：X 项

     ## 自动修复记录
     | # | 问题类型 | 修复内容 |
     |---|---------|---------|
     | 1 | 缺失章节 | 补充了「非功能需求」章节 |

     ## 需人工确认
     | # | 严重程度 | 问题描述 | 建议 |
     |---|---------|---------|------|
     | 1 | 必须修改 | XXX 需求存在歧义 | 建议与产品确认 |

     ## 检查项结论
     - [x] 完整性：通过
     - [x] 一致性：通过（X 项已修复）
     - [x] 可操作性：通过
     - [x] 规范性：通过

• 修复后仅复查一次（确认修复未引入新问题），**不再递归修复**。若复查仍发现问题，记录到评审报告的「需人工确认」中

<!-- @include templates/prompts/check-commands.md --> <!-- @include templates/prompts/state-update.md --> <!-- @include templates/prompts/handoff.md -->