@chenguangyao/devflow-kit 0.1.43

package/skills/test-spec/references/test-case-template.md

@@ -0,0 +1,276 @@
+# test-spec / test-case-template
+
+`tests.md` 完整模板、用例详表字段语义、正反例、L2 完整示例。
+
+---
+
+## 模板
+
+```markdown
+---
+slug: <slug>
+createdAt: <ISO>
+level: L1 | L2 | L3
+refs:
+  - requirement.md
+  - design.md
+---
+
+# Tests: <one-line title>
+
+## 1. 测试策略
+- 金字塔分布:unit 75% / integration 20% / e2e 5%
+- 工具:<按项目语言;见 coverage-strategy.md>
+- 覆盖率目标:line ≥ 80%,branch ≥ 70%(业务核心类)
+
+## 2. 数据准备(Fixtures)
+- `fixtures/users/batch_1k.json`:1000 合法用户
+- `fixtures/users/with_risk.json`:50 命中风控 + 950 正常
+- `fixtures/coupon/templates.sql`:3 个有效模板 + 1 个过期 + 1 个不足库存
+- Factory:`UserFactory.make(count, riskRate=0.1)` 批量生成
+
+## 3. 环境依赖 & Mock 策略
+| 依赖 | 策略 | 说明 |
+| --- | --- | --- |
+| DB | 真(内嵌 H2 / test container MySQL) | 用 fixture 种子 |
+| RiskService | mock | 覆盖 pass / hit / timeout 三分支 |
+| FeatureFlag | stub | 默认 enabled=true,按用例切 |
+| 监控上报 | spy | 断言指标是否上报 |
+
+## 4. 测试用例索引
+| TC | 类型 | F-ID | 优先级 | 一句话 |
+| --- | --- | --- | --- | --- |
+| TC-001 | unit | F-01 | P0 | 正向:1000 人全成功 |
+| TC-002 | unit | F-01 | P0 | 边界:空 userIds 400 |
+| TC-003 | unit | F-01 | P0 | 边界:1001 人 400 |
+| TC-004 | unit | F-02 | P0 | 部分失败:10 人风控 → failedUsers |
+| TC-005 | integration | F-01 | P0 | E2E with DB:批次落库正确 |
+| TC-006 | integration | F-02 | P1 | RiskService timeout 降级 |
+| TC-007 | unit | F-01 | P1 | 幂等:同 batchId 重复调用 |
+| TC-008 | integration | F-03 | P1 | 运营后台 CSV 上传 → 调 F-01 |
+| TC-009 | integration | F-01 | P1 | 权限:无 coupon:batch_grant → 403 |
+| NFR-PERF-001 | perf | F-01 | P1 | 1000 人 P99 ≤ 3s |
+
+## 5. 逐用例详表
+
+### TC-001:正向 - 1000 人全成功
+- **type**: unit
+- **linkedF**: F-01
+- **priority**: P0
+- **preconditions**:
+  - couponTemplate `ct_ok` 存在、库存 1200
+  - userIds = 1000 个合法 userId(fixture users/batch_1k.json)
+  - RiskService mock 全 pass
+- **steps**:
+  1. 调 `BatchGrantController.grant({userIds, couponTemplateId: 'ct_ok'})`
+- **expected**:
+  - 响应 status = 200
+  - body.grantedCount === 1000
+  - body.failedCount === 0
+  - body.failedUsers === []
+  - DB: coupon_grant 表新增 1000 行,每行 batch_id 非空且一致
+  - 指标 `coupon.batch.latency` 上报 1 条 histogram
+- **dataSource**: fixtures/users/batch_1k.json
+- **notes**: -
+
+### TC-002:边界 - 空 userIds → 400
+- **type**: unit
+- **linkedF**: F-01
+- **priority**: P0
+- **preconditions**: userIds = []
+- **steps**:
+  1. 调接口
+- **expected**:
+  - 响应 status = 400
+  - body.code === "EMPTY_BATCH"
+  - DB 无变更
+- **dataSource**: -
+
+### TC-003:边界 - 1001 人 → 400 BATCH_TOO_LARGE
+- **type**: unit
+- **linkedF**: F-01
+- **priority**: P0
+- **preconditions**: userIds 长度 1001
+- **steps**:
+  1. 调接口
+- **expected**:
+  - 响应 status = 400
+  - body.code === "BATCH_TOO_LARGE"
+  - body.details.limit === 1000
+  - body.details.actual === 1001
+
+### TC-004:部分失败 - 10 人风控 hit
+- **type**: unit
+- **linkedF**: F-02
+- **priority**: P0
+- **preconditions**:
+  - userIds = 1000(fixture users/with_risk.json:前 50 人 mock 命中风控)
+  - RiskService mock: 前 10 人返回 hit(hitCode = "R001"),其余 pass
+- **steps**:
+  1. 调接口
+- **expected**:
+  - 响应 status = 200
+  - body.grantedCount === 990
+  - body.failedCount === 10
+  - body.failedUsers 含 10 个 {userId, reason: "RISK_HIT", hitCode: "R001"}
+  - DB: coupon_grant 新增 990 行(被拦的 10 人无记录)
+
+### TC-005:integration - 批次落库
+- **type**: integration
+- **linkedF**: F-01
+- **priority**: P0
+- **preconditions**:
+  - test container MySQL 已起
+  - fixture users/batch_1k.json
+- **steps**:
+  1. HTTP POST 真实调用
+  2. SELECT * FROM coupon_grant WHERE batch_id = <返回的 batchId>
+- **expected**:
+  - 查询得 1000 行
+  - 每行 status = 'granted',batch_id 一致,user_id 与输入列表一一对应
+
+### TC-006:RiskService timeout 降级
+- **type**: integration
+- **linkedF**: F-02
+- **priority**: P1
+- **preconditions**:
+  - RiskService stub: 对前 20 个 userId 返回 timeout(sleep 5s)
+  - config:riskTimeoutMs = 3000
+- **steps**:
+  1. 调接口(1000 人)
+- **expected**:
+  - 响应 status = 200
+  - 前 20 个在 failedUsers(reason: "RISK_TIMEOUT")
+  - 指标 `risk.timeout.count` 上报 20 次
+
+### TC-007:幂等 - 同 batchId
+- **type**: unit
+- **linkedF**: F-01
+- **priority**: P1
+- **preconditions**:
+  - batchId = "b_test_01"
+  - 第一次调用成功发 1000 人
+- **steps**:
+  1. 用同 batchId 再调一次
+- **expected**:
+  - 响应 status = 200
+  - 内容与第一次相同(幂等)
+  - DB 不新增行(唯一键拦截)
+
+### TC-009:权限 - 无 coupon:batch_grant
+- **type**: integration
+- **linkedF**: F-01
+- **priority**: P1
+- **preconditions**:
+  - 使用普通运营 token(角色: coupon:view)
+- **steps**:
+  1. 调接口
+- **expected**:
+  - 响应 status = 403
+  - body.code === "FORBIDDEN"
+
+### NFR-PERF-001:1000 人性能基线
+- **type**: perf
+- **linkedF**: F-01 + NFR-PERF
+- **priority**: P1
+- **preconditions**: 单实例 4c8g;DB 有 1k 模板 + 10k 用户 fixture
+- **steps**:
+  1. 用 k6 / JMeter 调接口 20 并发 × 5 分钟,每次 1000 人
+- **expected**:
+  - P99 ≤ 3s
+  - Error rate < 0.1%
+  - GC 无 Full GC > 200ms
+
+## 6. 非功能测试
+- 性能:NFR-PERF-001(见上)
+- 安全:TC-009 已覆盖鉴权;敏感数据脱敏在 unit test 里检查 log message
+- 可观测性:TC-001 / TC-006 断言指标上报
+
+## 7. 回归清单
+| 已有 TC | 影响 | 重跑原因 |
+| --- | --- | --- |
+| CouponGrantControllerTest.testSingleGrant | 单发不应受影响 | 确认不回归 |
+| RiskServiceTest.testCheck_hit | 风控判定不变 | 确认签名兼容 |
+```
+
+---
+
+## 字段语义补充
+
+### TC 编号
+
+- `TC-<NNN>`(三位数字)全局唯一
+- 不重用已删除的编号
+- 非功能前缀 `NFR-<domain>-<NNN>`
+
+### priority(优先级)
+
+| | 含义 |
+| --- | --- |
+| P0 | 必过;一个挂就阻塞 deliver |
+| P1 | 应过;挂了但 MUST 修不上,需要用户 accept 风险 |
+| P2 | 最好过;挂了可以进 `todo.md` 下期跟进 |
+
+### type(类型)
+
+- **unit**:单类 / 纯函数;mock 所有外部依赖;毫秒级
+- **integration**:真实 DB + mock 第三方;秒级
+- **e2e**:端到端全链路(可能含前端);分钟级
+- **perf**:性能 / 容量;独立阶段跑
+- **security**:鉴权 / 敏感数据 / 越权;通常归 integration 但单独标识
+
+### linkedF
+
+- 必引用 ≥ 1 个 F-ID(如 `F-01` 或 `F-01, F-02`)
+- 非功能引用 `NFR-<domain>`(PERF / SEC / OBS / AVAIL)
+
+### preconditions
+
+**要**:具体、可复现(fixture 文件名 / 数据库状态 / mock 返回)
+
+**不要**:"系统正常" / "普通场景"这种模糊表达
+
+### steps
+
+- 编号列表,每一步动作是 agent 可执行的
+- 不要塞断言(断言在 expected);只写"做什么"
+
+### expected
+
+- 每条断言独立一行
+- 覆盖:响应、body 字段、DB 状态、副作用(指标、日志、事件)
+- **数字精确**("grantedCount === 990",不是"大约 990")
+
+### dataSource
+
+- 指向 fixture 文件或 factory 规则
+- 不要用"根据业务逻辑生成"这种模糊表达
+
+### notes
+
+- flaky 原因、skip 原因、为什么不用某种测法
+- 空可以省略
+
+---
+
+## 反例
+
+```
+TC-XXX: 测试批量发放
+  type: unit
+  steps: 调用接口,检查结果
+  expected: 正常
+```
+
+问题:
+
+- 没 linkedF
+- preconditions 缺
+- steps 不可执行
+- expected 零信息(什么叫"正常")
+
+---
+
+## 本文与 SKILL.md 的关系
+
+SKILL.md 给了 tests.md 的 section 骨架和字段清单。本文是完整模板 + 完整示例,agent 写 tests.md 时复制本文模板开始。

