---
name: downstream-gen
description: A5 下游文档生成——基于 docs/01 和 docs/03 推导，一次性生成 docs/02 + docs/05 + docs/06 § 三 + docs/10，回填 REQ 卡片依赖接口，把模块清单追加到 docs/08 § 二。
user-invocable: false
allowed-tools: Read Write Edit Glob Grep Skill AskUserQuestion Bash(cat *) Bash(cp *)
---

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

# downstream-gen

## 执行步骤

### 步骤 0：打印当前位置流程图

用 `Bash` 执行 `cat` 命令向用户展示当前位置流程图（stdout 即 ASCII 框图）：

```bash
cat "${CLAUDE_PLUGIN_ROOT}/skills/downstream-gen/banners/flow.txt"
```

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

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

1. 构建**模块依赖 DAG**。
3. 对**每个模块内部**构建 REQ 间依赖，得到模块内 REQ 顺序。
4. 合成 `req_order[]`：按 `module_topo_order[]` 依次铺开每个模块内的 REQ 序列（**同模块 REQ 连续**）。
5. **环依赖打破**：
   - **模块级**：若模块 DAG 存在环（module_A ↔ module_B），按启发式（字母序 / 被依赖次数多者先）破环排出 `module_topo_order`，并在**参与环的模块里第一个 REQ** 的 `note` 字段填入原因（如 "A↔B 互依赖：先做 A 的骨架"）。
   - **REQ 级（同模块内）**：若模块内 REQ 互依赖，同样破环，`note` 填原因。
   - 非环 REQ `note` 留 `—`。
6. 为 `req_order[]` 每项生成字段：
   - `index`：行号（从 1 开始）
   - `req_id`：如 `REQ-SYS-001`
   - `module_id`：该 REQ 所属模块，如 `module_sys`
   - `rationale`（**选中理由**）：依赖驱动的简短描述，如 `所属模块无依赖，基础模块` / `依赖 REQ-SYS-001 已在前` / `所属模块依赖 module_sys 已在前`
   - `note`（**备注**）：默认 `—`；仅环依赖打破场景填原因
7. 读取并填充 `${CLAUDE_SKILL_DIR}/templates/docs-02-template.md`。
8. 写入 `docs/02-开发计划.md`。

完成后，用 `Edit` 在 `docs/08-模块任务管理.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。

完成后，用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选：
- `  - [ ] docs/05 API 契约已生成`

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

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

完成后，用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选：
- `  - [ ] REQ 卡片依赖接口已回填`

### C. docs/06 — 页面清单

对每个有前端页面的模块：读取并填充 `${CLAUDE_SKILL_DIR}/templates/docs-06-module-pagelist-template.md`，追加到 `docs/06-UI交互规范.md` § 三。

完成后，用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选：
- `  - [ ] docs/06 § 三 页面清单已填入`

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

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

完成后，用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选：
- `  - [ ] 下方模块列表已填入`

### E. docs/10 — 验收清单（项目级 SOP）

```bash
cp "${CLAUDE_SKILL_DIR}/templates/docs-10-header-template.md" docs/10-验收检查清单.md
```

完成后，用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选：
- `  - [ ] docs/10 验收清单已生成`

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

1. 一致性检查 + 自主修复循环（最多 3 轮，docs/01 是 REQ SSoT 不动）：

   **检查项**：
   - 每个 docs/01 REQ 都出现在 docs/05（作为接口，如适用）
   - `docs/02 § 二` 的 `module_id` 集合 = `docs/08 § 二` 的 `module_id` 集合

   **不一致 → 按差异类型自主修复**：
   - **REQ 缺 docs/05 endpoint** → 按步骤 B 规则为该 REQ 推测，并追加到 docs/05
   - **module_id 缺 docs/08 § 二** → 按步骤 D 规则渲染该模块 bullet（含 REQ 子项），按 `module_id` 字母序插入正确位置
   - **module_id 缺 docs/02 § 二** → 重算该模块的 `req_order` 段（步骤 A 子流程），按拓扑序插入 docs/02 § 二

   修复后重跑检查；通过 → 进入 2；3 轮仍失败 → 停下，打印最终残留差异 + 已尝试的 3 轮修复摘要让用户介入。

2. **最终占位符扫描 + 结构性残留检查**（覆盖 Plan 阶段全部产出）：

   a. **`TBD` → 自动补齐**：Grep 搜索 `TBD(A3 自动补)` 和 `TBD(A5 自动补)`。有命中则就地补填（A3 残留 → 查 docs/03 填 `依赖表`；A5 残留 → 查 docs/05 按 REQ-ID 填 `依赖接口`），再 Grep 确认 0 命中；仍残留报错停下。

   b. **结构性残留检查（不只看字面占位符，校验 SSoT 完整性）**：

      - **docs/05 每个端点都有请求/响应 schema**：逐个解析 docs/05 的每个 endpoint 段（以 `### REQ-` 开头的小节）。每段必须同时含非空的 `- **请求**:` 与 `- **响应**:` 行——值不得为空、`TBD`、`—` 或 `【人工填写：…】`。缺失/留空 → 按步骤 B 规则就地为该端点推测补全请求/响应 schema，再复核；3 轮仍补不全则计入残留清单（见下方 c），交由 QA 循环让用户介入。
      - **docs/02 DAG 覆盖每个 REQ**：收集 docs/01 全部 REQ-ID 集合，与 `docs/02 § 二、开发顺序清单` 表中出现的 `req_id` 集合比对。任一 docs/01 REQ 未出现在 docs/02 顺序清单 → 按步骤 A 子流程把该 REQ 插入其所属模块段的正确拓扑位置（保持同模块 REQ 连续），再复核；3 轮仍无法补齐则计入残留清单交由 QA 循环。

   c. **`【人工填写：...】` + 结构性残留 → QA 循环等用户补**：

      循环执行直到（搜索不到 `【人工填写：`）**且**（步骤 b 两项结构检查均通过）且用户选「继续」：
      - 0 残留 → 直接放行进入步骤 3
      - 有残留 → 打印残留清单（含字面占位符 `<文件:行号> — <内容摘要>`，以及结构性缺口 `docs/05 端点 <REQ-ID> 缺请求/响应 schema` / `docs/02 顺序清单缺 REQ <REQ-ID>`），用 `AskUserQuestion` 弹「继续」/「有疑问想先沟通」二选一；用户回答后重扫 + 重跑结构检查再决定放行 / 继续循环

      **每次弹 QA 前都重扫一次**（含两项结构检查）——保证用户看到的 N 是最新的，避免「用户以为填完但实际还有残留」直接放行。

