@chenguangyao/devflow-kit 0.1.43

package/skills/requirement-analysis/references/code-recon.md

@@ -0,0 +1,151 @@
+# requirement-analysis / code-recon
+
+Round 2 的代码侦察方法论。目的:**把 agent 能自己回答的问题先答了,不要扔给用户**。侦察得好 = Round 2 问用户的问题从 10 个变成 2 个。
+
+---
+
+## 侦察范围(侦察什么)
+
+从 Round 1 的功能需求 + 用户故事里提取关键词,按下面维度扫:
+
+| 维度 | 侦察目标 | 用什么 |
+| --- | --- | --- |
+| **入口层** | 已有相关的 Controller / Handler / Route? | `Grep "<功能名>|<模块名>"` + `Glob` |
+| **服务层** | 已有相关的 Service / Manager? | `Grep "class.*Service"` |
+| **数据层** | 已有相关的 DAO / Mapper / ORM model? | `Grep "<表名>Repository|<Entity>"` |
+| **契约** | 已有 DTO / Request / Response? | `Glob "**/dto/**"` / OpenAPI 文件 |
+| **事件 / 消息** | 已有相关 event / topic? | `Grep "@EventListener|@KafkaListener"` |
+| **测试** | 已有相关的单元测试?(作为反向文档) | `Glob "**/<keyword>*Test*"` |
+| **配置** | 相关的 feature flag / config? | `Grep "<module>.enabled"` |
+| **文档** | README / ADR / runbook 里有没有约束? | `Grep -r "<keyword>" docs/` |
+
+## 侦察深度(侦察到什么程度)
+
+**按 level 决定**:
+
+| Level | 侦察深度 |
+| --- | --- |
+| **L1** | 读 1-2 个核心文件即可(主要看是否有兼容约束) |
+| **L2** | 绘制出"入口 → Service → DAO"一层调用链 + 找到复用点 |
+| **L3** | 绘制出完整跨模块调用关系 + 标注并发 / 事务边界 |
+
+不要**读全仓库**;侦察是"带问题去读",不是"读完再说"。
+
+## 侦察产物(怎么写进 requirement.md)
+
+侦察结果写进 `§5. 数据 / 接口影响` 的 "代码侦察结论" 子节:
+
+```markdown
+### 代码侦察结论
+- 主要改动位于: `<module>/<path>/<file>`
+- 复用的现有能力: `<ExistingService.method>`(行号 + 一句话用途)
+- 注意项:
+  - <事务 / 并发 / 兼容性坑>
+  - <已有的兼容逻辑不能破坏>
+  - <同类功能的 2 个实现要选一个>
+```
+
+**关键**:侦察结论要**可被 design.md 直接用**,而不是"我大概看了一下"。
+
+## 侦察后的追问(Round 2 问题)
+
+侦察会暴露 3 类只能问用户的问题:
+
+### 1. "多选一"(代码里有 ≥ 2 个同类实现)
+
+- 例:`GrantService` 和 `LegacyGrantService` 并存 → "本次在哪个上扩?"
+- 例:两个 `CouponController` 版本 → "v1 弃用了还是要兼容?"
+
+### 2. "契约语义"(代码里字段含义模糊,注释缺)
+
+- 例:`status` 字段的取值 1,2,3 含义不明 → "状态 1 是待发放还是已发放?"
+- 例:`batch_id` 是必填还是可空 → "NULL 语义是什么?"
+
+### 3. "跨系统依赖"(侦察到调用外部服务,但不知道能不能用)
+
+- 例:GrantService 调了 `billing.feign.GrantFeignClient` → "billing 服务对外接口是否已稳定?有没有 TTL?"
+
+## 侦察的停止条件(何时停)
+
+- 所有 F-ID 都能对应到现有代码(能扩) 或 确认不存在(全新)
+- "多选一" / "契约语义" / "跨系统依赖" 已经列出所有待问项
+- 读过的文件总数 ≤ 10(L2)或 ≤ 20(L3);超过说明偏题
+
+## 侦察时不要做的事
+
+- **不要改代码**:requirement 阶段就是读,不要一边读一边想动手
+- **不要越级**:不要试图在侦察中设计方案,那是 tech-spec 的事
+- **不要往 requirement 里塞实现细节**:requirement 只写"有啥、怎样配合",不写"Service 怎么拆"
+- **不要把 tests 当权威**:现有测试可能过时 / 低覆盖,仅做参考
+
+## 完整侦察示例(L2 新功能 `add-coupon-batch-grant`)
+
+### Step 1:从 F-ID 抽关键词
+
+F-01: 批量发放接口 → 关键词: `coupon`, `grant`, `batch`
+F-02: 风控逐条应用 → 关键词: `RiskService`
+F-03: 后台批量选择 → 关键词: `admin`, `upload`
+
+### Step 2:按维度扫
+
+```
+Grep "couponGrant" --glob "**/*.java" --type java
+Grep "class.*CouponController"
+Grep "class.*GrantService"
+Grep "class.*RiskService"
+Glob "**/coupon/controller/**"
+Glob "**/coupon/service/**"
+Grep "@Transactional" --glob "**/GrantService.java"
+```
+
+### Step 3:逐文件读关键段
+
+```
+Read coupon-service/src/main/java/.../GrantController.java        # 50 lines 起
+Read coupon-service/src/main/java/.../GrantService.java           # 看 grantOne 方法
+Read coupon-service/src/main/java/.../RiskService.java            # 看 check 方法签名
+```
+
+### Step 4:产出结论(写进 requirement.md §5)
+
+```
+### 代码侦察结论
+- 主要改动:
+  - 新增 `BatchGrantController`(在 controller/ 下)
+  - `GrantService.grantOne`(L125-L180)已有单发,复用
+- 复用:
+  - `RiskService.check(userId, templateId)`(L45-L72)  行为契约清楚,直接复用
+- 注意项:
+  - `GrantService.grantOne` 目前带 @Transactional,批量时**不要**继承外层事务(否则 N 倍 DB 连接占用)
+  - 历史有 `LegacyGrantController`,前端已不调用,本次不动
+  - `Coupon` 表没有 `batch_id` 字段,需要 DDL 加列
+```
+
+### Step 5:Round 2 追问(只问不能自己回答的)
+
+```
+Q1: GrantService.grantOne 的 @Transactional 在批量时建议如何处理?不继承外层事务,逐条独立提交?
+A1: 确认,逐条独立提交,部分失败的用户返回 failedUsers。
+
+Q2: 运营后台的 CSV 上传大小?
+A2: 1000 行上限,超出拒绝。
+```
+
+---
+
+## 侦察的"轻量 / 重量"决策
+
+| 信号 | 轻量(读 < 3 文件) | 重量(读 ≥ 5 文件 + 绘链路) |
+| --- | --- | --- |
+| L1 bug fix | ✓ | — |
+| L2 新功能,纯追加 | ✓ | — |
+| L2 修改现有逻辑 | — | ✓ |
+| L3 任何 | — | ✓ |
+| 触碰并发 / 事务路径 | — | ✓ |
+| 触碰跨服务契约 | — | ✓ |
+
+---
+
+## 本文与 SKILL.md 的关系
+
+SKILL.md 只提了"先 Grep / Glob 再问"。本文给完整侦察套路:侦察什么、侦察到多深、侦察产物怎么写、侦察后该问哪类问题、何时停、何时轻量 / 重量。agent 做 Round 2 前应读本文。