package/skills/verify/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: devflow-verify
+description: |
+  devflow-kit verify 阶段按 change 级别跑齐所有必需测试 + 报告(unit / integration / contract / e2e / joint / remote / smoke / self-test /
+  perf / regression),用**带 YAML frontmatter 的 markdown** 作为 first-class 报告物,
+  最后 `devflow verify finalize` 汇总到 verify.md。触发:`devflow verify`、`devflow test <kind>`、
+  `devflow report self-test`、`devflow verify finalize`、`/df:verify`。
+when_to_use: |
+  code-review 全部轮次通过后。跑测试 → 写 / 生成报告 → finalize。不通过则回退 apply(修)
+  或 tech-spec(重新设计)。verify 拦的是"事实",不是"主观判断"。
+---
+
+# verify
+
+**事实层**:只关心"测试真的跑了没、结果是什么"。不下主观判断(那是 review 的事),但可以发现 review 看不出来的行为问题(如性能不达标)。
+
+## 前置检查
+
+| 输入 | 必需 | 缺失处理 |
+| --- | --- | --- |
+| code-review status = completed(所有轮次通过) | 是 | 回退 review |
+| 所有 plan 的 task 状态 done | 是 | 回退 apply |
+| `design.md` 里有 NFR(L2/L3) | L2/L3 必须 | 回退 tech-spec |
+| 测试契约 | 是 | 优先读 `tests.md`；缺失时读 `plan.md` 的 Test 字段和 requirement.md 的 AC |
+| 有可用的测试执行环境 | 是 | `devflow doctor` |
+
+**硬闸**:`devflow verify` 启动时检查 `state.review.status === "completed"`;缺失拒绝启动,除非 `--skip-review-gate --reason="..."`(审计)。如果 review 刚通过并生成了 `verify_start` 检查点,必须先由用户确认 `devflow checkpoint resolve --id=<checkpoint-id> --decision=start-verify`,不得自动开始 verify；紧急场景可用 `devflow verify --slug=<slug> --force --reason="..."` 审计绕过。
+
+## 按级别的必需报告
+
+| level | 必需报告 | 可选 |
+| --- | --- | --- |
+| L0 | `test-report.md#unit` | 若部署后才可见,补 `#smoke` |
+| L1 | `test-report.md#unit`, `#smoke` | — |
+| L2 | `test-report.md#unit`, `#integration`, `#smoke`, `#self-test` | 有调用方/回调/跳转链路时补 `#contract`;按风险补 regression |
+| L3 | `test-report.md#unit`, `#integration`, `#e2e`, `#smoke`, `#self-test` | 跨服务链路默认补 `#contract`;按风险补 `#perf`, `#regression` |
+
+报告按需聚合写在 `devflow/changes/<slug>/reports/test-report.md`。不要为凑 level 生成空 section；没执行对应测试就不要写对应 section。只有兼容旧工具时才显式加 `--split-report` 额外生成零散 markdown。
+
+每种报告的具体结构、必填字段、数据来源:见 [`references/report-templates.md`](references/report-templates.md)。
+
+## 每种报告的产出方式
+
+| kind | 生成方式 | 工具 |
+| --- | --- | --- |
+| unit-test | 自动 | `devflow test unit --cmd "<test command>"` |
+| integration-test | 自动 | `devflow test integration --cmd "<test command>"` |
+| contract-test | 自动/半自动 | `devflow test contract --cmd "<contract/check command>"`;可结合 `devflow sync yapi` 和 `devflow logs query` |
+| e2e-test | 半自动 | `devflow test e2e --cmd "..."` + 手动补充截图 / 视频链接 |
+| joint-test | 半自动 | `devflow test joint --cmd "..." --backend-url=... --frontend-url=...` + 浏览器操作 / 截图 |
+| remote-test | 自动/半自动 | `devflow test remote --preflight --api-base-url=... --cmd "..."` |
+| smoke-test | 手工 | 按模板手写(实际用户路径走一遍) |
+| self-test | 半自动 | `devflow report self-test` 脚手架 → 按 F-ID / AC 逐项手填证据 |
+| perf-test | 自动或半自动 | `devflow test perf --cmd "<jmh / wrk / k6 command>"` |
+| regression-test | 自动 | `devflow test regression --cmd "<回归 suite>"` |
+
+框架自动解析 9 种框架(Jest / Vitest / Mocha / Tap / node:test / Go / Pytest / unittest / JUnit)和 5 种 coverage 格式(JSON summary / LCOV / Cobertura / Go cover profile / JaCoCo XML),都能写进 frontmatter。
+
+报告的解析规则、自定义扩展、frontmatter 最小 / 推荐字段:见 [`references/report-templates.md`](references/report-templates.md)。
+
+## YAML frontmatter 契约
+
+每份报告**必须**包含:
+
+```yaml
+---
+slug: <change-slug>
+kind: unit | integration | contract | e2e | joint | remote | smoke | self-test | regression | perf
+status: pass | fail | partial | blocked
+failureType: code_error | env_error | -
+ts: <ISO datetime>
+---
+```
+
+推荐补充(生成器会自动填;手写时可选):
+
+```yaml
+total: 245
+passed: 243
+failed: 2
+skipped: 0
+duration_ms: 142300
+coverage:
+  lines: 86.4
+  branches: 78.1
+coveragePath: coverage/coverage-summary.json
+command: "mvn -pl coupon-service test"
+```
+
+`devflow verify finalize`、`devflow deliver` 里生成 PR 评论 都会读这些字段。缺失时会回退到简化展示。
+
+## Self-test 的严格性
+
+L2/L3 的 `test-report.md#self-test` 不是 "跑了下单元测试" 就算。它必须**逐个 F-ID / AC 留证据**:
+
+```markdown
+### F-01 | AC1: 批量提交 1000 条成功 → 返回 grantedCount=1000
+
+- **执行方式**:postman / curl 批量提交,query DB
+- **执行时间**:2026-04-24 14:00
+- **输入**:`users-1k.json`(附件)
+- **期望**:response.grantedCount = 1000
+- **实际**:response.grantedCount = 1000 ✅
+- **证据**:`reports/evidence/F-01-AC1-response.json`、`reports/screenshots/F-01-AC1-db.png`
+```
+
+self-test 书写规则 + AC 证据模板 + 反模式:见 [`references/self-test-guide.md`](references/self-test-guide.md)。
+
+## NFR 验证(L2/L3)
+
+design.md 里的 NFR(性能、并发、SLA)在 verify 阶段**必须**有对应报告数据支撑:
+
+| NFR 类型 | 验证手段 |
+| --- | --- |
+| P99 响应时间 | `test-report.md#perf`,基于负载测试工具输出 |
+| QPS / 吞吐 | `test-report.md#perf` |
+| 并发数 | `test-report.md#perf`(压测工具并发参数) |
+| 可用性(SLA) | 不在 verify 跑,但要写进 rollout plan |
+| 数据一致性 | `test-report.md#integration` 或 `#self-test` |
+| 调用链 / API 契约一致性 | `test-report.md#contract`；必要时附 YAPI 同步记录和 SLS/OSS 日志检索 |
+| 资源使用(CPU / mem) | `test-report.md#perf`(附 profiling 截图) |
+
+缺失 NFR 报告 → finalize 拒绝通过,除非用 `--accept-missing-nfr` 审计跳过(带 justification)。
+
+NFR 验证的具体方法、工具选型、基线对比:见 [`references/nfr-verification.md`](references/nfr-verification.md)。
+
+## Finalize
+
+```bash
+devflow verify finalize
+```
+
+执行内容:
+
+1. 扫描 `reports/` 下所有必需报告(根据 level)
+2. 读每份报告的 frontmatter(尤其 status)
+3. **全部 status=pass** → verify.status=completed,产出 `verify.md` 汇总
+4. 任一 fail / partial → finalize 拒绝;顾问给出回退建议(apply / tech-spec / requirement-analysis)
+5. 任一缺失 → 拒绝,提示补跑
+
+verify.md 本身 = 一份 dashboard(报告链接 + 结论),不重复内容。
+
+## 测试失败时的 Systematic Debug（必须先找根因）
+
+> 借鉴 **systematic-debugging** 原则：禁止"随手改一下试试"，每次修复前必须完成根因调查。
+
+```
+Iron Law: NO FIXES WITHOUT ROOT CAUSE FIRST
+
+测试失败 → 4 阶段必须顺序执行，不可跳跃：
+
+Phase 1 — 根因调查（先于任何改动）
+  1. 完整读错误信息（不要只看最后一行）
+  2. 确认：能稳定复现吗？每次都失败？
+  3. 查最近变更：git diff 里哪个改动最可能引入这个 fail？
+  4. 多组件系统：在每个边界加诊断输出，先跑一次看在哪层断
+
+Phase 2 — 模式分析
+  1. 找 codebase 里同类功能的正常写法
+  2. 对比"正常的"和"失败的"，列出所有差异
+  3. 确认依赖 / 环境 / 配置是否完整
+
+Phase 3 — 假设 + 最小验证
+  1. 写下一句话假设："我认为根因是 X，因为 Y"
+  2. 最小改动验证（只改一处）
+  3. 若验证失败 → 新假设，不要叠加修改
+
+Phase 4 — 修复
+  1. 先写回归测试（红 → 绿 验证）
+  2. 改根因，不改症状
+  3. 确认 exit 0 + 全量测试绿
+
+⛔ 红线（出现以下想法立刻停）：
+  - "先改几个地方看看哪个有效"
+  - "大概是 X 问题，改了再说"
+  - 尝试 3 次都没解决 → 停！可能是架构问题，回 tech-spec
+```
+
+## 失败后的回退路径
+
+| 失败情况 | 回退到 |
+| --- | --- |
+| unit / integration fail,代码 bug | apply |
+| e2e fail,集成问题 | apply(可能 tech-spec) |
+| self-test 发现 AC 没满足 | apply(回去实现;严重时 tech-spec 重新设计) |
+| perf-test 不达 NFR | tech-spec(重新设计)或申请修改 NFR(回到 requirement-analysis) |
+| smoke-test 发现 UX / 核心路径不通 | apply |
+| 回归测试挂(无关本次改动) | 记 ISSUE + 审计跳过(不阻塞本 slug) |
+
+每次回退都在 `state.iterations[]` 记一条("triggeredAt: verify")。
+
+verify 失败的完整回退决策树、审计格式、与 orchestrator 的交互:见 [`references/verify-rollback-map.md`](references/verify-rollback-map.md)。
+
+## 完成状态协议
+
+```
+---STATUS---
+result: DONE | BLOCKED | NEEDS_INPUT
+verifyStatus: pass | fail | partial | blocked
+outputs:
+  - devflow/changes/<slug>/verify.md
+  - devflow/changes/<slug>/reports/test-report.md
+reports:
+  unit: pass (243/245, cov 86.4%)
+  integration: pass (52/52)
+  e2e: pass (18/18)
+  smoke: pass
+  self-test: pass (12/12 F-ID, all AC met)
+  perf: pass (P99=180ms, NFR=200ms)
+failedReports: []
+nextAction: devflow deliver
+---END_STATUS---
+```
+
+## 反模式
+
+- **pass 前没有重跑最新代码**:上次 fix 后没重跑,结果 report 是旧的(frontmatter `ts` 字段会暴露:早于最后一次 commit)
+- **self-test 一笔带过**("按规格做了测试,通过了" 没 AC 证据)→ L2/L3 finalize 会拒绝
+- **截图超 1MB 嵌 markdown**:用 `reports/screenshots/` 相对链接
+- **跳过 perf-test 说"线下环境不准"**:至少跑一次拿基线,不达标则 stub + 真实环境补跑
+- **把 skipped 测试归为 pass**:frontmatter 的 skipped 字段要如实;大量 skip 需 explain
+- **finalize 前没清 flaky**:3 次跑 2 次过的测试要先 quarantine(+ 记 issue),不能"多跑几次过就算"
+- **把 verify.md 写得比 review.md 长**:verify.md 是 dashboard,不重复内容
+- **verify 不过就在 apply 偷偷改**:必须回退到 apply(更新 state、开新 iteration)
+- **把测试框架警告当错误**(or 反过来):status=pass/fail 的判定要看 frontmatter,不要看"视觉印象"
+
+## 参考
+
+- [`references/report-templates.md`](references/report-templates.md) — 每种 kind 的模板、frontmatter 字段语义、9 种测试框架 / 5 种 coverage 格式的识别规则
+- [`references/self-test-guide.md`](references/self-test-guide.md) — self-test 的 AC 证据书写规则、L1 / L2 / L3 深度要求、反模式
+- [`references/nfr-verification.md`](references/nfr-verification.md) — 性能 / 吞吐 / 可用性 / 资源的验证方法与工具选型
+- [`references/verify-rollback-map.md`](references/verify-rollback-map.md) — 失败 → 回退决策树 + 审计格式 + 与 orchestrator 的接口