@chenguangyao/devflow-kit 0.1.43

package/skills/tech-spec/references/api-contract-design.md

@@ -0,0 +1,172 @@
+# tech-spec / api-contract-design
+
+API 契约设计原则(REST / GraphQL / gRPC / 事件)、版本化、字段演进。这是 design.md §5 的写作依据。
+
+---
+
+## 通用原则
+
+1. **契约是外部承诺**:签了就要兑现;改契约要按版本化流程,不要就地改语义
+2. **只加字段,不删不改**:客户端忽略未知字段,所以加字段是**非 breaking**;删字段 / 改语义必然 breaking
+3. **字段默认可空 + 默认值明确**:新增必填字段 = breaking;新增可空字段 = 非 breaking
+4. **错误码集中管理**:不要每个 Controller 各自定义一套,集中到 `ErrorCode` enum 或 yaml
+5. **幂等性显式标注**:文档里写清楚 GET/DELETE 幂等、POST 是否幂等(通过什么 key)
+
+---
+
+## REST 契约
+
+### URL 设计
+
+- 资源用名词复数:`/api/v1/coupons`,不是 `/api/v1/getCoupon`
+- 层级反映归属:`/api/v1/users/{userId}/coupons`
+- 动作用 HTTP 动词表达:POST 创建 / GET 读 / PUT 替换 / PATCH 改 / DELETE 删
+- 不得已的动作类路径:`/api/v1/coupons/{id}:revoke`(冒号分隔,RFC 7320 允许)
+
+### 版本化
+
+- URL 路径版本:`/api/v1/`(简单,推荐)
+- Header 版本:`Accept: application/vnd.company.v1+json`(复杂,不推荐)
+- **新能力开 v2**:`/api/v2/coupon/batch-grant`;v1 /v2 并存一段时间,v1 加 Sunset header
+- **破坏性改动不要就地改 v1**
+
+### 状态码语义
+
+| code | 含义 | 例 |
+| --- | --- | --- |
+| 200 | 成功 | 正常返回 |
+| 201 | 已创建 | POST 资源成功 + Location header |
+| 204 | 无内容 | DELETE / PUT 成功不需要 body |
+| 400 | 客户端错(请求无效) | 参数错、逻辑冲突 |
+| 401 | 未认证 | 缺 token / token 无效 |
+| 403 | 无权限 | token 有效但角色不够 |
+| 404 | 不存在 | 注意:越权访问他人数据返回 403 而非 404(避免泄漏存在性) |
+| 409 | 冲突 | 唯一键、乐观锁失败 |
+| 410 | 已删除 | 资源已被移除,永久 |
+| 413 | Payload 过大 | body 超限 |
+| 429 | 限流 | 带 Retry-After header |
+| 500 | 服务端错 | 兜底 |
+| 503 | 服务不可用 | 降级 / 维护 / flag 关闭 |
+
+### 错误 body 格式(推荐统一)
+
+```json
+{
+  "code": "BATCH_TOO_LARGE",
+  "message": "批量上限 1000,当前 1001",
+  "traceId": "a1b2c3",
+  "details": {
+    "limit": 1000,
+    "actual": 1001
+  },
+  "suggestion": "拆分为多次调用"
+}
+```
+
+统一格式的好处:客户端可写通用错误处理;测试容易断言。
+
+### 分页 / 排序 / 筛选
+
+- 分页:`?cursor=xxx&limit=50`(cursor 优于 offset,大 offset 慢)
+- 排序:`?sort=-createdAt,name`(前缀 `-` 降序)
+- 筛选:`?status=active&tag=vip`(简单 eq) 或 `?filter=status eq 'active'`(复杂 DSL)
+
+---
+
+## gRPC 契约
+
+### Proto 演进规则
+
+- **字段 tag 永远不重用**:删了字段标 `reserved 5;`,新字段用下一个 tag
+- **只加新字段,不删旧字段**(删了会 breaking)
+- **enum 加值**:放在最末,不要插中间;protobuf 未知值自动设为 0,要小心默认值语义
+
+### 不要做的事
+
+- 改字段 name(序列化按 tag,但 stub 代码会 breaking)
+- 改字段 type(bool → int 等)
+- 把 `optional` 变 `required`(proto3 已没 required,proto2 别改)
+- 重用已 deprecated 的 tag 号
+
+### 错误模型
+
+- 用 `google.rpc.Status` 标准(code + message + details[])
+- details 里塞 `ErrorInfo`、`BadRequest.FieldViolation`、`RetryInfo` 等标准类型
+
+---
+
+## GraphQL 契约
+
+- Schema 里**加字段 / 加类型 / 加参数** 都不 breaking
+- 删字段 / 改类型 / 改 non-null 性都 breaking
+- 弃用用 `@deprecated(reason: "...")`,不要删
+- 查询深度限制 / 复杂度限制(防 N+1 查询攻击)
+
+---
+
+## 事件 / 消息契约
+
+### 基本字段(建议每个事件都有)
+
+```json
+{
+  "eventId": "evt_<uuid>",          // 幂等 key
+  "eventType": "coupon.granted",     // 类型,形如 <bounded-context>.<past-tense-verb>
+  "eventVersion": "v1",              // schema 版本
+  "occurredAt": "<ISO>",             // 事件发生时间
+  "producer": "coupon-service",      // 生产者
+  "traceId": "<...>",                // 追踪
+  "payload": { ... }                 // 业务字段
+}
+```
+
+### 事件版本化
+
+- schema 只加字段,不删不改
+- 重大变更 → 新 topic(`coupon.granted.v2`),旧 topic 沉默直到无消费者
+- 消费者**必须**能忽略未知字段(forward-compat)
+
+### 幂等消费
+
+- `eventId` 做消费者的幂等 key:已处理过直接跳过
+- 消费者要能处理重复投递(at-least-once 是常态)
+
+---
+
+## 字段设计常见陷阱
+
+| 陷阱 | 好做法 |
+| --- | --- |
+| `status: "active"` 字符串 enum | 用真正的 enum 类型(proto)或明确值列表(OpenAPI) |
+| 金额用 float / double | 用 decimal / BigDecimal / long(最小单位"分") |
+| 时间戳用 int 秒 | 明确时区;用 ISO-8601 字符串或 unix millis long |
+| 布尔字段歧义(`isEnabled` vs `isDisabled`) | 用正向命名(enabled),避免双重否定 |
+| 手机号 / 身份证用 int / long | 用 string(保留前导 0 + 避免溢出) |
+| 错误信息放 `message` 字段但没有 `code` | 永远先给 code(机器可读),再给 message(人可读) |
+| 把 list 字段命名成单数 | list 字段复数(users),scalar 字段单数(userId) |
+| 时间段用 startDate+endDate 但语义模糊 | 明确 "左闭右开 [start, end)" 还是 "闭区间 [start, end]" |
+
+---
+
+## 版本共存策略
+
+| 场景 | 策略 |
+| --- | --- |
+| 旧 v1 仍有流量 | v1/v2 并行;v1 逐步灰度减量 |
+| v1 完全没流量 | v1 标 deprecated,6 个月后删除(留足客户端升级时间) |
+| 灰度切换 | 按 userId hash 或 feature flag 分流(一个用户一直走同一版,防抖动) |
+| 内部服务切换 | 双写 + 对账期 + 切读 + 下线旧路径 |
+
+---
+
+## 契约 / 代码 / 文档一致性
+
+- **Contract-first**:先定义 spec(OpenAPI / proto / GraphQL schema),再生成代码
+- **Single source of truth**:spec 文件 check in 仓库,CI 校验"实现与 spec 一致"
+- **Review 时对 spec 改动严格**:spec 改动 = API breaking 警告,要 ADR 级审查
+
+---
+
+## 本文与 SKILL.md 的关系
+
+SKILL.md 给了契约设计 4 条原则。本文扩展为 REST / gRPC / GraphQL / 事件的具体规则 + 版本化策略 + 字段设计陷阱。tech-spec 写 §5 契约时应按本文规则校对每个接口。