package/skills/requirement-analysis/references/edge-case-catalog.md

@@ -0,0 +1,164 @@
+# requirement-analysis / edge-case-catalog
+
+需求阶段 edge case 挖掘 catalog。按 8 个维度扫描,每个维度给常见问题 + 对应 AC 骨架。requirement.md §8 的边界场景就按这里选。
+
+---
+
+## 为什么在 requirement 阶段就挖?
+
+- 边界没挖透 → design 时漏考虑 → code-review 发现 MUST → 返工
+- 有些边界需要**业务确认**(如"部分失败算成功还是失败"),这是 business decision,不能在 apply 阶段临时拍
+- verify 阶段的 self-test 表按边界场景组织,没挖边界 = self-test 写不满
+
+---
+
+## 8 个维度
+
+1. 空 / 零 / null(Empty / Zero / Null)
+2. 极值 / 溢出(Extreme / Overflow)
+3. 重复 / 幂等(Duplicate / Idempotency)
+4. 并发 / 竞态(Concurrency / Race)
+5. 部分失败(Partial failure)
+6. 权限 / 越权(Authorization)
+7. 时区 / 本地化(Timezone / Locale)
+8. 依赖不可用(Dependency unavailable)
+
+---
+
+## 维度 1:空 / 零 / null
+
+| 问法 | 常见 AC 骨架 |
+| --- | --- |
+| 传空集合 | `Given [] → 400 EMPTY_INPUT`(不要返回 200 空) |
+| 必填字段为 null | `Given {name: null} → 400 FIELD_REQUIRED:name` |
+| 可选字段为 null | `Given {nickname: null} → 200(默认值或 null 沿用)` |
+| 0 值 | `Given {qty: 0} → 400 OR 视业务(如退款可 0?)` |
+| 空字符串 vs null | 统一:"", null, " " 都视为空?要明确 |
+| 默认值 | 不传字段与显式传 null 区别? |
+
+**常见坑**:后端 DTO 反序列化时 `null` 和"缺字段"不同,需业务明确。
+
+## 维度 2:极值 / 溢出
+
+| 问法 | 常见 AC 骨架 |
+| --- | --- |
+| 上限 | `Given N > 上限 → 400 OVER_LIMIT` |
+| 下限 | `Given N < 下限 → 400` |
+| 负数 | `Given -1 → 400 OR 视业务` |
+| 超大字符串 | `Given str.length > 1024 → 400 FIELD_TOO_LONG` |
+| 数字溢出 | `Given amount > Long.MAX → 400`(用 BigDecimal 替) |
+| Payload 过大 | `Given body > 1MB → 413 PAYLOAD_TOO_LARGE` |
+| 时间极值 | `Given time > 9999-12-31 → 400`(常见在解析时) |
+
+**常见坑**:单元测试不覆盖 INT_MAX / LONG_MAX → 线上压力测试才暴露。
+
+## 维度 3:重复 / 幂等
+
+| 问法 | 常见 AC 骨架 |
+| --- | --- |
+| 同参数 2 次调用 | 幂等接口:`Given 相同请求 → 第 2 次返回第 1 次的结果,不产生重复副作用` |
+| 非幂等接口重复 | 有唯一键:`Given 重复 payNo → 409 DUPLICATE`;无唯一键:业务决定 |
+| 批次内重复 | `Given batch 中有 2 个相同 userId → 去重处理,只产生一条 grant_log` |
+| 不同请求恰好相同 | 区分"业务重复" vs "网络重试";用 requestId / nonce 判 |
+
+**常见坑**:支付 / 扣款类接口未做幂等 → 重复扣款事故。
+
+## 维度 4:并发 / 竞态
+
+| 问法 | 常见 AC 骨架 |
+| --- | --- |
+| 同时扣减 | `Given qty=10 + 同时 -1 → 最终 qty=8(UPDATE ... SET qty=qty-1 WHERE qty>=1)` |
+| 乐观锁 | `Given 同时 UPDATE 同行 → 晚者 409 VERSION_CONFLICT` |
+| 分布式锁 | `Given 两节点同时处理 → 后者等待 OR 拒绝` |
+| 读写并发 | `Given 读时另一 session 改 → 读到一致快照(隔离级别)` |
+| 缓存一致性 | `Given DB 改后 → 缓存 N 秒后一致` |
+
+**常见坑**:单机测能过,多实例 / 多线程下炸。
+
+## 维度 5:部分失败
+
+**这是最常被用户忽略的维度**。批量、异步、外部调用都涉及。
+
+| 问法 | 常见 AC 骨架 |
+| --- | --- |
+| 批量里部分条目失败 | `Given 1000 人中 10 人失败 → 200 + grantedCount=990 + failedUsers=[{userId,reason}...]` |
+| 外部调用失败 | `Given 下游 timeout → 返回 500 + 记日志 + 不重试(避免雪崩)` |
+| 事务中途失败 | `Given step3 fail → 回滚 step1+2 所有副作用,metric 上报 rollback` |
+| 异步任务失败 | `Given 消费失败 → 重试 3 次 + 死信队列 + 告警 on-call` |
+| 长任务中途崩溃 | `Given 崩溃 → 可恢复:保存 checkpoint + 重启接续` |
+
+**业务要决策**:部分失败算"整体成功"还是"整体失败"?返回 200 还是 207 Multi-Status?前端怎么展示?
+
+## 维度 6:权限 / 越权
+
+| 问法 | 常见 AC 骨架 |
+| --- | --- |
+| 无 token | `401 UNAUTHORIZED` |
+| 过期 token | `401 TOKEN_EXPIRED + 前端自动跳登录` |
+| 无此权限 | `403 FORBIDDEN + errorCode=INSUFFICIENT_ROLE` |
+| 越权访问他人数据 | `403(不 404,避免泄漏资源存在)` |
+| 越权修改数据 | 同上 + audit log |
+| 越权提升权限 | `403 + trigger 安全告警` |
+| 特权账号日志 | 高权限操作(批量发放、改价、清数据) 必须 audit log |
+
+## 维度 7:时区 / 本地化
+
+| 问法 | 常见 AC 骨架 |
+| --- | --- |
+| 过期时间 | `过期时间基准 UTC 还是用户本地?必须明确` |
+| 跨时区查询 | `"今天" 按谁的时区定义?` |
+| 夏令时 | `涉及美国 / 欧洲时要小心 DST 跳跃` |
+| 字符集 | `Given emoji / 中文 → 不乱码(UTF-8)` |
+| 货币 | `金额单位:元还是分?int 还是 BigDecimal?` |
+| 日期格式 | `UI 显示按 locale,API 传输固定 ISO 8601` |
+
+## 维度 8:依赖不可用
+
+| 问法 | 常见 AC 骨架 |
+| --- | --- |
+| DB 不可用 | `Given DB down → 503 + 指标上报 + 不重试 / 快速失败` |
+| 缓存不可用 | `Given Redis down → 降级直连 DB(性能降) 或 快速失败(SLO 优先)` |
+| 下游超时 | `timeout 3s → 500 SERVICE_TIMEOUT + log + 不 block 用户` |
+| 下游 5xx | `下游返回 500 → 本接口如何处理?(重试 / 降级 / 透传)` |
+| 消息队列积压 | `消息积压 > N → 告警;消费延迟 > M → 告警` |
+
+---
+
+## 挖掘清单(每级任务的最少条数)
+
+| Level | §8 最少边界条数 | 必覆盖维度 |
+| --- | --- | --- |
+| **L1** | 4 | 空/null + 极值 + 权限 + 其他 1 个 |
+| **L2** | 8 | 前 6 个维度至少各 1 条 + 2 个自选 |
+| **L3** | 12 | 8 个维度全覆盖 + 4 个自选(重点:部分失败 / 并发 / 依赖不可用) |
+
+---
+
+## 挖掘流程(推荐)
+
+1. 读 requirement.md §3 功能需求表的每条 F-ID
+2. 对每个 F-ID,按维度 1-8 问一遍"这个场景下会怎样"
+3. 把相关的场景记到 §8 表里;不相关的**不要硬塞**(维度不适用时跳过)
+4. 对 **部分失败** 维度,主动问用户 → 这不是 agent 能替决策的
+5. 完成后对照"挖掘清单"看是否达到 Level 要求
+
+## 完整挖掘示例(add-coupon-batch-grant L2)
+
+```
+| 维度 | 场景 | 期望 | F-ID |
+| --- | --- | --- | --- |
+| 空 | userIds 空 | 400 EMPTY_BATCH | F-01 |
+| 极值 | 1001 人 | 400 BATCH_TOO_LARGE | F-01 |
+| 极值 | 0 人(意味着 userIds=[]) | 400 EMPTY_BATCH(同上) | F-01 |
+| 重复 | batch 内 userId 重复 | 去重,发一次 | F-01 |
+| 重复 | 同 batch 提交 2 次(网络重试) | 幂等:requestId 去重,第 2 次回 1 次结果 | F-01 |
+| 并发 | 两运营同一模板同一用户同时发 | 风控去重(同 userId 24h 内不重发) | F-02 |
+| 部分失败 | 10/1000 人风控拦截 | 200 + failedUsers 含 hitCode | F-02 |
+| 权限 | 普通运营(无 coupon:batch_grant) | 403 FORBIDDEN | F-01 |
+```
+
+---
+
+## 本文与 SKILL.md 的关系
+
+SKILL.md 列了 8 个维度表作为提醒。本文给每个维度的完整问法 + AC 骨架 + 挖掘密度要求。agent 在写 `§8 边界与异常` 时应逐个维度扫一遍。

