@chenguangyao/devflow-kit 0.1.43

package/skills/code-review/references/output-template.md

@@ -0,0 +1,275 @@
+# code-review / output-template
+
+`code-review` skill 的三份产物:
+
+1. `review.md` — 人类可读,每轮 append 一个 `## Round N` section。
+2. `review.findings.json` — 机器可解析;`state.json.phases.review.rounds[N].findingsPath` 指向它,下一轮 apply 读它做自动定位。
+3. `code-review-report.md` — 最终一次通过后产出,作为 `devflow verify` / `devflow deliver` 的硬前置(审计留档)。
+
+`devflow review --round` 保证前两者同步写入;写失败整体 rollback,不留 partial 状态。
+
+---
+
+## §1 `review.md` —— 每轮 section 模板
+
+```markdown
+---
+round: 1                            # 从 1 起算
+reviewer: independent               # 固定值,表明 context 隔离
+baseBranch: master                  # 与 coder 的 worktree 对齐
+commitRange: <base-sha>..<head-sha> # git diff 用到的范围
+diffScope: api-change               # data-layer | test-only | api-change | config-only | docs-only | full
+iterationCount: 1                   # = round
+mustCount: 3
+shouldCount: 2
+nitCount: 1
+outcome: back_to_apply              # pass | back_to_apply | blocked | force-pass
+createdAt: 2026-04-24T09:12:30+08:00
+---
+
+## 第 1 轮
+
+### 0. 变更范围摘要
+
+- 变更文件: 7 个(5 个 src,2 个 test)
+- 变更范围判定: `api-change`
+- 新增 / 修改 / 删除: +214 / -38 / -0
+- 涉及层级: Controller → Service → Repository → Migration
+
+### 1. 上轮问题修复情况(round > 1 时才有;round 1 填 "N/A")
+
+| 序号 | 问题 | 本轮状态 |
+| --- | --- | --- |
+| CR-001 | 金额在 SQL 中计算导致精度问题 | 已修复 |
+| CR-002 | TC-002 测试缺失 | 已修复 |
+| CR-003 | 魔法值未定义 | **未修复(继承)** |
+
+### 2. 本轮检查结果(按维度)
+
+#### 2.1 正确性
+| 检查项 | 结果 | 说明 |
+| --- | --- | --- |
+| 实现符合 design.md | 是 | CouponGrantService 与设计一致 |
+| 业务逻辑正确 | 是 | |
+| 接口契约一致 | **否** | `couponId` 类型不一致(见 CR-101) |
+| 边界条件处理 | 是 | |
+| 并发安全 | **否** | 库存扣减未用原子 UPDATE(见 CR-102) |
+| 事务与幂等 | 是 | |
+
+#### 2.2 完整性(需求功能点对照)
+| 需求功能点 | 代码覆盖 | 对应改动点 | 状态 |
+| --- | --- | --- | --- |
+| F-01 用户可领取优惠券 | 是 | CouponController.grant | 已覆盖 |
+| F-02 同一用户同模板不可重复领 | **否** | — | **未覆盖(CR-103)** |
+| F-03 库存耗尽返回友好错误码 | 是 | GrantService.checkStock | 已覆盖 |
+
+#### 2.3 安全性
+| 检查项 | 结果 | 说明 |
+| --- | --- | --- |
+| SQL 注入 | 是 | 全部参数化 |
+| 鉴权 | 是 | |
+| 敏感数据脱敏 | **否** | log 里含手机号(见 CR-104) |
+| Secret 落代码 | 是 | |
+
+#### 2.4 性能
+(按 §4 review-checklist.md 逐项填)
+
+#### 2.5 可维护性
+(按 §5 review-checklist.md 逐项填)
+
+#### 2.6 测试 —— tests.md ↔ 测试代码对照
+| 用例 | 对应测试 | 断言有效 | 状态 |
+| --- | --- | --- | --- |
+| TC-001 领券成功 | TestGrantCoupon_Success | 是 | 覆盖 |
+| TC-002 重复领券 | — | — | **缺失(CR-105)** |
+| TC-003 库存耗尽 | TestGrantCoupon_OutOfStock | 否 | **断言无效(CR-106)** |
+
+#### 2.7 可观测性 / 数据迁移
+(按 §7 review-checklist.md 逐项填)
+
+### 3. 本轮 findings(按严重度)
+
+> 同时写进 `review.findings.json`,下游 apply 用 JSON 做自动定位。
+
+| ID | 级别 | fixMode | 位置 | 问题 | 建议 |
+| --- | --- | --- | --- | --- | --- |
+| CR-101 | MUST | REVIEW | api/v1/coupon.proto:17 | couponId 在 proto 是 int64,代码里 string | 统一为 string,前后端通过 gen 代码对齐 |
+| CR-102 | MUST | REVIEW | service/grant.go:45 | 先 SELECT 再 UPDATE 有超卖风险 | 改为 `UPDATE stock SET qty=qty-1 WHERE qty>0 AND id=?` 原子更新,检查 RowsAffected |
+| CR-103 | MUST | REVIEW | service/grant.go | F-02 未实现 | 增加 `(userId, templateId)` 唯一约束 + 查询拦截 |
+| CR-104 | MUST | AUTO-FIX | service/grant.go:52 | 日志打印了 user.Phone 原始值 | 使用 `log.WithUser(user)` 统一脱敏 |
+| CR-105 | MUST | REVIEW | test/grant_test.go | TC-002 缺失 | 新增 `TestGrantCoupon_Duplicated` 断言 ErrCodeDuplicate |
+| CR-106 | MUST | REVIEW | test/grant_test.go:88 | 只断言无错,未验证错误码 | 补 `assert.Equal(t, ErrCodeOutOfStock, err.Code)` |
+| CR-201 | SHOULD | REVIEW | service/grant.go:40-95 | 函数过长(> 80 行),职责复杂 | 拆 `validate / deduct / persist` 三段 |
+| CR-202 | SHOULD | AUTO-FIX | service/grant.go:60 | 魔法值 3 | 常量 `STATUS_GRANTED = 3` |
+| CR-301 | NIT | AUTO-FIX | service/grant.go:25 | 变量名 `t` 不表意 | 改为 `template` |
+
+### 4. 结论
+
+- **outcome: back_to_apply**(MUST=6,SHOULD=2,NIT=1)
+- **下一轮 apply 优先级**:先 AUTO-FIX 类(CR-104, CR-202, CR-301),再 REVIEW 类按 CR-101 → CR-102 → CR-103 → CR-105 → CR-106 → CR-201。
+- **风险提示**:CR-102(并发超卖)若线上已发布要紧急热修。
+```
+
+**要点**:
+
+- 表格行内的 MUST / SHOULD / NIT 才会被 `devflow review --round` 计数;散文里的 "should" / "must" 要小写。
+- findings 的 ID 格式 `CR-<N>xx`:MUST 用 100-199,SHOULD 用 200-299,NIT 用 300-399,方便扫表识别。
+- 本轮 findings 不要编号重用 —— 跨轮 ID 唯一;继承的未修复项沿用原 ID,不创建新 ID。
+
+---
+
+## §2 `review.findings.json` —— Schema
+
+```json
+{
+  "$schema": "https://devflow.dev/schemas/review-findings.v1.json",
+  "round": 1,
+  "baseBranch": "master",
+  "commitRange": "<base-sha>..<head-sha>",
+  "diffScope": "api-change",
+  "iterationCount": 1,
+  "summary": {
+    "correctness":     "failed",
+    "completeness":    "failed",
+    "security":        "failed",
+    "performance":     "passed",
+    "maintainability": "fair",
+    "tests":           "failed",
+    "observability":   "passed"
+  },
+  "counters": { "must": 6, "should": 2, "nit": 1 },
+  "outcome": "back_to_apply",
+  "findings": [
+    {
+      "id": "CR-101",
+      "level": "MUST",
+      "dimension": "correctness",
+      "subcheck": "1.3 接口契约一致性",
+      "fixMode": "REVIEW",
+      "location": { "file": "api/v1/coupon.proto", "line": 17, "symbol": "CouponGrantRequest.couponId" },
+      "description": "couponId 在 proto 是 int64,代码使用 string,前后端对接会 type-mismatch",
+      "evidence": ["proto 定义 int64", "handler 里 req.CouponId.(string) 断言"],
+      "suggestedFix": "统一为 string 或 int64,并通过生成代码保证一致",
+      "resolved": false,
+      "carriedOverFromRound": null
+    },
+    {
+      "id": "CR-102",
+      "level": "MUST",
+      "dimension": "correctness",
+      "subcheck": "1.5 并发安全",
+      "fixMode": "REVIEW",
+      "location": { "file": "service/grant.go", "line": 45, "symbol": "grantCoupon" },
+      "description": "先 SELECT qty 再 UPDATE 有超卖窗口",
+      "suggestedFix": "改原子 UPDATE: UPDATE stock SET qty=qty-1 WHERE qty>0 AND id=?; 检查 RowsAffected==1",
+      "resolved": false
+    }
+  ]
+}
+```
+
+**字段必选**:`id` `level` `dimension` `fixMode` `location.file` `description` `suggestedFix` `resolved`。
+
+**`level`**:`MUST` | `SHOULD` | `NIT`(大写)。
+
+**`dimension`**:`correctness` | `completeness` | `security` | `performance` | `maintainability` | `tests` | `observability`。
+
+**`fixMode`**:
+- `AUTO-FIX` — coder 可直接按 suggestedFix 应用,不需要再设计(如命名、魔法值、日志脱敏装饰器)。
+- `REVIEW` — 需要 coder 人工理解、可能引发 design 修改(如接口契约、并发模型)。
+- `SPEC` — 需要回到 tech-spec / requirement 层(连续 2 轮同类 MUST 往往是这个)。
+
+**`location.symbol`**(可选):函数 / 类 / 字段名,给 coder 做模糊匹配,路径漂移后仍能定位。
+
+**`carriedOverFromRound`**(可选):非 null 表示本项从第 N 轮继承且仍未修复;跨轮同一 ID 出现 2 次应升级为 `fixMode=SPEC` 并写入 `escalation-playbook.md` 定义的流程。
+
+---
+
+## §3 `code-review-report.md` —— 审查通过后才产出
+
+只有 outcome 最终是 `pass` 或 `force-pass` 时产出;它是 `devflow verify` / `devflow deliver` 的硬前置(见 workflow gating)。
+
+模板:
+
+```markdown
+---
+finalRound: 2
+finalOutcome: pass            # pass | force-pass
+totalRounds: 2
+totalMustFixed: 6
+totalShouldFixed: 1
+totalNitFixed: 3
+totalMustAccepted: 0          # force-pass 时 >0,需列出 reason
+totalShouldAccepted: 1        # 有 should 被接受放行,列在 "接受与理由" section
+forcePassReason: null         # force-pass 时非空
+signedOff: reviewer
+signedAt: 2026-04-24T11:30:00+08:00
+---
+
+# 代码审查报告 — <slug>
+
+## 1. 审查结论
+
+| 项 | 值 |
+| --- | --- |
+| 最终结论 | **pass** |
+| 总轮次 | 2 |
+| 是否允许提测 | **是** |
+| MUST 全部修复 | 是(6/6) |
+| SHOULD 修复 / 接受 | 1/1(1 项接受,见第 4 节)|
+| 待办 NIT | 3(跟踪至 issue,不阻塞) |
+
+## 2. 需求功能点覆盖度(requirement.md → 代码)
+
+| 需求功能点 | 代码覆盖 | 对应改动点 | 状态 |
+| --- | --- | --- | --- |
+| F-01 | 是 | CouponController.grant | 已覆盖 |
+| F-02 | 是 | GrantService.checkDuplicated | 已覆盖 |
+| F-03 | 是 | GrantService.checkStock | 已覆盖 |
+
+## 3. design.md 改动点对照
+
+| 改动点 | 涉及文件 | 代码已实现 | 全链路完整 | 备注 |
+| --- | --- | --- | --- | --- |
+| 新增 coupon_grant 表 | migration/0012_coupon_grant.sql | 是 | 是 | |
+| CouponGrantService | service/grant.go | 是 | 是 | |
+| 对外 API GrantCoupon | api/v1/coupon.proto | 是 | 是 | |
+
+## 4. 接受与理由(SHOULD / MUST 放行项)
+
+> force-pass 时 MUST 放行必须在此列出 reason;合并到 archive 后永久留档。
+
+| ID | 级别 | 接受理由 |
+| --- | --- | --- |
+| CR-201 | SHOULD | 函数长度超阈值但职责明确且单测覆盖充分,延后拆分到下个迭代(issue #432) |
+
+## 5. 未修复项(NIT)
+
+| ID | 内容 | 跟踪 |
+| --- | --- | --- |
+| CR-301 | 变量命名不表意 | issue #433 |
+| CR-302 | README 未更新 | issue #434 |
+| CR-303 | CHANGELOG 待补 | 在 deliver 阶段补 |
+
+## 6. 附件
+
+- 第 1 轮: [review.md#第-1-轮](./review.md#第-1-轮) / [review.findings.json](./review.findings.json) round=1
+- 第 2 轮: [review.md#第-2-轮](./review.md#第-2-轮) / [review.findings.json](./review.findings.json) round=2
+```
+
+**产出路径**:`devflow/changes/<slug>/code-review-report.md`
+
+**何时产出**:
+
+- `devflow review --round` 判定 outcome ∈ `{pass, force-pass}` 时,自动从 `review.md` 和 `review.findings.json` 聚合生成。
+- 产出后 `state.json.phases.review.reportPath` 指向它。
+- `devflow verify` / `devflow deliver` 启动时读取 `reportPath`;缺失或 `finalOutcome=blocked` 时拒绝放行。
+
+---
+
+## §4 写作要点
+
+- **不要**在同一 MUST 里描述多个问题,拆成独立 finding —— 否则下一轮 apply 只能部分修复,计数乱掉。
+- **不要**把 suggestedFix 写成"重新审视设计"这样的虚话;写就写具体代码或具体改法。确实需要重新设计的,把 `fixMode` 写成 `SPEC`。
+- **不要**把 fixMode 留空 —— 下游 coder 会退回 NEEDS_INPUT 死循环。
+- **不要**在 findings 之外的散文里写"MUST"这个词 —— 计数会污染。