package/skills/tech-spec/references/decision-records.md

@@ -0,0 +1,110 @@
+# tech-spec / decision-records
+
+ADR-lite(Architecture Decision Record)在 design.md 里的嵌入式写法。不是"每个设计都写 ADR",只对**值得未来回顾的关键决策**写。
+
+---
+
+## 什么决策值得记 ADR
+
+| 值得 | 不值得(用默认) |
+| --- | --- |
+| 选了数据库 / 存储 / 中间件(Redis vs Memcached、MySQL vs PG) | 选了哪个 JSON 解析库 |
+| 一致性模型(强一致 / 最终 / Saga / TCC) | 每个方法的命名 |
+| 同步 / 异步 / 消息驱动 | 日志格式 |
+| 通信协议(REST vs gRPC vs GraphQL) | 变量命名风格 |
+| 容错策略(重试 / 降级 / 快速失败) | 缩进 |
+| 鉴权模型(JWT vs session、自建 vs SSO) | — |
+| 分片 / 分表 / 分库方案 | — |
+| 灰度方案(flag vs 分流 vs 机房切) | — |
+
+**判据**:如果 6 个月后团队换人问"当时为啥这么做",答不出就写 ADR。
+
+---
+
+## ADR-lite 模板(内嵌在 design.md §11 或独立章节)
+
+```markdown
+### ADR-<NN>: <一句话结论>
+
+**Context**:<为什么要做这个决策;关键约束>
+**Decision**:<选了什么>
+**Alternatives considered**:
+  - <备选 1>:<为什么没选>
+  - <备选 2>:<为什么没选>
+**Consequences**:
+  - 正面:<好处>
+  - 负面:<我们知道的代价 / 未来要承担的成本>
+**Reversal trigger**:<什么情况下我们会回过头推翻这个决策>
+```
+
+---
+
+## 示例 ADR
+
+### ADR-01: 批量发放用同步 API 而非异步任务
+
+**Context**:运营需要批量发券,峰值预估 1000 人/批、20 QPS。当前无运营侧的"任务中心"UI,做异步需要新增前端组件与后端任务状态机。
+**Decision**:同步 HTTP API + 内部循环 grantOne(每条独立事务)。
+**Alternatives considered**:
+- 方案 B(异步 + 消息队列):吞吐更好,但 UI 成本 + 状态机复杂,放弃
+- 方案 C(客户端并发调单发):风控会误判,放弃
+**Consequences**:
+- 正面:开发 1 周;无 UI 变更;运营立即可用
+- 负面:1000 人场景 P99 ≈ 3s,接口超时时间必须 ≥ 5s;单实例批量 QPS 有限(≤ 20)
+**Reversal trigger**:峰值 > 50 QPS 或单批 > 5000 时需切异步;届时方案 B 可无损迁移(API 外观不变)。
+
+---
+
+### ADR-02: RiskService 失败时批量整体降级为"全部跳过风控 + 单独告警"
+
+**Context**:批量发放场景下,如 RiskService 偶发不稳定,是"直接整批失败"还是"允许跳过风控 + 告警"?业务方希望活动不中断。
+**Decision**:当本批 RiskService 连续 5 次超时,切换到"skip 风控"模式,所有用户不经风控直接发券,但**所有 skip 的记录打标**并触发告警;直到 RiskService 恢复前保持 skip。
+**Alternatives considered**:
+- A:整批失败(最安全,但业务中断)
+- B:按用户单独重试 3 次后 skip(折中,但代码复杂)
+**Consequences**:
+- 正面:业务连续性有保证
+- 负面:风控被短暂跳过的用户需要事后对账;加了一个"降级状态"要维护
+**Reversal trigger**:若合规要求零 skip(如金融业务),改为 A。
+
+---
+
+## 写 ADR 的常见误区
+
+1. **光写 Decision 不写 Alternatives**:看不到"为什么不是别的",无法审计
+2. **Alternatives 全是稻草人**(故意列很差的选项衬托)→ reviewer 能看出来
+3. **不写 Reversal trigger**:决策没有"退出条件",未来很难推翻
+4. **把 ADR 写成很长的设计稿**:ADR 是决策**摘要**,每条 ≤ 10 行;细节放 design.md 正文
+5. **一个设计堆 10 个 ADR**:2-3 个关键决策就够了;不重要的决策用默认,不写
+
+---
+
+## ADR 与 design.md §11 alternatives 的关系
+
+**两种可合并**:把 ADR 当作 §11 的结构化形式。
+**也可独立**:L3 或长期项目,ADR 单独放 `devflow/changes/<slug>/adr/ADR-01-<slug>.md`；默认 workspace 模式放到 `~/.devflow/workspace/changes/<feature-xx>/adr/`。archive 阶段再归档到当前需求的 `knowledge/架构决策/` 存底。
+
+推荐:
+
+| Level | 建议 |
+| --- | --- |
+| L1 | 无 ADR(决策都是琐碎的) |
+| L2 | ≤ 2 个 ADR,内嵌在 §11 |
+| L3 | 2-5 个 ADR,默认放 `~/.devflow/workspace/changes/<feature-xx>/adr/`;历史 in-repo 模式可放 `devflow/changes/<slug>/adr/` |
+
+---
+
+## 归档到 knowledge/架构决策/
+
+`devflow archive` 时:
+
+- 若 design.md / `adr/*.md` 里有 "Reversal trigger" 字段 → 把 ADR 抽出来复制到当前需求知识目录：
+  - 单服务：`<repo>/devflow/knowledge/架构决策/ADR-<slug>-<NN>.md`
+  - 默认 workspace：`~/.devflow/workspace/changes/<feature-xx>/knowledge/架构决策/ADR-<slug>-<NN>.md`
+- 这样下次别人做类似决策时可以 `devflow knowledge query "异步 vs 同步"` 找到历史依据
+
+---
+
+## 本文与 SKILL.md 的关系
+
+SKILL.md 提了"决策 vs 记账"方法论;本文给 ADR-lite 的具体模板、示例、常见误区。写 design.md §11 alternatives 时直接用本文的 ADR 模板,不要自由发挥。

