sdd-flow-kit 1.3.15 → 1.3.18

package/scripts/lib/test-assertion-analysis.mjs

@@ -0,0 +1,134 @@
+/**
+ * 测试断言分析（与 src/core/testAssertionAnalysis.ts 保持语义一致，供 scripts 独立运行）。
+ */
+
+const TEST_TITLE_RE = /(?:^|\n)\s*(?:test|it)(?:\.(?:only|skip))?\s*\(\s*(?:async\s*)?[`'"]([^`'"]*)[`'"]/g;
+const EXPECT_RE = /\bexpect\s*\(/;
+const E2E_DIR_RE = /(^|\/)(e2e|playwright)(\/|$)/i;
+const REGISTRY_STUB_FILE_RE = /prd-atoms-coverage|prd-atoms-registry|semantic-registry/i;
+const PLACEHOLDER_ONLY_RE = /getByPlaceholder|getByLabel|getByTestId/i;
+const DATA_ASSERTION_RE =
+  /getByRole\s*\(\s*['"]cell|getByRole\s*\(\s*['"]row|toContainText|waitForResponse|\.n-data-table|data-table-tbody|data-table-body/i;
+const HOOK_TITLE_RE = /^(?:beforeEach|afterEach|beforeAll|afterAll)$/i;
+
+export function stripComments(content) {
+  let out = "";
+  let i = 0;
+  while (i < content.length) {
+    if (content[i] === "/" && content[i + 1] === "/") {
+      while (i < content.length && content[i] !== "\n") i += 1;
+      continue;
+    }
+    if (content[i] === "/" && content[i + 1] === "*") {
+      i += 2;
+      while (i < content.length && !(content[i] === "*" && content[i + 1] === "/")) i += 1;
+      i += 2;
+      continue;
+    }
+    out += content[i];
+    i += 1;
+  }
+  return out;
+}
+
+export function parseTestBlocks(content) {
+  const stripped = stripComments(content);
+  const blocks = [];
+  const re = new RegExp(TEST_TITLE_RE.source, "g");
+  let m;
+  const indices = [];
+  let idx = 0;
+  while ((m = re.exec(stripped)) !== null) {
+    indices.push({ title: m[1] ?? "", start: m.index, index: idx });
+    idx += 1;
+  }
+  for (let i = 0; i < indices.length; i += 1) {
+    const cur = indices[i];
+    const nextStart = indices[i + 1]?.start ?? stripped.length;
+    const slice = stripped.slice(cur.start, Math.min(cur.start + 4000, nextStart));
+    blocks.push({ title: cur.title, body: slice, index: cur.index });
+  }
+  return blocks;
+}
+
+export function isRegistryStubFile(relPath, content) {
+  const norm = relPath.replace(/\\/g, "/");
+  if (REGISTRY_STUB_FILE_RE.test(norm)) return true;
+  if (!E2E_DIR_RE.test(norm)) return false;
+  const blocks = parseTestBlocks(content);
+  if (blocks.length === 0) return false;
+  const allShallow = blocks.every((b) => {
+    const hasExpect = EXPECT_RE.test(b.body);
+    const onlyCount =
+      /expect\s*\([^)]*\)\s*\.toBeGreaterThan\s*\(\s*0\s*\)/.test(b.body) &&
+      !DATA_ASSERTION_RE.test(b.body) &&
+      !/\bpage\.goto\b/.test(b.body);
+    return !hasExpect || onlyCount;
+  });
+  return allShallow && blocks.length >= 3;
+}
+
+export function testBlockIsPlaceholderOnly(block) {
+  if (HOOK_TITLE_RE.test(block.title.trim())) return false;
+  if (!EXPECT_RE.test(block.body)) return false;
+  const hasPlaceholder = PLACEHOLDER_ONLY_RE.test(block.body);
+  const hasData = DATA_ASSERTION_RE.test(block.body);
+  const hasInteraction = /\b(?:click|dblclick|fill|press|selectOption)\b/.test(block.body);
+  return hasPlaceholder && !hasData && !hasInteraction;
+}
+
+export function analyzeE2eSpecDepth(relPath, content) {
+  const issues = [];
+  if (isRegistryStubFile(relPath, content)) {
+    return {
+      ok: false,
+      issues: ["伪覆盖登记文件，不能作为 change 级 E2E 验收"],
+      stats: { testCount: 0, testsWithExpect: 0, hasGoto: false, hasDataAssertion: false, hasInteraction: false },
+    };
+  }
+
+  const stripped = stripComments(content);
+  const blocks = parseTestBlocks(content);
+  const hookBlocks = blocks.filter((b) => HOOK_TITLE_RE.test(b.title.trim()));
+  const testBlocks = blocks.filter((b) => !HOOK_TITLE_RE.test(b.title.trim()));
+  const testsWithExpect = testBlocks.filter((b) => EXPECT_RE.test(b.body)).length;
+  const hasGoto = /\bpage\.goto\b/.test(stripped);
+  const hasDataInTests = testBlocks.some((b) => DATA_ASSERTION_RE.test(b.body));
+  const hasInteractionInTests = testBlocks.some((b) =>
+    /\b(?:click|dblclick|fill|press|selectOption)\b/.test(b.body),
+  );
+  const placeholderOnlyTests = testBlocks.filter((b) => testBlockIsPlaceholderOnly(b));
+
+  if (testBlocks.length === 0) issues.push("未解析到 test/it 用例（不含 hook）");
+  if (testsWithExpect === 0) issues.push("无含 expect( 的 test/it 块");
+  if (!hasGoto && !hookBlocks.some((b) => /\bpage\.goto\b/.test(b.body))) {
+    issues.push("缺少 page.goto（页面可达性未验证）");
+  }
+  if (placeholderOnlyTests.length > 0) {
+    issues.push(
+      `以下用例仅断言 placeholder/label: ${placeholderOnlyTests.map((t) => t.title).join(", ")}`,
+    );
+  }
+  if (!hasDataInTests && !hasInteractionInTests) {
+    issues.push("所有 test 块均缺少数据展示断言或交互操作");
+  }
+
+  const ok =
+    testBlocks.length > 0 &&
+    testsWithExpect > 0 &&
+    (hasGoto || hookBlocks.some((b) => /\bpage\.goto\b/.test(b.body))) &&
+    placeholderOnlyTests.length === 0 &&
+    (hasDataInTests || hasInteractionInTests);
+
+  return {
+    ok,
+    issues,
+    stats: {
+      testCount: testBlocks.length,
+      testsWithExpect,
+      hasGoto,
+      hasDataAssertion: hasDataInTests,
+      hasInteraction: hasInteractionInTests,
+    },
+  };
+}

package/scripts/resolve-playwright-e2e-scope.mjs

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+/**
+ * 根据 OpenSpec change / 显式模块名解析 Playwright 运行范围。
+ *
+ * scope 三级（见 e2e/e2e-scope.config.json defaultScope）：
+ * - change（默认）：优先 change 文档中的 e2e/*.spec.ts；未写明则按 changeScopeFallback 回退（默认 module）
+ * - module：解析到的 e2e/<module>/ 整个目录
+ * - full：输出 FULL，由调用方跑全量 e2e/**
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const CONFIG_PATH = path.join(ROOT, "e2e/e2e-scope.config.json");
+
+const VALID_SCOPES = new Set(["change", "module", "full"]);
+
+function loadConfig() {
+  return JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"));
+}
+
+function resolveDefaultScope(config) {
+  const fromEnv = process.env.OPSX_PLAYWRIGHT_SCOPE || process.env.POQUAN_PLAYWRIGHT_SCOPE;
+  if (fromEnv) return fromEnv;
+  return config.defaultScope || "change";
+}
+
+function parseArgs(argv) {
+  const config = loadConfig();
+  const out = {
+    change: "",
+    scope: resolveDefaultScope(config),
+    modules: "",
+  };
+  for (let i = 2; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--change" && argv[i + 1]) {
+      out.change = argv[++i];
+    } else if (a === "--scope" && argv[i + 1]) {
+      out.scope = argv[++i];
+    } else if (a === "--modules" && argv[i + 1]) {
+      out.modules = argv[++i];
+    } else if (!a.startsWith("-") && !out.change) {
+      out.change = a;
+    }
+  }
+  const envModules = process.env.OPSX_E2E_MODULES || process.env.POQUAN_E2E_MODULES;
+  if (envModules) {
+    out.modules = envModules;
+  }
+  if (!VALID_SCOPES.has(out.scope)) {
+    console.error(
+      `[resolve-playwright-e2e-scope] 无效 scope="${out.scope}"；允许: change | module | full`,
+    );
+    process.exit(2);
+  }
+  return out;
+}
+
+function findChangeDir(changeName) {
+  const active = path.join(ROOT, "openspec/changes", changeName);
+  if (fs.existsSync(active)) return active;
+  const archiveRoot = path.join(ROOT, "openspec/changes/archive");
+  if (!fs.existsSync(archiveRoot)) return null;
+  const hit = fs
+    .readdirSync(archiveRoot)
+    .filter((d) => d.endsWith(changeName) || d.includes(changeName))
+    .sort()
+    .pop();
+  return hit ? path.join(archiveRoot, hit) : null;
+}
+
+/** 从 change 文档中提取显式声明的 e2e spec 路径（tasks / proposal / design） */
+function collectSpecPathsFromChangeDir(changeDir) {
+  const specs = new Set();
+  const specRe = /\be2e\/[\w/.-]+\.spec\.(?:ts|js)\b/g;
+  const files = ["tasks.md", "proposal.md", "design.md"];
+  for (const f of files) {
+    const fp = path.join(changeDir, f);
+    if (!fs.existsSync(fp)) continue;
+    const content = fs.readFileSync(fp, "utf8");
+    let m;
+    while ((m = specRe.exec(content)) !== null) {
+      const rel = m[0];
+      const abs = path.join(ROOT, rel);
+      if (fs.existsSync(abs)) specs.add(rel);
+    }
+  }
+  return [...specs].sort();
+}
+
+function resolveChangeSpecPaths(changeName, config) {
+  const paths = new Set();
+  const changeDir = findChangeDir(changeName);
+  if (changeDir) {
+    collectSpecPathsFromChangeDir(changeDir).forEach((p) => paths.add(p));
+  }
+  const overrides = config.changeNameToSpecs?.[changeName];
+  if (overrides) {
+    for (const raw of overrides) {
+      const rel = raw.startsWith("e2e/") ? raw : `e2e/${raw}`;
+      const abs = path.join(ROOT, rel);
+      if (fs.existsSync(abs)) paths.add(rel);
+    }
+  }
+  return [...paths].sort();
+}
+
+function collectCapabilities(changeDir) {
+  const caps = [];
+  const specsDir = path.join(changeDir, "specs");
+  if (!fs.existsSync(specsDir)) return caps;
+  for (const ent of fs.readdirSync(specsDir, { withFileTypes: true })) {
+    if (ent.isDirectory()) caps.push(ent.name);
+  }
+  return caps;
+}
+
+function scanFeatureDirs(text) {
+  const found = new Set();
+  const re = /src\/features\/([a-z0-9-]+)/gi;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    found.add(m[1]);
+  }
+  return [...found];
+}
+
+function matchChangeNameKeywords(changeName, config) {
+  const mods = new Set();
+  for (const { pattern, modules } of config.changeNameKeywords || []) {
+    if (new RegExp(pattern, "i").test(changeName)) {
+      modules.forEach((mod) => mods.add(mod));
+    }
+  }
+  return [...mods];
+}
+
+function modulesToPaths(moduleIds, config) {
+  const paths = new Set();
+  for (const id of moduleIds) {
+    const dirs = config.modules[id];
+    if (!dirs) continue;
+    dirs.forEach((p) => {
+      const abs = path.join(ROOT, p);
+      if (fs.existsSync(abs)) paths.add(p);
+    });
+  }
+  return [...paths].sort();
+}
+
+function resolveModules({ change, modules }, config) {
+  if (modules) {
+    return modules
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+  }
+  const moduleSet = new Set();
+  if (change) {
+    const changeDir = findChangeDir(change);
+    if (changeDir) {
+      for (const cap of collectCapabilities(changeDir)) {
+        (config.capabilityToModules[cap] || []).forEach((m) => moduleSet.add(m));
+      }
+      const textFiles = ["proposal.md", "design.md", "tasks.md"];
+      let blob = "";
+      for (const f of textFiles) {
+        const fp = path.join(changeDir, f);
+        if (fs.existsSync(fp)) blob += `${fs.readFileSync(fp, "utf8")}\n`;
+      }
+      for (const feat of scanFeatureDirs(blob)) {
+        (config.featureDirToModules[feat] || []).forEach((m) => moduleSet.add(m));
+      }
+    }
+    matchChangeNameKeywords(change, config).forEach((m) => moduleSet.add(m));
+  }
+  return [...moduleSet];
+}
+
+/** 按 change / OPSX_E2E_MODULES / POQUAN_E2E_MODULES 解析模块 id 与 e2e 目录路径 */
+function resolveModuleScope(args, config) {
+  const moduleIds = resolveModules(args, config);
+  const paths = modulesToPaths(moduleIds, config);
+  return { moduleIds, paths };
+}
+
+function emitModulePaths(args, config, logPrefix) {
+  const { moduleIds, paths } = resolveModuleScope(args, config);
+  if (paths.length === 0) {
+    console.error(
+      "[resolve-playwright-e2e-scope] 未能解析模块；请设置 OPSX_E2E_MODULES=auth,review / POQUAN_E2E_MODULES=auth,review 或 OPSX_PLAYWRIGHT_SCOPE=full",
+    );
+    process.exit(2);
+  }
+  process.stderr.write(
+    `${logPrefix} scope=module change=${args.change || "-"} modules=${moduleIds.join(",")} paths=${paths.join(" ")}\n`,
+  );
+  paths.forEach((p) => process.stdout.write(`${p}\n`));
+}
+
+function main() {
+  const config = loadConfig();
+  const args = parseArgs(process.argv);
+
+  if (args.scope === "full") {
+    process.stdout.write("FULL\n");
+    return;
+  }
+
+  if (args.scope === "change") {
+    if (!args.change) {
+      console.error(
+        "[resolve-playwright-e2e-scope] scope=change 需要 change 名；示例: node scripts/resolve-playwright-e2e-scope.mjs <change-name>",
+      );
+      process.exit(2);
+    }
+    const specPaths = resolveChangeSpecPaths(args.change, config);
+    if (specPaths.length > 0) {
+      process.stderr.write(
+        `[resolve-playwright-e2e-scope] scope=change（文档 spec） change=${args.change} specs=${specPaths.join(" ")}\n`,
+      );
+      specPaths.forEach((p) => process.stdout.write(`${p}\n`));
+      return;
+    }
+
+    const fallback = config.changeScopeFallback ?? "module";
+    if (fallback === "module") {
+      process.stderr.write(
+        `[resolve-playwright-e2e-scope] scope=change 未在 tasks/proposal/design 中找到 spec，` +
+          `已按 changeScopeFallback=module 回退模块目录（change=${args.change}）\n`,
+      );
+      emitModulePaths(args, config, "[resolve-playwright-e2e-scope]");
+      return;
+    }
+
+    console.error(
+      `[resolve-playwright-e2e-scope] scope=change 未找到 e2e/*.spec.ts，且 changeScopeFallback=${fallback}；` +
+        `可配置 changeNameToSpecs、将 changeScopeFallback 设为 module，或 OPSX_PLAYWRIGHT_SCOPE=module|full`,
+    );
+    process.exit(2);
+  }
+
+  emitModulePaths(args, config, "[resolve-playwright-e2e-scope]");
+}
+
+main();

package/src/templates/artifacts/01-adi-doc-skill-/346/214/207/345/274/225.template.md

@@ -7,9 +7,12 @@
 ```bash
 cd {{DOC_SKILL_REL}}
 export DOC_PRODUCT_PREFIX="{{PRODUCT_PREFIX}}"
+export SDD_SYNC_SOURCE_DIR="{{SYNC_SOURCE_DIR_REL}}"
 python3 confluence-doc.py {{VERSION_EXAMPLE}}
 ```
 
+脚本成功后会自动将 `docs/<版本目录>/*.md` 与 `image/` 同步到本 run 的 `source/PRD.md` 与 `source/image/`（也可手动执行 `npx sdd-flow-kit sync-source-prd --run-id <runId>`）。
+
 版本号可传：`2.3.2`、`V2.3.2`、`ADI_V2.3.2`、`ADI-V2.3.2`（脚本会归一化）。
 
 2. 脚本会依次用关键词打开 **Confluence 专用搜索页** `dosearchsite.action?queryString=<关键词>`（非首页顶栏搜索），并依次尝试：`ADI_V*` → `ADI-V*` → `ADI_*` → `ADI-*` → `ADI_v*` → `ADI-v*` → `ADI V*` → `ADI_V*结算` → `V*` 等。
@@ -24,8 +27,9 @@ python3 confluence-doc.py {{VERSION_EXAMPLE}}
 
 5. **禁止**在 Confluence 脚本未跑完或未确认失败前，用本地 Word/原型替代 `source/PRD.md`。
 
-6. 成功后把生成的 `docs/*.md` **主文档**复制/回填到本 run 目录：
-   - `source/PRD.md`
+6. 同步结果（自动，无需手抄）：
+   - `source/PRD.md`（含 `> 原型图片目录: image/` 元数据行）
+   - `source/image/`（正文图片，与 docs 版本目录一致）
 
 ## 直链兜底（可选，非默认）
 

package/src/templates/artifacts/02-/351/234/200/346/261/202/345/210/206/346/236/220/346/217/220/347/244/272/350/257/215.template.md

@@ -23,6 +23,11 @@
 - `01-需求分析报告.md`
 - `02-改动点清单.md`
 - `03-待确认问题清单.md`
+- 阶段 B 交付模式另产出：`05-验收清单.md`、**填写完成的** `04-技术文档草稿.md`（须符合 `04-技术文档生成指引.md`，禁止摘要版）
+
+## 04 技术文档（阶段 B 必读）
+- 同 run 目录：`04-技术文档生成指引.md`
+- 脚手架已生成完整模板 `04-技术文档草稿.md` → **在原文件上填内容，勿删章节**
 
 ## 输出话术（建议固定）
 - 提问模式：`SDD 模式：提问模式；矛盾点池状态：未闭合；仅更新 03，等待人工确认。`

package/src/templates/artifacts/04-/346/212/200/346/234/257/346/226/207/346/241/243.template.md

@@ -92,6 +92,20 @@
 - 错误态提示口径（toast/inline）：
 - 权限不足提示：
 
+### 2.4 演示代码参照（UI 类必填）
+
+> 演示可为 **Vue / React / 其他**；生产实现须达到 **相同交互与功能**。Propose 时整段迁入 `design.md` 的 `## 演示代码参照`。
+
+- 演示代码根路径：
+- 技术栈：vue | react | 其他
+- 生产 UI 库：
+
+| 演示模块 | 演示文件/组件 | 计划生产组件路径 | 关键交互信号（验收时须在代码中出现） |
+|---------|--------------|-----------------|-------------------------------------|
+| | | | |
+
+纯后端/无 UI 演示：在 design 写 `DEMO_REFERENCE_EXEMPT: <原因>`
+
 ## 3. 前端状态与数据模型设计
 
 ### 3.1 领域模型（TypeScript）

package/src/templates/artifacts/05-/351/252/214/346/224/266/346/270/205/345/215/225.template.md

@@ -11,10 +11,10 @@
 ## 填写规则
 
 1. **ID**：`AC-01`、`AC-02`… 全局唯一。
-2. **验收标准**：必须可观测（DOM 顺序、完整 toast/tooltip 文案、E2E 路径、截图对比等）。
+2. **验收标准**：必须可观测（DOM 顺序、完整 toast/tooltip 文案、E2E 路径、截图对比等）；**详情/弹窗类须写明演示模块名**（如「对齐演示 ProjectDetail §红票及其他」）。
 3. **测试类型**：`unit` | `component` | `e2e` | `visual` | `manual`（可组合，如 `unit+e2e`）。
 4. **优先级**：`P0`（交付阻断）/ `P1` / `P2`。
-5. **映射**：propose 后在 `openspec/changes/<change>/tasks.md` 或 `spec.md` 中引用 `[AC-XX]`。
+5. **映射**：propose 后在 `openspec/changes/<change>/tasks.md` 或 `spec.md` 中引用 `[AC-XX]`；**tasks 须有「演示模块迁移」段，与 design 映射表一行一任务**。
 6. **Intentional 偏差**：与 PRD 有意不一致时，必须同步记入 `03-待确认问题清单.md` 并在下文登记。
 
 ## 验收项

package/src/templates/artifacts/06-openspec-/346/217/220/346/241/210/350/215/211/347/250/277.template.md

@@ -8,7 +8,7 @@
 - [ ] `03-待确认问题清单.md` 已标注 **矛盾点池状态：已闭合**
 - [ ] `05-验收清单.md` 已标注 **定义状态：已定义**，且 P0 项齐全
 - [ ] `01-需求分析报告.md`、`02-改动点清单.md`、`04-技术文档草稿.md` 已生成（04 须引用 AC-ID）
-- [ ] `gate ac-ready` 通过（P0 已映射到 spec/tasks）
+- [ ] `gate ac-ready` 通过（P0 已映射到 spec/tasks，且 **design 含演示模块映射表**）
 - [ ] 用户已确认可进入提案阶段（阶段 B 闭环）
 - [ ] `autoChainOpsx` 为 true（默认）→ 与用户确认后**同一回合**自动 propose，无需再等「继续」
 
@@ -18,7 +18,7 @@
 - **验收 SSOT**：`05-验收清单.md`（**必须**）
 - 改动清单：`02-改动点清单.md`
 - 技术方案：`04-技术文档草稿.md`（引用 AC-ID）
-- UI/交互参考：（填写用户提供的路径，例如原型页面或设计稿目录）
+- UI/交互参考：（**必填**）演示代码根路径 + 技术栈（vue/react）；propose 时写入 `design.md` → `## 演示代码参照` 映射表（见 `design-demo-reference.template.md`）
 
 ## 执行命令（在 AI 工具中）
 

package/src/templates/artifacts/07-opsx-auto-chain.template.md

@@ -38,8 +38,8 @@
 ## UI 路径解析（按优先级）
 
 1. 用户本条消息给出的路径
-2. `source/PRD.md` 中的「原型图片目录」行（如 `docs/adi-v232/`）
-3. `docs/<product>-v<version无点>/` 或 `docs/<product>-<version>/` 目录（只读扫描）
+2. `source/PRD.md` 中的「原型图片目录」行（如 `source/image/` 或 `docs/adi-v232/image/`）
+3. `source/image/` 或 `docs/<product>-v<version无点>/image/`（只读扫描）
 
 缺失 UI 时：**仍继续** propose，在 `proposal.md` / `design.md` 注明「UI 待补」。
 

package/src/templates/artifacts/08-PRD/344/270/200/350/207/264/346/200/247/345/244/215/346/237/245/346/212/245/345/221/212.template.md

@@ -66,6 +66,8 @@
 - 「先沿用旧版，后续再改」— 兜底措辞
 - 「组件里应该有处理」— 无路径/行号/断言
 - 「基本满足」— 结论不在三选一内
+- `src/views/foo/index.vue:1` — **仅文件首行，无具体组件/交互证据**
+- `tests/.../prd-atoms-coverage.test.ts` — **注释登记 PRD-ID，非真实实现**
 
 ## 逐条对比（PRD 原子 × 代码）
 

package/src/templates/artifacts/design-demo-reference.template.md

@@ -0,0 +1,24 @@
+## 演示代码参照
+
+> **UI 类 change 必填**。演示可为 Vue/React；生产实现须达到相同交互与功能，允许换 UI 库。
+> 纯后端/无 UI 时在 change 文档首行写：`DEMO_REFERENCE_EXEMPT: <原因>`
+
+- **演示代码根路径**：`（填写绝对或相对路径，如 /path/to/demo 或 docs/demo-v234）`
+- **技术栈**：`vue` | `react` | `其他`
+- **生产 UI 库**：`（如 Naive UI / Ant Design）`
+- **迁移说明**：（可选）演示 Element Plus → 生产 Naive UI，布局与交互 SSOT 仍以演示为准
+
+### 演示模块 → 生产组件映射（门禁 SSOT）
+
+| 演示模块 | 演示文件/组件 | 生产组件路径 | 关键交互信号（须在生产代码出现） |
+|---------|--------------|-------------|--------------------------------|
+| （示例）列表页 | FinancialOverview.vue | src/views/finance/index.vue | 请输入项目ID或名称、拉取欢聚最新数据 |
+| （示例）详情-BD预估 | ProjectDetail.vue | src/views/finance/components/BdEstimateSection.vue | 编辑预估、BD预计开票日期、距BD预计 |
+| （示例）详情-红票 | ProjectDetail.vue | src/views/finance/components/RedInvoiceSection.vue | 红票及其他、添加记录、红票 |
+| （填写） | | | |
+
+### 禁止的实现方式
+
+- 禁止仅用单个 `*DetailDrawer.vue` 只读 `info-grid` 代替演示中的多区块/可编辑/弹窗。
+- 禁止 tasks 只写「实现 DetailDrawer」而不拆演示模块。
+- 禁止 08 报告证据仅写 `index.vue:1`。

package/src/templates/prompts/02-sdd-loop-prompt.md

@@ -46,7 +46,7 @@
 |------|------|
 | `01` | 业务概述、范围、风险（**不承担**完整验收） |
 | `05` | **唯一验收 SSOT**（从 `source/PRD.md` 逐条抽 AC） |
-| `04` | 技术方案（引用 AC-ID） |
+| `04` | **可开发级**前端技术方案（**保留模板全部 11 章**，引用 AC-ID） |
 | `02` | 代码改动计划表 |
 
 #### 3. 文档模板要求
@@ -73,6 +73,19 @@
 *   **格式**：表格形式（仅在“提问模式”下生成或更新）。
 *   **字段**：问题类型 (断点/起点缺失/推测缺口) | 问题描述 | 代码位置 (如有) | 建议/待确认项。
 
+**📄 04-技术文档草稿.md（与 `04-技术文档.template.md` 同结构，强制）**
+
+> **必读**：同 run 目录下 `04-技术文档生成指引.md`。  
+> **禁止**用 bullet 摘要替换整份文件；**禁止**删减 `##` / `###` 章节标题。
+
+*   **填写方式**：Read 现有 `04-技术文档草稿.md`（脚手架已写入完整模板）→ **在原文件内逐节替换占位**，不得新建简化版。
+*   **输入**：`source/PRD.md`、`source/接口文档.md`、用户演示代码路径（Vue/React）、`05-验收清单.md`、仓库代码扫描结果。
+*   **必备章节**（标题须保留）：文档元信息 → §1 改造范围（含 1.1–1.4）→ §2 页面与交互（含 **2.4 演示代码参照与映射表**）→ §3 状态模型 → §4 接口（含 **4.1 接口清单表**、4.3 字段映射/normalize）→ §5 表单校验 → §6 边界 → §7 **文件级**改造清单 → §8 风险表 → §9 发布回滚 → §10 测试验收 → §11 待确认。
+*   **篇幅**：填完后通常 **≥150 行**；§4.1 至少 5 条接口；UI 类 §2.4 至少 3 行演示映射。
+*   **AC 标注**：`[AC-XX]` 分散在各章节，勿只在文首堆叠。
+*   **详情/抽屉类**：须按演示代码拆子模块写入 §2.2 / §2.4 / §7（如 BD预估编辑、红票及其他、可编辑金额），**禁止**仅写单个 `*DetailDrawer`。
+*   **gate**：`docs-closed` 会校验 `tech-doc-structure`，不合格不得 propose。
+
 ---
 
 ### 🚦 核心指令 (Execution Logic)
@@ -100,19 +113,20 @@
 
 **任务（阶段 B 文档产出；`full-chain` 模式下不得在本路径结束回合）**：
 1.  更新 `03-待确认问题清单.md`，标注“**矛盾点池状态：已闭合**”，写入用户确认结论。
-2.  **从 `source/PRD.md` 生成 `05-验收清单.md`**（标注「定义状态：已定义」），再生成 `04-技术文档草稿.md`（引用 AC-ID）。
-3.  生成最终版 `01-需求分析报告.md` 和 `02-改动点清单.md`（清单中的路径是**计划**，不得在本回合修改这些文件）。
-4.  确认 `02-改动点清单.md` 中仅包含代码文件改动，不涉及 `openspec/spec/` 内容。
-5.  **禁止** 在阶段 B 内修改 `src/` 等业务代码。
-6.  更新 `.session-state.json`：`status: ready_for_propose`；若用户口令含执行模式，同步 `executionMode` / `strictCommands`。
-7.  执行 `gate docs-closed` → `phase advance --to docs-done`（exit 0 才继续）。
-8.  **若 `autoChainOpsx !== false` 且 `executionMode !== staged-confirm`（默认 full-chain）**：**不得结束回合**，同一回合继续读 `07-opsx-自动串联指引.md`，执行 C→D→E 直至 `deliver` exit 0；**不要**要求用户再说「继续」。
-9.  仅当 `autoChainOpsx === false` 时输出：`05/01/02/03/04 已更新。回复「继续」进入提案。`
-10. **`executionMode=staged-confirm` 时**（含兼容口令「严格SOP，不可替代」）：
+2.  **从 `source/PRD.md` 生成 `05-验收清单.md`**（标注「定义状态：已定义」）。
+3.  **填写 `04-技术文档草稿.md`**：先 Read 已有模板文件 + `04-技术文档生成指引.md`，**保留全部章节标题**，逐节填入 PRD/接口/演示/代码扫描内容；**禁止**重写为摘要版。
+4.  生成最终版 `01-需求分析报告.md` 和 `02-改动点清单.md`（清单中的路径是**计划**，不得在本回合修改这些文件）。
+5.  确认 `02-改动点清单.md` 中仅包含代码文件改动，不涉及 `openspec/spec/` 内容。
+6.  **禁止** 在阶段 B 内修改 `src/` 等业务代码。
+7.  更新 `.session-state.json`：`status: ready_for_propose`；若用户口令含执行模式，同步 `executionMode` / `strictCommands`。
+8.  执行 `gate docs-closed` → `phase advance --to docs-done`（exit 0 才继续；失败则继续补全 04 直至 `tech-doc-structure` 通过）。
+9.  **若 `autoChainOpsx !== false` 且 `executionMode !== staged-confirm`（默认 full-chain）**：**不得结束回合**，同一回合继续读 `07-opsx-自动串联指引.md`，执行 C→D→E 直至 `deliver` exit 0；**不要**要求用户再说「继续」。
+10. 仅当 `autoChainOpsx === false` 时输出：`05/01/02/03/04 已更新。回复「继续」进入提案。`
+11. **`executionMode=staged-confirm` 时**（含兼容口令「严格SOP，不可替代」）：
     - 每阶段执行前先输出：`本次计划命令清单（逐条）`
     - 每阶段执行后输出：`门禁结果 + 证据文件路径 + 下一步命令`
     - 等待用户确认后再进入下一阶段
-11. **`strictCommands=true` 时**：禁止用等价命令替代 NEXT.md 中的 gate/phase 链路（可与 full-chain 组合，不强制每阶段暂停）
+12. **`strictCommands=true` 时**：禁止用等价命令替代 NEXT.md 中的 gate/phase 链路（可与 full-chain 组合，不强制每阶段暂停）
 
 ---
 

package/src/templates/prompts/04-tech-doc-fill-prompt.md

@@ -0,0 +1,71 @@
+# 04-技术文档填写规范（阶段 B 强制）
+
+> **SSOT 模板**：同目录 run 下已由脚手架生成的 `04-技术文档草稿.md`（来自 `04-技术文档.template.md`）。  
+> **禁止**用几行 bullet + `[AC-xx]` 替换整份文件；**必须保留模板全部章节标题**，仅在各节内填入真实内容。
+
+---
+
+## 填写方式（必须遵守）
+
+1. **先 Read** 当前 `04-技术文档草稿.md`（已是完整模板，约 11 章）。
+2. **在原文件上逐节替换**占位内容（`（填写）`、空表格行、示例行），**不得删除**任何 `##` / `###` 标题。
+3. 输入来源（按优先级）：
+   - `source/PRD.md`（业务规则、交互、文案）
+   - `source/接口文档.md`（§4 接口清单、字段映射）
+   - 用户提供的**演示代码**路径（Vue/React 均可 → §2.4 映射表）
+   - `05-验收清单.md`（在各章标注 `[AC-XX]`，勿只在文首堆叠）
+   - 仓库现有代码（§1 现状、§7 改造清单）
+4. 填完后自检：行数建议 **≥150**；§4.1 至少 **5 行**接口表；§2.4 至少 **3 行**演示映射（UI 类需求）。
+5. 运行 `npx sdd-flow-kit gate --expect docs-closed`；若 `tech-doc-structure` 失败，继续补全缺失章节。
+
+---
+
+## 各章最低填写要求
+
+### 文档元信息
+- 需求名称、版本、业务域、分支、关联 PRD/接口/演示路径/自测
+
+### §1 改造范围
+- **1.1** 量化成功标准；**1.2** 列出全部页面/路由/弹窗；**1.3** Out of Scope（含 mock、后续迭代）
+- 每条 In Scope 能力标注 `[AC-XX]`
+
+### §2 页面与交互设计
+- **2.1** 权限/场景矩阵（有权限/无权限/只读等）
+- **2.2** 至少 2 条用户路径（列表、详情、导入、编辑…）写清 Step 与成功/失败 toast **完整文案**
+- **2.3** loading、空态、防重复提交
+- **2.4 演示代码参照（UI 必填）**：根路径、技术栈、**映射表**（演示模块 → 计划生产组件 → 关键交互信号）
+
+### §3 状态与数据模型
+- 核心 TypeScript 类型（列表行、详情 VO、表单草稿）
+- remote / ui / 派生状态划分；详情打开/关闭清理
+
+### §4 接口与数据交互
+- **4.1 表格**：接口路径 | Method | 用途 | 请求字段 | 响应字段 | 异常处理
+- **4.3** 写明后端 SNAKE_CASE → 前端 camelCase normalize 位置（如 `config/api/modules/*/caseTransform`）
+- 提交 payload 示例（JSON）
+
+### §5 表单与校验
+- 关键弹窗/编辑字段校验矩阵（必填、格式、错误文案）
+
+### §6–§11
+- 边界场景、文件级改造清单（**禁止**只写一个大组件名）、风险表、发布检查、测试要点与 05 AC 对应、待确认项（无则写「无」）
+
+---
+
+## 禁止的反模式（gate 会失败）
+
+| 反模式 | 示例 |
+|--------|------|
+| 摘要替换 | 仅 7 条 `## N. xxx [AC-xx]` 列表 |
+| 删章节 | 缺少 §3/§5/§6/§8/§9/§11 |
+| 无接口表 | §4 只有一句话「封装 api/modules」 |
+| 无演示映射 | UI 需求但 §2.4 为空 |
+| 详情一笔带过 | 「FinanceDetailDrawer」不提子模块（BD预估、红票、可编辑金额） |
+
+---
+
+## 与下游衔接
+
+- Propose 时：`design.md` **复制** §2.4 映射表 + §4 接口决策
+- `tasks.md`：**一行映射表 → 至少一条**「演示模块迁移」任务
+- 实现：**禁止**用单文件只读骨架代替映射表中的多个生产组件