---
name: downstream-gen
description: A5 下游文档生成——基于 docs/01 和 docs/03 推导，一次性生成 docs/02 + docs/05，回填 REQ 卡片依赖接口，把模块清单追加到 docs/08 § 二，并由 prototype/ + docs/01 + docs/05 推导 FE 清单写入 docs/08 § 三。这是 Plan 阶段最后一个 A 步骤。
user-invocable: false
allowed-tools: Read Write Edit Glob Grep AskUserQuestion
---

**所有输出必须使用中文。**

# downstream-gen

每步骤完成后用 `Edit` 在 `docs/08-模块任务管理.md` § 一 勾选对应子项。

## 执行步骤

### A. docs/02 — 开发计划（含 REQ 级开发顺序清单）

**清单颗粒度**：一行一个 REQ，同一模块的 REQ 必须**连续排列**。

1. **先读 `docs/06-实现策略.md`**：若其载明模块 / REQ 的实现顺序或优先级，作为构建顺序的**约束优先采纳**（与依赖拓扑冲突时以 docs/06 为准，并在该 REQ 的 `note` 注明取舍依据）。随后拓扑排模块得 `module_topo_order[]`，对每个模块内部拓扑排 REQ；按模块顺序依次铺开生成 `req_order[]`（同模块 REQ 连续）。出现环（模块级或模块内 REQ 级）用启发式（字母序 / 被依赖次数多者先）破环，并把原因填入参与环的首个 REQ 的 `note`；非环 REQ `note` 留 `—`。
2. 为每项生成 `index`（从 1）/ `req_id` / `module_id` / `rationale`（依赖驱动短描述）/ `note`。
3. 读取并填充 `${CLAUDE_SKILL_DIR}/templates/docs-02-template.md`，写入 `docs/02-开发计划.md`。

勾选：`  - [ ] docs/02 开发计划已生成`

### B. docs/05 — API 接口契约

1. 读取 `${CLAUDE_SKILL_DIR}/templates/docs-05-header-template.md`，写入 `docs/05-API接口契约.md` 头部。
2. 对所有模块的每个 REQ：读取并推断 `${CLAUDE_SKILL_DIR}/templates/docs-05-endpoint-template.md`，追加到 docs/05。

> 推断端点时对齐 `docs/06-实现策略.md` 中影响 API 设计的关键决策（分页 / 鉴权 / 统一响应包络 / 错误码风格等），保持契约与实现策略一致。

勾选：`  - [ ] docs/05 API 契约已生成`

### B2. 回填模块头 + REQ 卡片的 TBD(A5) 字段

1. 在 `docs/01-需求清单/*/*.md`（模块头 `_module.md` + 全部 REQ 卡片，卡片文件名 == req_id）中搜索并回填 `TBD(A5 自动补)` 
2. 打印回填统计：`A5 回填 <M> 处模块"依赖模块" + <N> 处 REQ"依赖接口"`。

勾选：`  - [ ] REQ 卡片依赖接口已回填`

### C. FE 清单 — 推导前端功能写入 docs/08 § 三

前端布局 / 页面 / 交互的权威是项目根 `prototype/`（完整前端 demo，含全部页面与布局）。本步**只**把「有哪些前端功能（FE-NN）」推导出来，供 Coding 阶段 `coding.mjs` 的 Router 聚合 `frontend-phase`——不另写 UI 规范文档。

1. 用 `Glob` 检查 `prototype/**/*.html`：
   - **0 个** → Plan 期可问：用 `AskUserQuestion` 告知「未在 prototype/ 找到 .html 原型，前端以 prototype/ 为权威」，给「我已补齐原型，请重新检查」/「本项目无前端」。选「无前端」→ docs/08 § 三「功能:」留空（Router 不产生 frontend-phase），跳过 2/3；选「已补齐」→ 重新 `Glob`。
   - **≥1 个** → 继续。