package/skills/code-review/references/review-checklist.md

@@ -0,0 +1,251 @@
+# code-review / review-checklist
+
+Reviewer 的核心工作清单(**语言无关骨架**)。按维度逐项扫描,每一项要明确回答"代码里有没有这样做"。每项都带:
+
+- **检查点**:reviewer 要回答的具体问题
+- **典型问题(反例)**:最常见的错法
+- **正确做法(正例)**:期望的样子
+- **严重度判定**:什么情况下算 MUST / SHOULD / NIT
+
+顺序:先 §1 Correctness(高优先级、高成本) → §7 Observability;然后打开 §严重度速查 校准判定。
+
+## 必须配合 language cheatsheet 使用
+
+本文只给"语言无关的骨架",真正的踩坑长什么样要看对应语言的 cheatsheet。按 `SKILL.md` 的"按项目语言自动加载 cheatsheet"章节挑 1-2 份一起读:
+
+| 语言 / 栈 | cheatsheet |
+| --- | --- |
+| Java + Spring + MyBatis | [`language-cheatsheets/java-spring-mybatis.md`](language-cheatsheets/java-spring-mybatis.md) |
+| Go | [`language-cheatsheets/go.md`](language-cheatsheets/go.md) |
+| Python(Django / FastAPI / Flask) | [`language-cheatsheets/python.md`](language-cheatsheets/python.md) |
+| Vue 3 + TypeScript | [`language-cheatsheets/vue.md`](language-cheatsheets/vue.md) |
+
+每个 cheatsheet 末尾都有"快速映射到本文"的章节,说明哪一节对应通用 checklist 的哪一节。
+
+---
+
+## §1 Correctness(正确性)
+
+### 1.1 实现是否符合 design.md
+
+- **检查点**:把 `design.md` 的"实现方案"或"改动点汇总"**逐条**在代码 diff 里找到对应。
+- **反例**:design 写了"并发场景用 Redis 分布式锁",代码用了 `synchronized` / `sync.Mutex` 单机锁。
+- **正例**:代码里有 Redis SET NX PX + lua 释放脚本,并带有超时与重入检查。
+- **判定**:设计方案写了但代码没实现 → **MUST**;代码实现了设计没提的额外能力 → **SHOULD**(范围越权,除非 requirement.md 显式要求)。
+
+### 1.2 业务逻辑是否正确
+
+- **检查点**:核心计算、状态转移、决策分支是否在所有输入下都产出 requirement.md 里约定的结果。
+- **反例**:优惠券金额 = SQL 里 `SUM(price * discount)` 直接返回给接口 —— 浮点误差 + 无法单元测试。
+- **正例**:金额拉回业务层用 `BigDecimal` / `decimal.Decimal` 计算,SQL 只做原子 UPDATE。
+- **判定**:结果错 → **MUST**;结果对但脆弱(精度、时区、locale) → **SHOULD**。
+
+### 1.3 接口契约是否一致
+
+- **检查点**:对外接口(HTTP / RPC / gRPC / 消息队列)的字段、类型、命名与 design.md 或"前端接口文档"是否 1:1。
+- **反例**:design 里字段 `couponId: string`,代码里 `coupon_id: number`。
+- **正例**:OpenAPI / Protobuf 自动生成 DTO,代码不手写;若手写则与 API spec 做 linter 校验。
+- **判定**:字段错/类型错/枚举值错 → **MUST**(上下游对接必崩);命名风格不一致(驼峰 vs 下划线)→ **SHOULD**。
+
+### 1.4 边界条件处理
+
+- **检查点**:null / 空串 / 0 / 负数 / 超大值 / UTF8 / 时区 / DST / leap year / 空集合 / 首尾元素。
+- **反例**:`list.get(0)` 无 `isEmpty` 判断;`strings.Split` 结果直接下标访问。
+- **正例**:入口处早 return + 显式错误类型 `EmptyInputError`,测试里覆盖空集合分支。
+- **判定**:崩溃路径未处理 → **MUST**;只处理主干、边界走兜底 log → **SHOULD**。
+
+### 1.5 并发安全
+
+- **检查点**:共享状态(map / slice / cache / counter / DB row)是否有原子性或锁保护;goroutine / thread 生命周期是否管理。
+- **反例**:两个请求同时扣库存,都先 SELECT 再 UPDATE,超卖。
+- **正例**:`UPDATE stock SET qty = qty - 1 WHERE qty > 0`(原子),或分布式锁包裹。
+- **判定**:有可观察到的竞态(超卖、重复扣款、重复下发)→ **MUST**;理论有竞态但极低概率(如只做缓存 miss 穿透)→ **SHOULD**。
+
+### 1.6 事务与幂等
+
+- **检查点**:涉及多表 / 跨系统写入的路径是否有事务;对外调用是否幂等(重试安全)。
+- **反例**:扣库存 + 生成订单不在同一事务;第三方支付回调无 idempotency key。
+- **正例**:`@Transactional` / `WithTransaction`;回调表按支付单号唯一索引。
+- **判定**:可能留下脏数据 / 重复扣款 → **MUST**;只影响可观测性(重复发短信)→ **SHOULD**。
+
+---
+
+## §2 Completeness(需求覆盖度)
+
+> 本节是 review 的"安全网" —— 防止需求遗漏。不深入查代码质量,只查"有没有做"。L1 无结构化 requirement 可跳过。
+
+### 2.1 requirement.md 功能点对照表
+
+必须在 `review.md` 的 Round 1 产一份:
+
+| 需求功能点(来自 requirement.md) | 代码覆盖 | 对应改动点(来自 design.md) | 状态 |
+| --- | --- | --- | --- |
+| F-01 用户可领取优惠券 | 是 | CouponController.grant | 已覆盖 |
+| F-02 同一用户同模板不可重复领 | **否** | — | **未覆盖(MUST)** |
+| F-03 库存耗尽返回友好错误码 | 是 | GrantService.checkStock | 已覆盖 |
+
+**判定规则**:
+- 代码已覆盖 → 通过
+- 代码未覆盖,但 design.md 标注"延后 / 不在本次范围" → 通过,备注原因
+- 代码未覆盖,design.md 也没提 → **MUST**(需求遗漏)
+
+### 2.2 EDGE CASES 对照
+
+把 requirement.md 的"边界 / 异常 / 反例"段每一条映射到代码路径或测试用例:
+
+| 边界场景 | 代码位置 | 测试用例 | 状态 |
+| --- | --- | --- | --- |
+| 库存为 0 | GrantService:45 | TC-003 | 覆盖 |
+| 用户未登录 | 中间件 `AuthMiddleware` | — | **测试缺失(MUST)** |
+
+### 2.3 delta/ spec 变更一致性(L2/L3)
+
+- **检查点**:`changes/<slug>/delta/*.md` 列出的 spec 变更在代码里是否都实现了。
+- **反例**:delta 写了"ADDED: 优惠券过期事件",代码里没发事件。
+- **判定**:delta 声明但未实现 → **MUST**(archive 会把 delta 合入 `specs/`,错的 spec 污染主库)。
+
+---
+
+## §3 Security(安全)
+
+| 检查点 | 反例 | 正例 | 判定 |
+| --- | --- | --- | --- |
+| SQL 注入 | `"SELECT * FROM u WHERE name='" + n + "'"` | Prepared Statement / ORM 参数化 | 任一未参数化 → **MUST** |
+| XSS / 模板注入 | 直接 `innerHTML = userInput` | 框架默认 escape 或 DOMPurify | **MUST** |
+| 鉴权 | 只校验 token 存在,不校验权限范围 | 中间件统一鉴权 + 资源所有权校验 | **MUST** |
+| 敏感数据记日志 | `log.info("user: %s", user)`(含手机号/身份证) | 结构化日志 + 脱敏装饰器 | **MUST**(合规红线)|
+| Secret 落代码 | 代码里写 `api_key = "sk-xxx"` | `env` / Vault / SOPS | **MUST** + audit log |
+| null 安全 | `user.getEmail().toLowerCase()` 无 nil 判断 | Optional / `user?.email` / 早 return | NPE 必 crash → **MUST**;理论存在 → **SHOULD** |
+| 资源泄漏 | `conn := open(); use(conn)`(漏 close) | `defer close()` / `try-with-resources` | **MUST** |
+| 密码学 | MD5 存密码;用 `math/rand` 生成 token | bcrypt / argon2;`crypto/rand` | **MUST** |
+| CSRF | 状态变更接口无 CSRF token | 框架 CSRF 中间件 | Web 表单 → **MUST**;纯 JSON API + 鉴权 → **SHOULD** |
+| 依赖漏洞 | 用了 CVE 披露的旧版 lib | lockfile 升级 + `npm audit` / `go mod audit` | 高危 CVE → **MUST** |
+
+---
+
+## §4 Performance(性能)
+
+| 检查点 | 反例 | 正例 | 判定 |
+| --- | --- | --- | --- |
+| N+1 查询 | 循环里每次查 DB | JOIN / IN / DataLoader / batched fetch | 接口可观测变慢 → **MUST**;调用量小 → **SHOULD** |
+| O(N²) 嵌套 | `for x in A: for y in A: if x==y` | 用 map/set 索引 | 大数据量 → **MUST**;N<100 → NIT |
+| 不必要的同步 | 在 HTTP handler 里同步调三方 API 串行 | 并发 + timeout + circuit breaker | 超 SLA → **MUST** |
+| 无界循环 / 队列 | `for ; ; { dequeue() }` 无退出 | 退出信号 + max iteration | **MUST** |
+| 内存泄漏 | listener / goroutine 不回收 | WeakRef / context cancel | **MUST** |
+| 缓存穿透 | 热点 key miss 直接压 DB | singleflight / 空对象缓存 | 生产热点 → **MUST**;非热点 → **SHOULD** |
+| 日志爆炸 | 每次请求打 DEBUG 全量 payload | 采样 + 级别控制 | **SHOULD** |
+
+## §5 Maintainability(可维护性)
+
+| 检查点 | 反例 | 正例 | 判定 |
+| --- | --- | --- | --- |
+| 命名 | `int t` / `doStuff()` / `handleX()` | `expireAt` / `calculateDiscount()` | **NIT**(多发 → **SHOULD**) |
+| 魔法值 | `if status == 3` | `if status == STATUS_PAID` | **SHOULD** |
+| 长函数(> 60 行 / > 5 层嵌套) | 200 行的 `process()` | 按职责拆 | **SHOULD** |
+| 重复代码 | 同一段逻辑 copy 3 次 | 提抽象函数 | 首次 **NIT**,3+ 处 **SHOULD** |
+| 职责单一 | Controller 直接写 SQL | 分层(Controller → Service → Repo) | **SHOULD** |
+| 注释规范 | 无注释 / `// TODO` 过半年 | 关键决策 + `Why` / 公共 API 文档 | 公共 API 无注释 **SHOULD**;内部 **NIT** |
+| 异常处理 | `catch (Exception) { log }` 吞异常 | 捕获具体类型 + rethrow / wrap | 吞异常 **MUST**;过度捕获 **SHOULD** |
+| 循环依赖 | A → B → A | 接口倒置 / 事件解耦 | **SHOULD** |
+
+## §6 Tests(单元测试)
+
+> 若 `reports/test-report.md#unit` 存在,相信其 PASS 结果,只复核 FAIL 与未覆盖项。
+
+### 6.1 tests.md ↔ 测试代码对照表
+
+| tests.md 用例号 | 对应测试方法 / 函数 | 断言是否有效 | 状态 |
+| --- | --- | --- | --- |
+| TC-001 领券成功 | `TestGrantCoupon_Success` | 是 | 覆盖 |
+| TC-002 重复领券 | — | — | **缺失(MUST)** |
+| TC-003 库存耗尽 | `TestGrantCoupon_OutOfStock` | 只 assert 无 error,未 assert 错误码 | **SHOULD**(断言无效)|
+
+### 6.2 测试代码质量检查
+
+| 检查点 | 反例 | 正例 | 判定 |
+| --- | --- | --- | --- |
+| 断言强度 | `assert.NoError(err)` (只验不报错) | 额外验证返回值 / 状态 / 副作用 | **SHOULD** |
+| Mock 策略 | Mock 被测函数本身 | 只 Mock 外部依赖(DB / HTTP) | **MUST** |
+| 测试数据 | 随机 / 时间敏感(`time.Now()`) | 固定 fixture / 注入时钟 | **SHOULD** |
+| skip / only | `it.skip` / `test.only` 入库 | CI 前清空 | **MUST** |
+| 死测试 | 断言了永远为真的东西(`assert.Equal(1, 1)`) | 断言业务结果 | **MUST** |
+| 测试命名 | `test1` / `testFoo2` | `Test<Function>_<Case>_<Expected>` | **NIT** |
+
+### 6.3 覆盖率(若有 `reports/test-report.md#unit` 里的覆盖率数据)
+
+| 指标 | 低于多少 | 判定 |
+| --- | --- | --- |
+| L1 | — | 只要关键路径有测试即可 |
+| L2 | 行覆盖 < 60% | **SHOULD** |
+| L3 | 行覆盖 < 75% 或关键路径分支覆盖 < 80% | **MUST** |
+
+---
+
+## §7 Observability / Migration / Ops
+
+### 7.1 可观测性
+
+| 检查点 | 反例 | 正例 | 判定 |
+| --- | --- | --- | --- |
+| 关键节点日志 | 无 | 请求入口 / 外部调用前后 / 异常分支 | 关键分支无日志 **SHOULD**;异常无日志 **MUST** |
+| TraceID 透传 | 子调用丢 traceID | `context` 透传或 header 透传 | **SHOULD** |
+| 指标 | 新业务无 QPS / 错误率 / 延迟指标 | Prometheus / OpenTelemetry counter/histogram | 新接口 **SHOULD** |
+| 告警 | 设计写了"库存低于 N 告警",代码没注册 | 告警规则与 design.md 对齐 | design 写了 → **MUST** |
+
+### 7.2 迁移(DDL / 数据迁移)
+
+| 检查点 | 反例 | 正例 | 判定 |
+| --- | --- | --- | --- |
+| DDL 可重入 | `ALTER TABLE ADD COLUMN` 无 `IF NOT EXISTS` | `IF NOT EXISTS` / 幂等脚本 | **MUST** |
+| 回滚脚本 | 只有 `up.sql` | 配套 `down.sql` 或明确"不可回滚" + 原因 | 无回滚且未说明 **MUST** |
+| 大表在线 | `ALTER TABLE` 加锁 | pt-osc / gh-ost / 分批 | 百万行以上表 **MUST** |
+| DDL ↔ 代码字段一致 | DDL 枚举 1,2,3 vs 代码常量 10,20,30 | 完全一致或生成代码 | **MUST**(历史踩坑,超级难排查) |
+
+### 7.3 新增字段全链路(重点!改数据层最易漏)
+
+每新增一个字段,逐层核对(按你的技术栈替换层级名):
+
+| 层级 | 检查 |
+| --- | --- |
+| DDL / migration | `ALTER TABLE` 已加且类型正确 |
+| ORM 模型(DO / Entity / Model) | 属性已声明 + 类型匹配 DDL |
+| 映射文件(mapper.xml / sqlc / 查询构建器) | SELECT 列表 / INSERT / UPDATE 已包含 |
+| Domain / Service 层 | 取/存逻辑已使用新字段 |
+| Convertor / DTO mapper | DO ↔ DTO 转换已处理 |
+| 对外返回对象(VO / Response) | 已暴露(如需) |
+| 前端接口文档 | 已同步(若有) |
+
+**任一层缺失 → MUST**。这是 arb 最核心的踩坑 checklist,原因:字段从 DDL 到 VO 需要经过 5-7 层,漏任何一层都会导致线上返回 null,而且 happy path 单测都能过。
+
+---
+
+## 严重度速查
+
+| 判定信号 | MUST | SHOULD | NIT |
+| --- | --- | --- | --- |
+| 数据正确性 / 丢单 / 资损 | ✓ | | |
+| 安全合规红线 | ✓ | | |
+| 需求功能未实现 / 契约破坏 | ✓ | | |
+| 测试用例缺失 / 断言无效 | ✓ | | |
+| DDL ↔ 代码字段不一致 | ✓ | | |
+| 生产可观测的性能回归 | ✓ | | |
+| 非阻塞的风险(可维护性、次级性能) | | ✓ | |
+| 非关键路径的代码异味 | | ✓ | |
+| 纯风格(命名、排版) | | | ✓ |
+
+**临界判定规则**:
+
+- 拿不准 MUST / SHOULD → 问自己"这个问题上线后 P0 / P1 / P2?",P0-P1 给 MUST。
+- 拿不准 SHOULD / NIT → 问自己"下一个接手这份代码的人会卡住吗?",会就 SHOULD。
+- 如果 reviewer 与 coder 对严重度有分歧,把分歧本身作为 SHOULD 记录,由 `devflow review --force-pass` 或回 tech-spec 上级裁决。
+
+---
+
+## 本 skill 与下游的交接
+
+Reviewer 的每一个 MUST / SHOULD 都应该:
+
+1. 写进 `review.md`(人读)
+2. **同时**写进 `review.findings.json`(机读,给 apply 自动定位修复)
+
+格式见 `references/output-template.md` §2。