package/skills/requirement-analysis/references/requirement-template.md

@@ -0,0 +1,339 @@
+# requirement-analysis / requirement-template
+
+`requirement.md` 的 9 段详细模板 + 字段语义 + 正反例 + 完整示例。
+
+---
+
+## 模板
+
+```markdown
+---
+slug: <slug>
+createdAt: <ISO>
+level: L1 | L2 | L3
+source: proposal | ingest
+refs:
+  - <refs/source.md 或 proposal.md>
+---
+
+# Requirement: <one-line title>
+
+## 1. 业务背景
+<从 proposal / refs 提炼;1-2 段文字,不要粘贴整个 Wiki>
+
+## 2. 用户故事
+- As a <角色>, I want <能力>, so that <收益>.
+- ...
+
+## 3. 功能需求
+| F-ID | 标题 | 描述 | AC(可验收) |
+| --- | --- | --- | --- |
+| F-01 | <一句话标题> | <更详细描述> | <Given...When...Then...> |
+| F-02 | ... | ... | ... |
+
+## 4. 非功能需求
+### 性能
+- <具体数值 + 场景>
+
+### 安全 / 合规
+- <涉及的敏感数据 + 合规要求>
+
+### 可观测性
+- <要加的指标 / 告警>
+
+### 可用性 / 灰度 / 回滚
+- <SLO / 灰度比例 / 回滚步骤>(L3 必填)
+
+## 5. 数据 / 接口影响
+### DDL 变更
+- <新表 / 新列 / 索引调整>
+
+### 契约变更
+| 接口 | 类型 | 变更点 |
+| --- | --- | --- |
+| POST /xxx | 新增 | ... |
+| PUT /yyy | 修改 | 新增字段 z |
+
+### 事件 / 消息
+- <新增事件 / 修改 topic 语义>
+
+### 代码侦察结论(Round 2 后填)
+- 主要改动位于: `<module>/<path>/<file>`
+- 复用的现有能力: `<ExistingService.method>`
+- 注意项: <已有的兼容逻辑 / 坑点>
+
+## 6. Round 1 Q&A(业务侧)
+| # | 问题 | 回答 | 结论影响到的 section |
+| --- | --- | --- | --- |
+| Q1 | ... | ... | §3 F-01 |
+| Q2 | ... | ... | §4 perf |
+
+## 7. Round 2 Q&A(实现侧)
+| # | 问题 | 回答 | 结论 |
+| --- | --- | --- | --- |
+| Q1 | ... | ... | ... |
+
+## 8. 边界与异常
+| 维度 | 场景 | 期望行为 | 对应 F-ID |
+| --- | --- | --- | --- |
+| 空输入 | 传空用户列表 | 返回 400 BAD_REQUEST, code=EMPTY_BATCH | F-01 |
+| 超限 | 传入 1001 人 | 返回 400, code=BATCH_TOO_LARGE | F-01 |
+| 部分失败 | 10/1000 被风控拦截 | 返回 200 + partialSuccess:true, hitList:[...] | F-02 |
+| ... | ... | ... | ... |
+
+## 9. 风险与遗留(Risks & Open issues)
+- **[Open]** <未解决的问题,带 owner 和 deadline>
+- **[Risk]** <已知的风险 + 缓解策略>
+```
+
+---
+
+## 字段语义详述
+
+### 1. 业务背景(Business background)
+
+**目的**:帮 downstream phase(特别是 code-review 和 archive)理解**为什么要做这事**,不是复述 PRD。
+
+**好**:1-2 段,含关键数据(现状、痛点、预期改善)。
+
+**反例**:
+
+> ~~~
+> 业务需要一个批量发券功能。详情见 PRD 链接 xxx。
+> ~~~
+> (没有提炼,相当于没写。)
+
+**正例**:
+
+> 现状:Q3 优惠券运营以单发接口为主,平均每场活动需手动发 300-500 次,耗时 1-2 小时 / 场。
+> 痛点:大促期间单场次发放峰值可达 1000+,人肉不可能完成;运营只能放弃或提前拉 DBA 脚本。
+> 本次目标:提供批量发放接口 + 运营后台,把单场耗时压到 ≤ 10 分钟。
+
+---
+
+### 2. 用户故事
+
+**格式**:`As a <角色>, I want <能力>, so that <收益>`(INVEST 原则,详见 acceptance-criteria.md)。
+
+**反例**:
+
+> ~~作为开发,我想写这个接口~~
+> (开发不是最终用户)
+
+**正例**:
+
+> - As a 运营专员, I want 在管理后台选择用户列表并一次发放优惠券, so that 不用手动操作 300 次。
+> - As a 风控管理员, I want 批量发放仍逐条应用风控规则, so that 活动合规不破口。
+
+---
+
+### 3. 功能需求
+
+**F-ID 规范**:
+
+- 格式 `F-<NN>`,F-01 起编号
+- **一旦创建,永不重用**(即使后来删除,也不要把 F-07 重新分配给新功能 —— 避免引用歧义)
+- 可以扩展为 `F-01.1` / `F-01.2` 表示子项
+
+**AC 写法**:每条都是可自动化验证的单句(或 Given-When-Then 三段式)。详见 acceptance-criteria.md §2。
+
+**最小完整度**:L1 ≥ 1 条 F-;L2 ≥ 3 条;L3 ≥ 5 条。少于此数意味着 requirement 拆得太粗。
+
+---
+
+### 4. 非功能需求
+
+四个常见维度(按 level 要求):
+
+| 维度 | L1 | L2 | L3 |
+| --- | --- | --- | --- |
+| 性能 | 可略(不劣化) | 具体数值 | SLO + 压测 |
+| 安全 | 无敏感数据可略 | 校验 + 脱敏 | + 合规审计 + 数据流图 |
+| 可观测性 | 现有日志即可 | 新增指标 + 告警 | 指标 + 告警 + runbook |
+| 可用性 / 灰度 | 可略 | 简单 flag | 分批灰度 + 回滚预案 |
+
+**反例**:
+
+> ~~性能要好,安全要严~~
+
+**正例**:
+
+> ### 性能
+> - 批量接口 P99 ≤ 3s(1000 人场景)
+> - 批量接口 QPS 峰值 20,不退化现有单发的 TP99
+>
+> ### 安全
+> - 批量接口鉴权沿用现有 token,并额外校验运营角色权限 `coupon:batch_grant`
+> - 日志中用户手机号 / 身份证 脱敏到后 4 位
+>
+> ### 可观测性
+> - 新增指标 `coupon.batch_grant.latency`(histogram,P99 告警阈值 5s)
+> - 新增指标 `coupon.batch_grant.success_rate`(gauge,告警阈值 < 99%)
+>
+> ### 可用性 / 灰度
+> - 灰度 1% → 10% → 50% → 100%,各阶段观测 2 小时
+> - 回滚预案:关闭 feature flag `coupon.batch.enabled`
+
+---
+
+### 5. 数据 / 接口影响
+
+**DDL 原则**:
+
+- 列出所有新表 / 新列 / 索引变更;每个带类型、长度、NOT NULL、COMMENT
+- 标注幂等性(`CREATE TABLE IF NOT EXISTS` / `ALTER TABLE ADD COLUMN IF NOT EXISTS`)
+
+**契约原则**:
+
+- 每个变更接口一行,标"新增 / 修改 / 删除"
+- 兼容性:是否 breaking?旧客户端是否受影响?
+
+**事件 / 消息**:
+
+- 新增 topic:列出 schema
+- 修改已有 topic:标注是否 wire-compatible
+
+**代码侦察结论**:Round 2 的结果,让 design 阶段直接可用。详见 `code-recon.md`。
+
+---
+
+### 6-7. Round 1 / Round 2 Q&A
+
+**目的**:审计留档,**不是摘要**。每条记下来:
+
+- 原始问题(不改写)
+- 用户原始回答
+- 结论影响到的 section(F-ID / 具体非功能项)
+
+**反例**:
+
+> ~~Round 1: 问了业务相关问题,都明确了~~
+> (没留档无法审计)
+
+**正例**:
+
+```
+## 6. Round 1 Q&A
+| # | 问题 | 回答 | 影响 section |
+| --- | --- | --- | --- |
+| Q1 | 单次批量上限? | 1000(运营最大需求),超出走多次调用 | §3 F-01 + §8 超限 |
+| Q2 | 部分失败怎么返回? | 返回 200 + 每用户状态列表,运营自行重试 | §3 F-02 + §8 部分失败 |
+| Q3 | 需要独立风控放行吗? | 不需要,沿用单发同规则 | §3 F-02 + §4 安全 |
+```
+
+---
+
+### 8. 边界与异常
+
+完整 catalog 见 `edge-case-catalog.md`。
+
+**最小完整度**:L1 ≥ 4 条,L2 ≥ 8 条,L3 ≥ 12 条。
+
+---
+
+### 9. 风险与遗留
+
+两个子类:
+
+- **[Open]**:当前未解决的问题,写 owner + deadline;若 Open issue 属于 P0,Round 1 不允许结束
+- **[Risk]**:已知风险 + 缓解策略(如"下游 grant API 9/25 才 ready,若延迟将影响提测")
+
+---
+
+## 完整示例(L2 新功能)
+
+```markdown
+---
+slug: add-coupon-batch-grant
+createdAt: 2026-04-24T10:15:00+08:00
+level: L2
+source: proposal
+refs:
+  - devflow/changes/add-coupon-batch-grant/proposal.md
+---
+
+# Requirement: 批量发放优惠券
+
+## 1. 业务背景
+现状:Q3 起运营使用单发接口发放活动券,平均 1 场活动 300-500 次手动操作,耗时 1-2h/场。
+痛点:Q4 大促预计峰值 1000+/场,人工不可完成。
+目标:提供批量发放接口 + 管理后台,单场 ≤ 10 分钟。
+
+## 2. 用户故事
+- As a 运营专员, I want 选择用户清单一次性发券, so that 单场操作 ≤ 10 分钟。
+- As a 风控管理员, I want 批量发放每条走同一风控, so that 活动合规不破口。
+
+## 3. 功能需求
+| F-ID | 标题 | 描述 | AC |
+| --- | --- | --- | --- |
+| F-01 | 批量发放接口 | POST /api/v2/coupon/batch-grant | Given 1000 个 userId + 一个 couponTemplateId, When 调用, Then 返回 200,body 含 grantedCount/failedCount/failedUsers,耗时 ≤ 3s |
+| F-02 | 风控逐条应用 | 每个 user 走单发的同风控路径 | Given 100 用户中有 10 个命中风控, When 批量发放, Then failedUsers 含这 10 人 + hitCode;成功 90 人 |
+| F-03 | 运营后台批量选择 | 支持文件导入 CSV / 查询条件圈选 | Given 运营上传 1000 行 CSV, When 点击"发放", Then 展示确认页 + 预估命中风控数 + 点击确认后调用 F-01 |
+
+## 4. 非功能需求
+### 性能
+- F-01 P99 ≤ 3s(1000 人场景);QPS 峰值 20
+
+### 安全
+- 运营需权限 `coupon:batch_grant`(新增),仅高级运营可操作
+- 日志手机号脱敏
+
+### 可观测性
+- 指标 `coupon.batch.latency` P99 告警 5s
+- 指标 `coupon.batch.error_rate` 告警 1%
+
+### 可用性 / 灰度
+- Feature flag `coupon.batch.enabled`
+- 回滚:关闭 flag
+
+## 5. 数据 / 接口影响
+### DDL
+- 新增索引 `idx_grant_batch_id` 在 `coupon_grant(batch_id)`(IF NOT EXISTS)
+- 新增列 `batch_id VARCHAR(36) NULL COMMENT '批次号'`(IF NOT EXISTS)
+
+### 契约
+| 接口 | 类型 | 变更点 |
+| --- | --- | --- |
+| POST /api/v2/coupon/batch-grant | 新增 | 全新接口 |
+| POST /api/v1/coupon/grant | 不变 | 保持兼容 |
+
+### 代码侦察结论
+- 主要改动:`coupon-service/BatchGrantController`(新增)、`coupon-service/GrantService.grantOne`(已有,复用)
+- 复用:`RiskService.check`(已有,不动)
+- 注意:`GrantService.grantOne` 目前带 `@Transactional`,批量时要改调用方式,详见 design.md
+
+## 6. Round 1 Q&A
+| # | 问题 | 回答 | 影响 |
+| --- | --- | --- | --- |
+| Q1 | 单次上限? | 1000 | §3 F-01 + §8 |
+| Q2 | 部分失败如何返回? | 200 + failedUsers 列表 | §3 F-01 + §8 |
+| Q3 | 需独立风控? | 否,沿用 | §3 F-02 |
+| Q4 | 灰度策略? | 上线先 1% flag,运营后台先内测 5 人 | §4 灰度 |
+
+## 7. Round 2 Q&A
+| # | 问题 | 回答 |
+| --- | --- | --- |
+| Q1 | GrantService.grantOne 目前是 @Transactional,批量时怎么处理? | 不继承事务,逐条独立提交 |
+| Q2 | 运营后台文件导入支持多大? | CSV 1000 行上限 |
+
+## 8. 边界与异常
+| 维度 | 场景 | 期望行为 | F-ID |
+| --- | --- | --- | --- |
+| 空输入 | 传空 userIds | 400 EMPTY_BATCH | F-01 |
+| 超限 | 1001 人 | 400 BATCH_TOO_LARGE | F-01 |
+| 无权限 | 普通运营调接口 | 403 FORBIDDEN | F-01 |
+| 部分失败 | 10/1000 命中风控 | 200 + 部分成功 | F-02 |
+| 重复 | 同一 userId 在 batch 内出现 2 次 | 去重后发一次,返回一次 | F-01 |
+| 不存在 template | templateId 不存在 | 400 TEMPLATE_NOT_FOUND | F-01 |
+| 并发 | 两运营同时批量发同模板给同人 | 风控去重 | F-02 |
+
+## 9. 风险与遗留
+- **[Risk]** CSV 编码若是 GBK 可能解析错;本次要求 UTF-8 only,文案提示。
+- **[Open]** 运营后台是否需要"发放历史回查"?Q: Alice @ PM,A: 本次不做,下期(SCRUM-15901)。
+```
+
+---
+
+## 本文与 SKILL.md 的关系
+
+SKILL.md 给了 9 个 section 标题和 Level 要求表。本文给完整模板、每段的字段语义、正反例、完整示例。所有 agent 在写 `requirement.md` 时应以本文的完整示例为参照。