2. 综合 `prototype/*.html` + docs/01 REQ 卡片 + docs/05 端点，按业务功能粒度推导 FE 清单（一个 `FE-NN` 可关联多个 prototype 区域 / 多个 REQ）。
3. 用 `Edit` 把 FE-NN 行写入 `docs/08-模块任务管理.md § 三` 的「功能:」项下，一行一个：`  - [ ] FE-NN <功能名>`（coding.mjs Router 据此聚合前端阶段）。

勾选：`  - [ ] FE 清单已推导填入 docs/08 § 三`

### D. docs/08 — 追加模块清单

读 `${CLAUDE_SKILL_DIR}/templates/docs-08-module-row-template.md`，按 `module_id` 字母序为每个模块渲染 bullet（模块元数据 + REQ 子项清单，REQ 序保持步骤 A 模块内顺序），追加到 docs/08。

勾选：`  - [ ] 下方模块列表已填入`

### E. 验证 + 勾选 docs/08 进度 + 结束 Plan

1. **合并扫描三类问题**（最多 3 轮自主修复，docs/01 是 REQ SSoT 不动）——一次性扫一致性 + `TBD(A3/A5 自动补)` + 结构性残留：

   - **一致性**：docs/01 REQ 全部出现在 docs/05；`docs/02 § 二` `module_id` 集合 = `docs/08 § 二` `module_id` 集合。
   - **TBD 残留**：`TBD(A3 自动补)` → 查 docs/03 填依赖表；`TBD(A5 自动补)` → 查 docs/05 按 req_id 填依赖接口。
   - **结构性**：docs/05 每个 `### ` 三级标题端点段（标题形如 `### <req_id> <标题>`）含非空 `- **请求**:` / `- **响应**:`（非 `TBD`/`—`/`【人工填写：…】`）；docs/01 全部 req_id 都出现在 `docs/02 § 二` 顺序清单。

   命中即按对应步骤规则就地补填（缺端点 → 按 B 推测；缺 module 行 → 按 D 渲染；缺 REQ 顺序行 → 按 A 子流程拓扑插入）。3 轮后仍残留 `【人工填写：】` 或结构缺口 → 打印清单 + 用 `AskUserQuestion` 弹「继续」/「有疑问想先沟通」二选一；每次弹问前重扫一次，避免脏读放行。

2. **docs/05 + docs/02 人工评审闸**（未确认不得勾选 A5）：摘要展示 docs/05 全部端点（`METHOD PATH — <req_id>`，标注「由 A5 自动推断」的项）+ docs/02 `req_order[]`（特别标 `note ≠ —` 的环依赖打破项）。`AskUserQuestion` 多问题表单同时问两项：「docs/05 端点/字段无误」+「docs/02 构建顺序可接受」，各二选一 `确认` / `需要修改`。任一需修改 → 收集修改点就地修订并重跑本闸，直到两项均 `确认`；否则禁止勾选 A5、禁止打印横幅。

3. 勾选 A5 父项：`- [ ] A5 下游文档生成 — downstream-gen`

4. 打印 A5 完成横幅并**停下**：

   ```
   [downstream-gen] ✅ A5 下游文档生成完成（Plan A0~A5 全部完成）
   产出：docs/02 / docs/05 / docs/08 § 二 模块清单 / docs/08 § 三 FE 清单；docs/08 § 一 A0~A5 已全勾。
   ⏭️ 下一步：运行 /erp-workflow:plan-start 进入终结闸
   ```

## 参考

- `${CLAUDE_SKILL_DIR}/templates/docs-02-template.md`
- `docs/06-实现策略.md`（A2 人工填写；docs/02 构建顺序 + docs/05 API 决策的参考）
- `${CLAUDE_SKILL_DIR}/templates/docs-05-header-template.md`
- `${CLAUDE_SKILL_DIR}/templates/docs-05-endpoint-template.md`
- `prototype/**/*.html`（前端页面/布局/交互权威；C 段据此推导 FE 清单）
- `${CLAUDE_SKILL_DIR}/templates/docs-08-module-row-template.md`（模块 bullet 行模板）