---
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/plan/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 轮修复摘要让用户介入。`[ERP-HALT]`

2. **最终占位符扫描**（覆盖 Plan 阶段全部产出）：

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

   b. **`【人工填写：...】` → QA 循环等用户补**：

      循环执行直到搜索不到 `【人工填写：` 且用户选「继续」：
      - 0 命中 → 直接放行进入步骤 3
      - 有命中 → 打印残留清单（`<文件:行号> — <内容摘要>`），用 `AskUserQuestion` 弹「继续」/「有疑问想先沟通」二选一；用户回答后重扫验证再决定放行 / 继续循环

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

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

4. 打印 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`