朱子纯 / erp-workflow-plugin

SKILL.md 9.42 KB

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 框图）：

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

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

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

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

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 轮修复摘要让用户介入。

  1. 最终占位符扫描 + 结构性残留检查（覆盖 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 是最新的，避免「用户以为填完但实际还有残留」直接放行。
  1. 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、禁止打印终止横幅。

  1. 完成后，用 Edit 在 docs/08-模块任务管理.md 勾选 A5 父项：

    • - [ ] A5 下游文档生成 — downstream-gen

  2. 打印 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