package/skills/tech-spec/references/design-template.md

@@ -0,0 +1,301 @@
+# tech-spec / design-template
+
+`design.md` 的 11 段详细模板、每段字段语义、正反例。附一个 L2 完整示例。
+
+---
+
+## 模板
+
+```markdown
+---
+slug: <slug>
+createdAt: <ISO>
+level: L1 | L2 | L3
+version: v1
+revisionLog:
+  - v1: 初始版本
+refs:
+  - requirement.md
+---
+
+# 技术方案: <一句话标题>
+
+## 1. 方案摘要
+<一段话,最多 5 句;一个完全不了解本事的人读完能说出"原来是这样做的">
+
+## 2. 目标 / 非目标
+### 目标(重申 requirement 的目标,不增不减)
+- ...
+### 非目标(从 Out of scope + 本次不解决的隐含需求)
+- ...
+
+## 3. 架构影响(组件)
+<mermaid 或 ASCII 组件图。只画变化的边;用星号标出新建/修改/删除>
+
+## 4. 改动点汇总
+| 文件 / 类 / 方法 | 类型 | 对应 F-ID | 说明 |
+| --- | --- | --- | --- |
+| coupon-service/BatchGrantController(新建) | 新建 | F-01 | 新增接口入口 |
+| coupon-service/GrantService#grantOne | 复用 | F-02 | 复用 |
+| ... | ... | ... | ... |
+
+## 5. 契约定义
+### 请求 / 响应
+```http
+POST /api/v2/coupon/batch-grant
+Content-Type: application/json
+
+{
+  "userIds": ["u1","u2",...],     // required, 1-1000
+  "couponTemplateId": "ct_123",   // required
+  "batchId": "b_uuid"              // optional, 幂等 key
+}
+
+→ 200 OK
+{
+  "grantedCount": 990,
+  "failedCount": 10,
+  "failedUsers": [{"userId":"u10", "reason":"RISK_HIT", "hitCode":"R001"}]
+}
+```
+
+### 错误码
+| code | http | 含义 |
+| --- | --- | --- |
+| EMPTY_BATCH | 400 | 空输入 |
+| BATCH_TOO_LARGE | 400 | > 1000 |
+| TEMPLATE_NOT_FOUND | 400 | 不存在 |
+| FORBIDDEN | 403 | 无权限 |
+| INSUFFICIENT_STOCK | 409 | 券库存不足 |
+| SERVICE_DISABLED | 503 | flag 关闭 |
+
+### 事件 / 消息
+- <新增 topic schema,或复用现有 topic 并说明>
+
+### YAPI / OpenAPI 同步
+- 契约文件:<openapi.json / swagger.json / api.md>
+- 同步命令:`devflow sync yapi --file=<file> --dry-run`
+- 同步策略:新增 / 覆盖 / 合并;说明分类(category)和 owner
+
+## 6. 数据层
+### DDL
+```sql
+ALTER TABLE coupon_grant ADD COLUMN IF NOT EXISTS batch_id VARCHAR(36) NULL
+  COMMENT '批次号,null 表示单发';
+
+CREATE INDEX IF NOT EXISTS idx_grant_batch_id ON coupon_grant(batch_id);
+```
+- 幂等:✓
+- 回滚:`DROP COLUMN IF EXISTS` + `DROP INDEX IF EXISTS`
+- 容量评估:新列 VARCHAR(36) × 当前 1 亿行 ≈ 3.6 GB(可接受)
+
+### 数据迁移
+<若涉及双写 / 回填,详见 rollout-and-rollback.md>
+
+## 7. 关键流程
+### 成功路径
+```mermaid
+sequenceDiagram
+  Client->>+BatchGrantController: POST /batch-grant (1000 userIds)
+  BatchGrantController->>+GrantService: for each userId: grantOne
+  GrantService->>+RiskService: check(userId, templateId)
+  RiskService-->>-GrantService: pass/hit
+  alt pass
+    GrantService->>+DB: INSERT grant_log + batch_id
+    DB-->>-GrantService: ok
+  end
+  GrantService-->>-BatchGrantController: result
+  BatchGrantController-->>-Client: 200 {granted, failed}
+```
+
+### 失败路径:下游 RiskService 超时
+<sequence diagram;展示 timeout → 降级 → 指标上报 的流程>
+
+### 调用链一致性验证
+- traceId / requestId 传递点:<入口 / 服务调用 / 回调 / 异步消息 / 前端轮询>
+- 调用方一致性:<字段 / 枚举 / 状态语义 / redirect/query / callback>
+- 日志检索:`devflow logs query --trace-id=<id>` 或 `--request-id=<id>`，provider 可为 SLS / OSS
+- 报告:`devflow test contract --cmd="<contract/check command>"`
+
+## 8. 错误处理 / 事务 / 回滚
+- 批量接口**不使用**外层事务;每个 userId 独立 try-catch 独立 commit
+  - 理由:部分失败语义 + 避免 1000 条连一个事务(长事务 + 行锁压力)
+- 重复 batchId:DB `UNIQUE (batch_id, userId)` 约束 + upsert 幂等
+- 下游超时:3s 超时 + 快速失败 + 落 failedUsers reason=DOWNSTREAM_TIMEOUT
+- 数据不一致容忍:允许 grant_log 落库成功但缓存未刷新(1 分钟后一致)
+
+## 9. 可观测性
+### 指标
+| name | type | 触发点 | 告警阈值 |
+| --- | --- | --- | --- |
+| coupon.batch.latency | histogram | 接口返回 | P99 > 5s 5min |
+| coupon.batch.error_rate | gauge | 接口返回 | > 1% 5min |
+| coupon.batch.partial_success | counter | 有 failedUsers | — |
+
+### 日志
+- INFO:请求入参摘要(batch_id, size, templateId, operator)
+- WARN:单条失败(userId, reason, hitCode)
+- ERROR:全量失败或非预期异常(含 stack + traceId)
+
+### 处置手册(L3 必填)
+- <告警时第一步怎么办;二层升级给谁>
+
+## 10. 兼容性 / 灰度 / 回滚
+### 灰度
+- feature flag `coupon.batch.enabled`(Apollo)
+- 阶段:内部 5 个运营账号白名单 → 1% 灰度 → 10% → 100%
+- 每阶段观测 P99 + error_rate ≥ 2 小时
+
+### 回滚
+- flag=0 立即生效;正在进行的请求沿用新路径完成
+- DB 变更不需要回滚(新增列不影响旧代码)
+
+### 兼容性
+- 单发接口 `/api/v1/coupon/grant` 不动,前端/他方不感知
+- Legacy 客户端不调批量接口
+
+## 11. 备选方案
+### 方案 A(已选):API 同步批量 + 内部循环 grantOne
+- 优点:复用风控 / 复杂度低 / 上线快
+- 缺点:1000 人 P99 ≈ 3s,单实例 QPS 有限
+
+### 方案 B:异步任务 + 消息队列
+- 优点:高吞吐 / 耐堆积
+- 缺点:异步语义复杂 / 运营需轮询结果 / 当前无运营轮询 UI
+- 放弃理由:当前规模(峰值 QPS ≤ 20)同步可扛,换异步增加运营心智成本
+
+### 方案 C:客户端并发调单发
+- 优点:服务端无改动
+- 缺点:风控容易把批量操作当刷子;运营体验差;无批次语义
+- 放弃理由:风控坑大
+```
+
+---
+
+## 字段语义补充
+
+### §3 架构影响
+
+图的原则:
+
+1. **只画变化的边**,不要把全系统架构图贴上来
+2. 新增组件标 `*(新建)*`,改动组件标 `*(修改)*`,删除标 `*(删除)*`
+3. ASCII 和 mermaid 都 OK,优先 mermaid(更可维护)
+4. **关键依赖的方向必须正确**(新组件的 inbound / outbound 都画)
+
+**反例**:
+
+> ~~(把整个 microservices 架构图贴过来)~~
+
+**正例**:
+
+> ```mermaid
+> graph LR
+>   Client -->|*新建*| BatchGrantCtrl[BatchGrantController *(新建)*]
+>   BatchGrantCtrl --> GrantService[GrantService *(复用)*]
+>   GrantService --> RiskService
+>   GrantService --> DB[(coupon_grant *(ddl: +batch_id)*)]
+> ```
+
+---
+
+### §4 改动点汇总
+
+每行要写**类型**,不要只写"改":
+
+| 类型 | 含义 |
+| --- | --- |
+| 新建 | 新建类 / 方法 / 表 |
+| 修改 | 改已有类 / 方法 |
+| 复用 | 调用现有,无修改 |
+| 删除 | 删除(注明原因) |
+| 配置 | 配置 / feature flag |
+
+**为什么每行要标对应 F-ID**:验证 F-ID coverage、下游 plan 拆 task、code-review 能扫完整度。
+
+---
+
+### §5 契约
+
+必须有的内容:
+
+- HTTP method + path(含版本)
+- Request/Response 完整 JSON 例子
+- 必需 / 可选字段、类型 / 长度
+- 错误码表(code + http + 含义)
+- 幂等性(是否幂等 + 幂等 key)
+
+契约的**版本化与兼容性**见 `api-contract-design.md`。
+
+---
+
+### §6 数据层
+
+硬规则:
+
+1. **所有 DDL 幂等**:`IF NOT EXISTS` / `IF EXISTS`
+2. **不要 DROP COLUMN**(除非用户明确同意 + 有数据迁移方案)
+3. 新增索引要评估写放大(写热点表多一个索引成本)
+4. 大表 DDL 需说明 online vs offline(MySQL 5.6+ online DDL / 大表加列可能要 pt-osc)
+
+---
+
+### §7 关键流程
+
+至少画 **2 条**:
+
+1. **Happy path**:最常见的成功路径
+2. **至少 1 条 failure path**:下游超时 / 部分失败 / 幂等重试 之一
+
+**反例**:
+
+> 1. 接收请求 2. 处理 3. 返回
+> (这不是流程,是废话)
+
+**正例**:
+
+> - 接收请求 → 校验(参数 + 权限) → 读 RiskService 配置 → 循环 grantOne(每条独立事务)→ 聚合结果 → 返回
+> - 单条 grantOne = RiskService.check → 若 pass:INSERT grant_log;若 hit:记 failedUsers
+
+---
+
+### §8 错误处理 / 事务
+
+必须说清楚:
+
+- 事务边界(哪些步骤同一事务,哪些独立)
+- 事务传播(嵌套事务怎么处理)
+- 幂等策略(重复请求怎么办)
+- 失败分类(可恢复 / 不可恢复 / 需人工)
+- 数据一致性等级(强一致 / 最终一致 / 允许脏读)
+
+---
+
+### §11 Alternatives
+
+每个备选要有:
+
+1. **方案名 + 核心思路**
+2. **优缺点**
+3. **放弃 / 选中理由**(要有决策信号,不能 "就选了 A")
+
+**反例**:
+
+> 方案 B:MQ。不选,因为复杂。
+> (不足以支持决策)
+
+**正例**:
+
+> 方案 B:异步任务 + 消息队列
+> - 优点:高吞吐 / 耐堆积 / 能轻易做历史查询
+> - 缺点:
+>   - 异步语义让运营要轮询或等通知(当前无 UI)
+>   - 部分失败返回语义复杂(多 event 收集)
+>   - 开发量 + 2 人周(要加消费者 + 任务表 + 状态机)
+> - 放弃:当前峰值 QPS ≤ 20,同步可扛;异步的好处在未来 10x 规模才显现,届时可演进(方案 A 可无损平迁到 B,因为 API 外观不变)
+
+---
+
+## 本文与 SKILL.md 的关系
+
+SKILL.md 给了 11 段表 + 每段的 L1/L2/L3 级别差异。本文给每段完整模板、字段语义、正反例、L2 完整示例。agent 写 design.md 时应复制本文模板开始。