3. **docs/05 + docs/02 人工评审闸（强制，未确认不得勾选 A5）**：

   向用户摘要展示两份 SSoT 的关键内容，请其确认无误：
   - **docs/05 API 契约**：列出全部端点（`METHOD PATH — REQ-ID`），并标注任何「由 A5 自动推断」的端点/字段供重点核对。
   - **docs/02 构建顺序**：展示 `req_order[]` 顺序，**特别标出所有 `note ≠ —` 的环依赖打破项**（启发式选定的顺序 + 原因），供用户判断该顺序是否可接受。

   用 `AskUserQuestion` 同时问两项确认（多问题表单），每项二选一：
   - 「docs/05 端点/字段确认无误」：`确认` / `需要修改`
   - 「docs/02 构建顺序可接受（含 cycle-breaking 选定的顺序）」：`确认` / `需要修改`

   裁决：
   - 两项均 `确认` → 进入步骤 4 勾选 A5。
   - 任一为 `需要修改` → 用 `AskUserQuestion` 收集具体修改点，就地修订对应文档（docs/05 端点/字段或 docs/02 顺序/备注），改完重新展示摘要并重跑本评审闸，直到两项均 `确认`。**未两项确认前禁止勾选 A5、禁止打印终止横幅。**

4. 完成后，用 `Edit` 在 `docs/08-模块任务管理.md` 勾选 A5 父项：
   - `- [ ] A5 下游文档生成 — downstream-gen`

5. 打印 Plan 阶段终止横幅并**停下**（不自动进入 B 阶段）：

   ```
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    [downstream-gen] ✅ Plan 阶段（A0~A5）全部完成

    所有规划文档已就绪，docs/08 § 一 全部勾选。

    ⚠️ 进入 B 阶段前必须完成：
      1. 审核 docs/01~10 + CLAUDE.md + sql/migrations/V1 + 各 scripts/*

      2. 把全部 Plan 产物 commit 到本地默认分支（main / master）：
           git add -A && git commit -m "chore: plan phase done"

      3. 运行 /erp-workflow:coding-start 进入 B 阶段
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   ```

## 参考

- `${CLAUDE_SKILL_DIR}/templates/docs-02-template.md`
- `${CLAUDE_SKILL_DIR}/templates/docs-05-header-template.md`
- `${CLAUDE_SKILL_DIR}/templates/docs-05-endpoint-template.md`
- `${CLAUDE_SKILL_DIR}/templates/docs-06-module-pagelist-template.md`（追加到 docs/06 § 三）
- `${CLAUDE_SKILL_DIR}/templates/docs-08-module-row-template.md`（模块 bullet 行模板）
- `${CLAUDE_SKILL_DIR}/templates/docs-10-header-template.md`