@gordon.gan/specflow 1.8.2-beta → 1.8.4-beta

package/dist/cli/commands/document-run.js

@@ -717,12 +717,15 @@ function buildSynthRules(dirs) {
     return [
         `## 跨仓合成规则（必须遵守）`,
         `1. **统一大纲**：一次生成一份 outline，章节覆盖所有仓，不按仓分章（跨仓对比/汇总放进对应章节）。`,
-        `2. **契约实体命名空间**：跨仓实体 id 用 \`<repo>_<id>\` 前缀（如 \`repo1_I1\`、\`repo2_T1\`），禁止不同仓共用裸 id。`,
-        `3. **每章必须分仓小节（质量门禁，validate 强制）**：每个必选章节的叙述按仓分节，用 \`### <repo>\` 小节标题（可带后缀如 \`### repo1 · 目标\`），且每个仓（${repoList}）都必须出现。禁止把多仓内容混写成一段（会导致细节互相稀释）。`,
-        `4. **全局视角**（若所选 profile 包含对应章节）：goal 写多仓总目标与边界；tech-selection 对比各仓技术方案；api-design/data-model 分仓列契约；closed-loop 跨仓统一闭环检查；implementability 跨仓统一可实施性评估。其他场景章节（如 reproduce/root-cause/fix、requirement/test-strategy、research/poc-demo/benchmark）同样按仓分节并给出跨仓结论。`,
+        `2. **契约单一定义**：同一物理端点（method+path）只定义一个契约实体，用 \`side\`（console/worker/internal）与 \`consumers\`/\`producers\`（仓名）标注面与消费方/生产方；\`<repo>_<id>\` 前缀仅作为追溯别名保留，禁止为不同仓重复定义同一接口（validate 会以 \`duplicate_contract\` 拦截）。`,
+        `3. **整体性组织（替代按仓分节）**：每章按主题写成一段整体叙述，仓归属用内联 \`[${repoList.split('、').join('] / [')}]\` 标注或表格「归属」列；**禁止**为无内容的仓写占位小节（如「某仓无 UI」）；若确需 \`### <repo>\` 小节，小节必须有实质内容（validate 会以 \`repo_section_stub\` 拦截空壳）。`,
+        `4. **全局视角**（若所选 profile 包含对应章节）：goal 写多仓总目标与边界；tech-selection 对比各仓技术方案；**接口与数据合并为「接口与数据设计」章**（接口总览 → 逐接口明细 → 数据模型与契约-表映射 → 存量回滚，DDL 就近引用附录），含契约-表映射表（每接口 ↔ 读写表/列）；closed-loop 跨仓统一闭环检查；implementability 跨仓统一可实施性评估。`,
         `5. **跨仓依赖/风险**：涉及仓间依赖（接口调用/数据共享/发布顺序）时显式标注「跨仓依赖」。`,
         `6. **按需加载规约（重要）**：写某个仓的小节时，**只读取该仓**的规约/IDE rules/guidance（该仓的 \`docs/\`、\`.cursor\`、\`.claude\`、\`.agents\` 等），**禁止一次性读取全部仓的规约**；只有写跨仓内容（接口对接/数据共享/发布顺序）时才读取**涉及仓**的规约。未读取的仓规约不得臆测，必要时标注「未读取该仓规约，待确认」。`,
         `7. **输入归属**：每段输入带「来源仓」标记，段 id 携带仓前缀（如 \`seg-repo1-proposal-01\`）；引用原文时按段 id 精确取回对应仓的片段，不整篇重读。`,
+        `8. **完整性骨架**：合成文档必须含术语与约定表、非目标汇总、风险与开放问题、决策记录（ADR，正文用 \`[D#]\` 引用，决策先定义后引用，validate 以 \`forward_decision_ref\` 提示前向引用）。`,
+        `9. **示例与字段表**：接口实体必须填 \`request_example\`/\`success_response_example\`/\`failure_response_example\`（真实 JSON body，无请求体方法显式标注「无请求体」）；请求字段与响应字段分列填写；错误表按 \`backend\`（gRPC→HTTP 映射）/ \`guard\`（前端守卫行为）/ \`internal\`（Worker 内部语义）分类。`,
+        `10. **主流程必须含图**：主业务流程章输出整体流程图（含失败分支）+ 时序图 + 失败路径决策图，图必须有文字说明（validate 以 diagram 门禁拦截缺图）。`,
     ].join('\n');
 }
 /**

package/dist/core/document/engine.js

@@ -17,7 +17,7 @@ import { renderDocument, renderHtml } from './render.js';
 import { runGates } from './gates.js';
 import { resolvePaths, reposPath, chapterPath } from './paths.js';
 import { parseEntitiesLenient } from './schemas.js';
-import { lintNarrative, checkRepoSectionCoverage } from './lint.js';
+import { lintNarrative, checkRepoCoverage, checkRepoSectionStub, checkDuplicateContract, checkExamplePresence, checkForwardDecisionRef, checkUnverifiedNumber, checkDataContractMapping } from './lint.js';
 import { checkStructuredCoverage } from './coverage.js';
 import { resolveProjectConventionPaths } from '../project-conventions.js';
 import { extractContracts, EMPTY_CONTRACTS } from './extract.js';
@@ -227,8 +227,18 @@ export async function runDocument(options) {
         await writeReviewResult(workRoot, review);
     }
     // --- Pass 4: render (T9) ---
+    // Multi-repo synthesize marker: repos.json (written by document synthesize) — 提前读取，
+    // 供渲染文档头元信息与 runGates 整体性门禁共用（Agent 模式 validateWork 亦同）。
+    let synthRepos = [];
+    try {
+        const raw = JSON.parse(await fs.readFile(reposPath(workRoot), 'utf-8'));
+        synthRepos = Array.isArray(raw) ? raw.filter((r) => typeof r === 'string') : [];
+    }
+    catch {
+        // no repos.json → not a synthesize workRoot → gate skipped (bundle/run unaffected)
+    }
     const appendixAntiAI = await readAppendix(workRoot, 'anti-ai');
-    const documentMd = renderDocument({ outline, entities: allEntities, narratives: narrativeMap, profile, appendixAntiAI });
+    const documentMd = renderDocument({ outline, entities: allEntities, narratives: narrativeMap, profile, appendixAntiAI, repos: synthRepos.length > 0 ? synthRepos : undefined });
     if (persist)
         await fs.writeFile(paths.documentMd, documentMd, 'utf-8');
     let documentHtml;
@@ -238,16 +248,6 @@ export async function runDocument(options) {
             await fs.writeFile(paths.documentHtml, documentHtml, 'utf-8');
     }
     // --- Gates (T10) ---
-    // Multi-repo synthesize marker: repos.json (written by document synthesize) → runGates enforces
-    // the per-repo section gate in the library pipeline too (not only Agent-mode validateWork).
-    let synthRepos = [];
-    try {
-        const raw = JSON.parse(await fs.readFile(reposPath(workRoot), 'utf-8'));
-        synthRepos = Array.isArray(raw) ? raw.filter((r) => typeof r === 'string') : [];
-    }
-    catch {
-        // no repos.json → not a synthesize workRoot → gate skipped (bundle/run unaffected)
-    }
     const gates = await runGates({
         outline,
         chapterNarratives: narrativeMap,
@@ -675,8 +675,8 @@ export async function validateWork(options) {
         }
     }
     // Multi-repo synthesize quality gate: if repos.json exists (document synthesize wrote it),
-    // every required chapter must have a per-repo section (`### <repo>`) for ALL repos.
-    // This prevents "伪统一" — cross-repo content diluting each other into vague prose.
+    // 整体性组织门禁——全文级仓覆盖（防某仓被概括掉）+ 空壳小节拦截（禁「某仓无 X」占位），
+    // 替代旧「每章必须 ### <repo> 分仓小节」；另附契约质量 lint（与 runGates 库模式一致）。
     let synthRepos = [];
     try {
         const raw = JSON.parse(await fs.readFile(reposPath(workRoot), 'utf-8'));
@@ -686,18 +686,34 @@ export async function validateWork(options) {
         // no repos.json → not a synthesize workRoot → gate skipped (bundle/run unaffected)
     }
     if (synthRepos.length >= 2) {
-        const requiredIds = new Set(profile.required);
-        for (const ch of outline.chapters) {
-            if (!requiredIds.has(ch.id))
-                continue;
-            const narrative = narrativeMap.get(ch.id);
-            if (narrative === undefined)
-                continue; // chapter_missing already reported
-            for (const d of checkRepoSectionCoverage(ch.id, narrative, synthRepos)) {
-                diags.push({ gate: 'synthesize', code: d.code, severity: d.severity, message: d.message, chapter: ch.id });
+        for (const d of checkRepoCoverage(synthRepos, narrativeMap)) {
+            diags.push({ gate: 'synthesize', code: d.code, severity: d.severity, message: d.message });
+        }
+        for (const [chId, narrative] of narrativeMap) {
+            for (const d of checkRepoSectionStub(chId, narrative, synthRepos)) {
+                diags.push({ gate: 'synthesize', code: d.code, severity: d.severity, message: d.message, chapter: chId });
             }
         }
     }
+    for (const d of checkDuplicateContract(allEntities.interfaces)) {
+        diags.push({ gate: 'lint', code: d.code, severity: d.severity, message: d.message });
+    }
+    for (const d of checkExamplePresence(allEntities.interfaces)) {
+        diags.push({ gate: 'lint', code: d.code, severity: d.severity, message: d.message });
+    }
+    for (const d of checkForwardDecisionRef(narrativeMap, allEntities.decisions)) {
+        diags.push({ gate: 'lint', code: d.code, severity: d.severity, message: d.message, chapter: d.chapter });
+    }
+    for (const [chId, narrative] of narrativeMap) {
+        for (const d of checkUnverifiedNumber(chId, narrative)) {
+            diags.push({ gate: 'lint', code: d.code, severity: d.severity, message: d.message, chapter: chId });
+        }
+    }
+    if (synthRepos.length >= 2) {
+        for (const d of checkDataContractMapping(narrativeMap, allEntities)) {
+            diags.push({ gate: 'lint', code: d.code, severity: d.severity, message: d.message });
+        }
+    }
     // Structured coverage (entity points must be filled).
     for (const d of checkStructuredCoverage(outline, entityMap)) {
         diags.push({ gate: 'coverage', code: d.code, severity: d.severity, message: d.message, chapter: d.chapter });
@@ -710,7 +726,7 @@ export async function validateWork(options) {
         return { ok: false, diagnostics: diags };
     }
     // Render (appendices driven by profile.appendices).
-    const documentMd = renderDocument({ outline, entities: allEntities, narratives: narrativeMap, profile, appendixAntiAI });
+    const documentMd = renderDocument({ outline, entities: allEntities, narratives: narrativeMap, profile, appendixAntiAI, repos: synthRepos.length > 0 ? synthRepos : undefined });
     await fs.writeFile(paths.documentMd, documentMd, 'utf-8');
     let documentHtml;
     if (options.renderHtmlOutput !== false) {

package/dist/core/document/gates.js

@@ -2,7 +2,7 @@
  * Document Engine — gate orchestration (T10.4).
  * Runs lint → structured coverage → review check → budget → zod, collecting diagnostics.
  */
-import { lintNarrative, checkBudget, checkDiagramPresence, checkNumericPresence, checkGoldenSignals, checkRepoSectionCoverage } from './lint.js';
+import { lintNarrative, checkBudget, checkDiagramPresence, checkNumericPresence, checkGoldenSignals, checkRepoCoverage, checkRepoSectionStub, checkDuplicateContract, checkExamplePresence, checkForwardDecisionRef, checkUnverifiedNumber, checkDataContractMapping, } from './lint.js';
 import { checkStructuredCoverage } from './coverage.js';
 import { checkReviewResult } from './review.js';
 export async function runGates(input) {
@@ -48,18 +48,38 @@ export async function runGates(input) {
             }
         }
     }
-    // Multi-repo synthesize gate (library pipeline): every non-optional chapter must have per-repo
-    // sections (`### <repo>`) when repos ≥2 — matches validateWork (Agent mode) enforcement.
+    // Multi-repo synthesize gate (library pipeline): 全文级仓覆盖 + 空壳小节拦截（整体性组织，
+    // 替代旧「每章必须 ### <repo> 分仓小节」）。matches validateWork (Agent mode) enforcement.
     if (input.repos && input.repos.length >= 2) {
-        const requiredById = new Map(input.outline.chapters.filter((c) => !c.optional).map((c) => [c.id, c]));
+        for (const d of checkRepoCoverage(input.repos, input.chapterNarratives)) {
+            diags.push({ gate: 'synthesize', code: d.code, severity: d.severity, message: d.message });
+        }
         for (const [chId, narrative] of input.chapterNarratives) {
-            if (!requiredById.has(chId))
-                continue;
-            for (const d of checkRepoSectionCoverage(chId, narrative, input.repos)) {
+            for (const d of checkRepoSectionStub(chId, narrative, input.repos)) {
                 diags.push({ gate: 'synthesize', code: d.code, severity: d.severity, message: d.message, chapter: chId });
             }
         }
     }
+    // 契约质量 lint：契约单一定义 / 示例带 body（空壳拦截）/ 前向决策引用 / 未验证数字 / 契约-表映射。
+    for (const d of checkDuplicateContract(input.entities.interfaces)) {
+        diags.push({ gate: 'lint', code: d.code, severity: d.severity, message: d.message });
+    }
+    for (const d of checkExamplePresence(input.entities.interfaces)) {
+        diags.push({ gate: 'lint', code: d.code, severity: d.severity, message: d.message });
+    }
+    for (const d of checkForwardDecisionRef(input.chapterNarratives, input.entities.decisions)) {
+        diags.push({ gate: 'lint', code: d.code, severity: d.severity, message: d.message, chapter: d.chapter });
+    }
+    for (const [chId, narrative] of input.chapterNarratives) {
+        for (const d of checkUnverifiedNumber(chId, narrative)) {
+            diags.push({ gate: 'lint', code: d.code, severity: d.severity, message: d.message, chapter: chId });
+        }
+    }
+    if (input.repos && input.repos.length >= 2) {
+        for (const d of checkDataContractMapping(input.chapterNarratives, input.entities)) {
+            diags.push({ gate: 'lint', code: d.code, severity: d.severity, message: d.message });
+        }
+    }
     // structured coverage
     for (const d of checkStructuredCoverage(input.outline, input.chapterEntities)) {
         diags.push({ gate: 'coverage', code: d.code, severity: d.severity, message: d.message, chapter: d.chapter });

package/dist/core/document/lint.d.ts

@@ -36,4 +36,30 @@ export interface RepoSectionDiagnostic {
     message: string;
     chapter?: string;
 }
-export declare function checkRepoSectionCoverage(chapterId: string, narrative: string, repos: readonly string[]): RepoSectionDiagnostic[];
+export declare function countRepoMentions(narrative: string, repo: string): number;
+export declare function checkRepoCoverage(repos: readonly string[], narratives: ReadonlyMap<string, string>, threshold?: number): RepoSectionDiagnostic[];
+export declare function checkRepoSectionStub(chapterId: string, narrative: string, repos: readonly string[], minChars?: number): RepoSectionDiagnostic[];
+/** 同一物理端点（method+path 归一化）不得存在多个接口实体。 */
+export declare function checkDuplicateContract(interfaces: ReadonlyArray<{
+    method: string;
+    path: string;
+    id: string;
+}>): RepoSectionDiagnostic[];
+/** 空壳示例拦截：body 方法必须给 request_example（或标注「无请求体」）；有响应字段必须有成功响应示例。 */
+export declare function checkExamplePresence(interfaces: ReadonlyArray<{
+    id: string;
+    method: string;
+    request_example?: string;
+    response_fields?: unknown[];
+    success_response_example?: string;
+}>): RepoSectionDiagnostic[];
+/** 前向决策引用：叙述引用 [D#] 但该决策未在 entities.decisions 定义 → warning（P6 决策位置前移辅助检查）。 */
+export declare function checkForwardDecisionRef(narratives: ReadonlyMap<string, string>, decisions: ReadonlyArray<{
+    id: string;
+}>): RepoSectionDiagnostic[];
+/** 性能章目标数字必须标注来源/待实测（P10）。 */
+export declare function checkUnverifiedNumber(chapterId: string, narrative: string): RepoSectionDiagnostic[];
+/** 接口与数据整合（P11）：synth 模式下有表实体时，接口章必须含契约-表映射表。 */
+export declare function checkDataContractMapping(narratives: ReadonlyMap<string, string>, entities: {
+    tables?: unknown[];
+}): RepoSectionDiagnostic[];

package/dist/core/document/lint.js

@@ -124,24 +124,143 @@ export function checkGoldenSignals(chapterId, narrative, gates = []) {
             message: `Chapter "${chapterId}" gates require SRE 四金信号 monitoring but missing: ${missing.map((m) => m.key).join('、')}（监控必须覆盖延迟/流量/错误/饱和度）`,
         }];
 }
-export function checkRepoSectionCoverage(chapterId, narrative, repos) {
+export function countRepoMentions(narrative, repo) {
+    const esc = escapeRegExp(repo);
+    const re = new RegExp(`\\[${esc}\\]|^###\\s+${esc}(?:\\s|：|:|·|$)|${esc}_`, 'gm');
+    return (narrative.match(re) ?? []).length;
+}
+export function checkRepoCoverage(repos, narratives, threshold = 3) {
     if (repos.length < 2)
         return []; // 非 synthesize 或单仓 → 不校验
+    const joined = [...narratives.values()].join('\n');
     const diags = [];
     for (const repo of repos) {
-        // 匹配 `### <repo>` 小节标题（行首，可带后缀如 `### repo1 · 目标`）
-        const sectionRe = new RegExp(`^###\\s+${escapeRegExp(repo)}(?:\\s|：|:|·|$)`, 'm');
-        if (!sectionRe.test(narrative)) {
+        if (countRepoMentions(joined, repo) < threshold) {
             diags.push({
-                code: 'repo_section_missing',
+                code: 'repo_coverage_missing',
+                severity: 'error',
+                message: `合成文档中仓 ${repo} 全文累计出现 < ${threshold} 次（应含 [${repo}] 标注、\`### ${repo}\` 小节或 ${repo}_ 前缀实体），疑似被概括掉`,
+            });
+        }
+    }
+    return diags;
+}
+export function checkRepoSectionStub(chapterId, narrative, repos, minChars = 40) {
+    const diags = [];
+    for (const repo of repos) {
+        const re = new RegExp(`^###\\s+${escapeRegExp(repo)}(?:\\s|：|:|·|$)[\\s\\S]*?(?=^###|$)`, 'm');
+        const m = re.exec(narrative);
+        if (!m)
+            continue;
+        const sectionBody = m[0].replace(/^###[^\n]*\n/, '').trim();
+        if (sectionBody.length < minChars) {
+            diags.push({
+                code: 'repo_section_stub',
                 severity: 'error',
                 chapter: chapterId,
-                message: `Chapter "${chapterId}" 缺少仓 ${repo} 的分仓小节（应含 \`### ${repo}\`，合成文档每章必须按仓分节，防止跨仓内容互相稀释）`,
+                message: `Chapter "${chapterId}" 的仓 ${repo} 小节内容过短（< ${minChars} 字符，疑似「无 X」占位），请并入整体叙述或补足实质内容`,
+            });
+        }
+    }
+    return diags;
+}
+// ============= 契约质量 lint（P2/P3/P4/P6：契约单一定义 / 示例带 body / 前向决策引用） =============
+/** 同一物理端点（method+path 归一化）不得存在多个接口实体。 */
+export function checkDuplicateContract(interfaces) {
+    const diags = [];
+    const seen = new Map();
+    for (const it of interfaces) {
+        const key = `${it.method} ${it.path.trim().toLowerCase()}`;
+        const prev = seen.get(key);
+        if (prev) {
+            diags.push({
+                code: 'duplicate_contract',
+                severity: 'error',
+                message: `接口 ${it.id} 与 ${prev} 为同一物理端点（${it.method} ${it.path}），契约应单一定义并标注消费方/生产方（<repo>_<id> 仅作追溯别名）`,
+            });
+        }
+        else {
+            seen.set(key, it.id);
+        }
+    }
+    return diags;
+}
+const BODY_METHODS = new Set(['POST', 'PUT', 'PATCH']);
+const NO_BODY_MARK = /无请求体/;
+/** 空壳示例拦截：body 方法必须给 request_example（或标注「无请求体」）；有响应字段必须有成功响应示例。 */
+export function checkExamplePresence(interfaces) {
+    const diags = [];
+    for (const it of interfaces) {
+        const example = (it.request_example ?? '').trim();
+        const isNoBodyMark = NO_BODY_MARK.test(example);
+        // 空壳拦截：body 方法既无真实 JSON 请求体、也未显式标注「无请求体」→ error。
+        if (BODY_METHODS.has(it.method) && !isNoBodyMark && example.length === 0) {
+            diags.push({
+                code: 'request_example_missing',
+                severity: 'error',
+                message: `接口 ${it.id}（${it.method}）缺少 request_example（真实 JSON 请求体），空壳「成功示例」不合格；确无请求体请显式标注「无请求体」`,
+            });
+        }
+        if ((it.response_fields?.length ?? 0) > 0 && !it.success_response_example) {
+            diags.push({
+                code: 'response_example_missing',
+                severity: 'error',
+                message: `接口 ${it.id} 声明了响应字段但缺少 success_response_example（真实 JSON 成功响应示例）`,
             });
         }
     }
     return diags;
 }
+/** 前向决策引用：叙述引用 [D#] 但该决策未在 entities.decisions 定义 → warning（P6 决策位置前移辅助检查）。 */
+export function checkForwardDecisionRef(narratives, decisions) {
+    const defined = new Set(decisions.map((d) => d.id));
+    const diags = [];
+    const re = /\[(D\d+)\]/g;
+    for (const [chId, narrative] of narratives) {
+        let m;
+        while ((m = re.exec(narrative)) !== null) {
+            if (!defined.has(m[1])) {
+                diags.push({
+                    code: 'forward_decision_ref',
+                    severity: 'warning',
+                    chapter: chId,
+                    message: `Chapter "${chId}" 引用了未定义的决策 ${m[1]}（决策应在 ADR 章节先行定义，正文用 [D#] 引用）`,
+                });
+            }
+        }
+    }
+    return diags;
+}
+/** 性能章目标数字必须标注来源/待实测（P10）。 */
+export function checkUnverifiedNumber(chapterId, narrative) {
+    if (chapterId !== 'performance')
+        return [];
+    if (!/\d/.test(narrative))
+        return [];
+    if (!/待实测|门闩|测量|实测|基准/.test(narrative)) {
+        return [{
+                code: 'unverified_number',
+                severity: 'warning',
+                chapter: chapterId,
+                message: `Chapter "${chapterId}" 含目标数字但未标注「待实测/门闩/测量方法」，数字可信度不足（性能数字必须给来源或测量方式）`,
+            }];
+    }
+    return [];
+}
+/** 接口与数据整合（P11）：synth 模式下有表实体时，接口章必须含契约-表映射表。 */
+export function checkDataContractMapping(narratives, entities) {
+    if ((entities.tables?.length ?? 0) === 0)
+        return [];
+    const narrative = narratives.get('api-design') ?? '';
+    if (!/契约-表映射|映射表|接口.*表.*映射|表.*接口.*映射/.test(narrative)) {
+        return [{
+                code: 'data_contract_mapping_missing',
+                severity: 'warning',
+                message: '接口与数据应整合呈现：api-design 章缺少「契约-表映射」（每接口 ↔ 读写表/列），接口约定与数据库仍游离',
+            }];
+    }
+    return [];
+}
 function escapeRegExp(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }

package/dist/core/document/render.d.ts

@@ -19,7 +19,10 @@ export declare function renderTable(t: TableEntity): string;
 export declare function renderDecisions(decisions: Array<{
     id: string;
     text: string;
+    background?: string;
+    alternative?: string;
 }>): string;
+/** 契约实体按「面」分组渲染（Console 面 / 内部与 Worker 面），替代平铺。 */
 export declare function renderEntities(entities: Entities): string;
 export interface RenderDocumentInput {
     outline: Outline;
@@ -32,6 +35,10 @@ export interface RenderDocumentInput {
     };
     /** LLM-written anti-AI self-check items (from appendices/anti-ai.md, optional). */
     appendixAntiAI?: string;
+    /** 参与仓清单（synth 模式）：渲染文档头元信息（P7 整体性）。 */
+    repos?: string[];
+    /** 是否渲染产物溯源附录（P8：默认关闭，调试/--signoff 时开启）。 */
+    includeProvenance?: boolean;
 }
 /** Strip engine repair notes (`<!-- review-fix ... -->`) from the FINAL render. The audit trail
  *  stays in `chapters/<id>.md` and `review-result.json`; the deliverable document must not show
@@ -53,6 +60,17 @@ export declare function stripEntityJsonBlocks(text: string): string;
  * 仅当首行非空是 H1 且其内容与章节标题 trim 后一致时才剥离，避免误删正文中的真实内容。
  */
 export declare function stripLeadingTitle(text: string, chapterTitle: string): string;
+/**
+ * 章节叙述标题整体降级 n 级（默认 1）。原因：renderDocument 已为每章输出 `## <章节标题>`（H2），
+ * 而 Agent 生成的叙述内小节标题习惯用 `##`（H2）、分仓小节用 `###`（H3）——与章节头同级，
+ * 造成最终文档目录层级乱（`## 需求` 与 `## 跨仓总目标` 平级）。渲染时降级：`##`→`###`、`###`→`####`…，
+ * 使章节头 H2 → 叙述小节 H3 → 分仓 H4，层级正确。
+ *
+ * 只处理行首的 markdown 标题（`#{1,6}\s`），并跳过围栏代码块（mermaid/``` 内部行不动），
+ * 避免把代码内容里的 `#` 误判成标题。H6 封顶不再升。质量门禁 `### <repo>` 检查的是原始章节
+ * 文件（chapters/*.md），不在此处降级影响范围——仅最终渲染的 document.md 生效。
+ */
+export declare function demoteHeadings(text: string, levels?: number): string;
 export declare function renderDocument(input: RenderDocumentInput): string;
 /** 附录 B · 去AI味自检（frontend-dev-guide §十一 → README §1.6 五维表）。 */
 export declare function renderAppendixAntiAI(content?: string): string;

package/dist/core/document/render.js

@@ -31,32 +31,45 @@ export function escapeInline(s) {
 }
 // ============= Contract entity → Markdown (T9.1) =============
 export function renderInterface(i) {
-    const rows = [
+    const meta = [
         `##### ${i.id} · ${escapeInline(i.name)}（${i.method} ${i.path}）`,
         '',
-        '**字段表**',
-        '',
-        '| 字段 | 类型 | 必填 | 说明 |',
-        '|------|------|------|------|',
-        ...[...i.request_fields ?? [], ...i.response_fields ?? []].map((f) => `| ${escapeTableCell(f.name)} | ${escapeTableCell(f.type)} | ${f.required ? '是' : '否'} | ${escapeTableCell(f.desc ?? '')} |`),
-        '',
-        '**成功示例**',
-        '',
-        '```http',
-        `${i.method} ${escapeFenceContent(i.path)}`,
-        '```',
-        '',
-        '**失败示例**',
-        '',
-        ...i.failure_examples.map((ex) => `- ${escapeInline(ex)}`),
-        '',
+        ...(i.side || (i.consumers?.length ?? 0) > 0 || (i.producers?.length ?? 0) > 0
+            ? [`**面**：${escapeInline(i.side ?? '—')}${(i.consumers?.length ?? 0) > 0 ? ` ｜ **消费方**：${(i.consumers ?? []).map(escapeInline).join(', ')}` : ''}${(i.producers?.length ?? 0) > 0 ? ` ｜ **生产方**：${(i.producers ?? []).map(escapeInline).join(', ')}` : ''}`, '']
+            : []),
+    ];
+    const fieldRows = (fields) => fields.map((f) => `| ${escapeTableCell(f.name)} | ${escapeTableCell(f.type)} | ${f.required ? '是' : '否'} | ${escapeTableCell(f.desc ?? '')} |`);
+    const fieldTables = [];
+    if ((i.request_fields ?? []).length > 0) {
+        fieldTables.push('**请求字段**', '', '| 字段 | 类型 | 必填 | 说明 |', '|------|------|------|------|', ...fieldRows(i.request_fields ?? []));
+    }
+    if ((i.response_fields ?? []).length > 0) {
+        fieldTables.push('**响应字段**', '', '| 字段 | 类型 | 必填 | 说明 |', '|------|------|------|------|', ...fieldRows(i.response_fields ?? []));
+    }
+    const examples = [];
+    if (i.request_example) {
+        examples.push('**请求示例**', '', '```json', escapeFenceContent(i.request_example), '```');
+    }
+    if (i.success_response_example) {
+        examples.push('**成功响应示例**', '', '```json', escapeFenceContent(i.success_response_example), '```');
+    }
+    if ((i.failure_examples?.length ?? 0) > 0 || i.failure_response_example) {
+        examples.push('**失败示例**', '');
+        if ((i.failure_examples?.length ?? 0) > 0) {
+            examples.push(...(i.failure_examples ?? []).map((ex) => `- ${escapeInline(ex)}`));
+        }
+        if (i.failure_response_example) {
+            examples.push('', '```json', escapeFenceContent(i.failure_response_example), '```');
+        }
+    }
+    const errors = [
         '**错误**',
         '',
-        '| 条件 | 状态 | 说明 |',
-        '|------|------|------|',
-        ...i.errors.map((e) => `| ${escapeTableCell(e.condition)} | ${escapeTableCell(e.status)} | ${escapeTableCell(e.note ?? '')} |`),
+        '| 条件 | 状态 | 类别 | 说明 |',
+        '|------|------|------|------|',
+        ...i.errors.map((e) => `| ${escapeTableCell(e.condition)} | ${escapeTableCell(e.status)} | ${escapeTableCell(e.kind ?? 'backend')} | ${escapeTableCell(e.note ?? '')} |`),
     ];
-    return rows.join('\n');
+    return [...meta, ...fieldTables, ...examples, ...errors].join('\n');
 }
 export function renderTable(t) {
     return [
@@ -74,22 +87,37 @@ export function renderDecisions(decisions) {
     if (decisions.length === 0)
         return '';
     return [
-        '**决策记录**',
+        '## 决策记录（ADR）',
         '',
-        '| 决策 | 结论 |',
-        '|------|------|',
-        ...decisions.map((d) => `| ${escapeTableCell(d.id)} | ${escapeTableCell(d.text)} |`),
+        '| 决策 | 背景 | 结论 | 备选（已否决） |',
+        '|------|------|------|------|',
+        ...decisions.map((d) => `| ${escapeTableCell(d.id)} | ${escapeTableCell(d.background ?? '')} | ${escapeTableCell(d.text)} | ${escapeTableCell(d.alternative ?? '')} |`),
     ].join('\n');
 }
+/** 契约实体按「面」分组渲染（Console 面 / 内部与 Worker 面），替代平铺。 */
 export function renderEntities(entities) {
     const parts = [];
-    for (const i of entities.interfaces)
-        parts.push(renderInterface(i));
+    const groups = new Map();
+    for (const i of entities.interfaces) {
+        const key = i.side ?? 'other';
+        if (!groups.has(key))
+            groups.set(key, []);
+        groups.get(key).push(i);
+    }
+    const sideTitle = {
+        console: 'Console 面契约',
+        internal: '内部 / Worker 面契约',
+        worker: 'Worker 面契约',
+        other: '契约',
+    };
+    for (const key of ['console', 'internal', 'worker', 'other']) {
+        const list = groups.get(key);
+        if (!list || list.length === 0)
+            continue;
+        parts.push(`### ${sideTitle[key]}`, '', list.map(renderInterface).join('\n\n'));
+    }
     for (const t of entities.tables)
         parts.push(renderTable(t));
-    const decisionsMd = renderDecisions(entities.decisions);
-    if (decisionsMd)
-        parts.push(decisionsMd);
     return parts.join('\n\n');
 }
 /** Strip engine repair notes (`<!-- review-fix ... -->`) from the FINAL render. The audit trail
@@ -146,30 +174,97 @@ export function stripLeadingTitle(text, chapterTitle) {
     const rest = trimmed.slice(firstLine.length).replace(/^\n+/, '');
     return rest;
 }
+/**
+ * 章节叙述标题整体降级 n 级（默认 1）。原因：renderDocument 已为每章输出 `## <章节标题>`（H2），
+ * 而 Agent 生成的叙述内小节标题习惯用 `##`（H2）、分仓小节用 `###`（H3）——与章节头同级，
+ * 造成最终文档目录层级乱（`## 需求` 与 `## 跨仓总目标` 平级）。渲染时降级：`##`→`###`、`###`→`####`…，
+ * 使章节头 H2 → 叙述小节 H3 → 分仓 H4，层级正确。
+ *
+ * 只处理行首的 markdown 标题（`#{1,6}\s`），并跳过围栏代码块（mermaid/``` 内部行不动），
+ * 避免把代码内容里的 `#` 误判成标题。H6 封顶不再升。质量门禁 `### <repo>` 检查的是原始章节
+ * 文件（chapters/*.md），不在此处降级影响范围——仅最终渲染的 document.md 生效。
+ */
+export function demoteHeadings(text, levels = 1) {
+    if (levels <= 0)
+        return text;
+    const lines = text.split('\n');
+    let inFence = false;
+    const out = [];
+    for (const line of lines) {
+        const trimmed = line.trimStart();
+        if (trimmed.startsWith('```'))
+            inFence = !inFence;
+        if (!inFence) {
+            const m = /^(#{1,6})(\s.*)$/.exec(line);
+            if (m) {
+                const hashes = Math.min(m[1].length + levels, 6);
+                out.push('#'.repeat(hashes) + m[2]);
+                continue;
+            }
+        }
+        out.push(line);
+    }
+    return out.join('\n');
+}
 export function renderDocument(input) {
-    const { outline, entities, narratives, profile, appendixAntiAI } = input;
+    const { outline, entities, narratives, profile, appendixAntiAI, repos, includeProvenance } = input;
     const body = [`# 方案文档：${escapeInline(outline.profile)}`, ''];
-    for (const ch of outline.chapters) {
+    // 文档头元信息（P7）：确定性渲染，不依赖 LLM。
+    const meta = [];
+    if (repos && repos.length > 0)
+        meta.push(`| 参与仓 | ${repos.map(escapeTableCell).join('、')} |`);
+    if (meta.length > 0) {
+        body.push('| 项 | 值 |', '|------|------|', ...meta, '');
+    }
+    // 目录（P7）：按大纲章节序确定性生成；接口与数据合并时 data-model 不单列。
+    const apiDesignIdx = outline.chapters.findIndex((c) => c.id === 'api-design');
+    const dataModelIdx = outline.chapters.findIndex((c) => c.id === 'data-model');
+    const mergeDataModel = apiDesignIdx >= 0 && dataModelIdx > apiDesignIdx;
+    body.push('## 目录', '');
+    outline.chapters.forEach((ch, idx) => {
+        if (mergeDataModel && ch.id === 'data-model')
+            return;
+        body.push(`${idx + 1}. ${escapeInline(ch.title)}`);
+    });
+    body.push('');
+    for (const [idx, ch] of outline.chapters.entries()) {
+        if (mergeDataModel && ch.id === 'data-model')
+            continue; // 已并入「接口与数据设计」章
         body.push(`## ${escapeInline(ch.title)}`, '');
-        // 依次净化：剥内嵌契约 JSON 块（机器中间格式）→ 剥与章节标题重复的首行 H1 → 剥引擎修复注记。
-        const narrative = stripLeadingTitle(stripEntityJsonBlocks(stripReviewNotes(narratives.get(ch.id) ?? '')), ch.title);
+        // 依次净化：剥内嵌契约 JSON 块（机器中间格式）→ 剥与章节标题重复的首行 H1 → 剥引擎修复注记，
+        // 再把叙述内标题降级一级（章节头已占 H2，叙述小节 H2→H3），保证目录层级正确。
+        const narrative = demoteHeadings(stripLeadingTitle(stripEntityJsonBlocks(stripReviewNotes(narratives.get(ch.id) ?? '')), ch.title));
         if (narrative.trim())
             body.push(narrative.trim(), '');
+        // 接口与数据整合（P11）：data-model 紧随 api-design 时并入其下为小节，不再单独成章。
+        if (mergeDataModel && ch.id === 'api-design') {
+            const dm = outline.chapters[dataModelIdx];
+            const dmNarrative = demoteHeadings(stripLeadingTitle(stripEntityJsonBlocks(stripReviewNotes(narratives.get(dm.id) ?? '')), dm.title));
+            if (dmNarrative.trim())
+                body.push('### 数据模型', '', dmNarrative.trim(), '');
+        }
+    }
+    // 决策记录（ADR）独立成节（P6）：不再埋在契约实体末尾。
+    const decisionsMd = renderDecisions(entities.decisions);
+    if (decisionsMd.trim()) {
+        body.push('---', '', decisionsMd, '');
     }
     // Contract entities: append to the chapters that reference them (simplified: append in a
-    // final "契约" section, since entities are cross-chapter).
+    // final "附录 A" section, since entities are cross-chapter).
     const contractMd = renderEntities(entities);
     if (contractMd.trim()) {
-        body.push('---', '', '## 契约实体', '', contractMd, '');
+        body.push('---', '', '## 附录 A：契约实体明细', '', contractMd, '');
     }
-    // 产物溯源附录 (borrowed from approval · appendix A): each chapter's data source.
-    body.push('---', '', '## 附录 A: 产物溯源', '');
-    body.push('| 章节 | 数据来源 | 处理方式 |');
-    body.push('|------|---------|---------|');
-    for (const ch of outline.chapters) {
-        body.push(`| ${escapeTableCell(ch.title)} | 输入素材 / 项目规约 / 大纲要点 | LLM 生成 + 引擎校验 |`);
+    // 产物溯源附录（P8）：默认不渲染（synth 下每章来源雷同，属噪声）；--signoff/调试时开启。
+    if (includeProvenance) {
+        body.push('---', '', '## 附录：产物溯源', '');
+        body.push('| 章节 | 数据来源 | 处理方式 |');
+        body.push('|------|---------|---------|');
+        for (const ch of outline.chapters) {
+            body.push(`| ${escapeTableCell(ch.title)} | 输入素材 / 项目规约 / 大纲要点 | LLM 生成 + 引擎校验 |`);
+        }
+        body.push('', '');
     }
-    body.push('', '');
     // 附录 B/C: rendered from profile.appendices (decision: deterministic templates, §7.3).
     const appendices = profile?.appendices ?? [];
     if (appendices.includes('anti-ai')) {

package/dist/core/document/schemas.d.ts

@@ -34,13 +34,17 @@ export declare const ErrorSpecSchema: z.ZodObject<{
     condition: z.ZodString;
     status: z.ZodString;
     note: z.ZodOptional<z.ZodString>;
+    /** 错误类别：backend=gRPC→HTTP 映射；guard=前端守卫行为；internal=Worker 内部语义（P5 拆分）。 */
+    kind: z.ZodOptional<z.ZodEnum<["backend", "guard", "internal"]>>;
 }, "strip", z.ZodTypeAny, {
     status: string;
     condition: string;
+    kind?: "backend" | "guard" | "internal" | undefined;
     note?: string | undefined;
 }, {
     status: string;
     condition: string;
+    kind?: "backend" | "guard" | "internal" | undefined;
     note?: string | undefined;
 }>;
 export declare const InterfaceEntitySchema: z.ZodObject<{
@@ -90,16 +94,26 @@ export declare const InterfaceEntitySchema: z.ZodObject<{
         condition: z.ZodString;
         status: z.ZodString;
         note: z.ZodOptional<z.ZodString>;
+        /** 错误类别：backend=gRPC→HTTP 映射；guard=前端守卫行为；internal=Worker 内部语义（P5 拆分）。 */
+        kind: z.ZodOptional<z.ZodEnum<["backend", "guard", "internal"]>>;
     }, "strip", z.ZodTypeAny, {
         status: string;
         condition: string;
+        kind?: "backend" | "guard" | "internal" | undefined;
         note?: string | undefined;
     }, {
         status: string;
         condition: string;
+        kind?: "backend" | "guard" | "internal" | undefined;
         note?: string | undefined;
     }>, "many">;
     failure_examples: z.ZodArray<z.ZodString, "many">;
+    request_example: z.ZodOptional<z.ZodString>;
+    success_response_example: z.ZodOptional<z.ZodString>;
+    failure_response_example: z.ZodOptional<z.ZodString>;
+    side: z.ZodOptional<z.ZodEnum<["console", "worker", "internal"]>>;
+    consumers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    producers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
     path: string;
     id: string;
@@ -107,6 +121,7 @@ export declare const InterfaceEntitySchema: z.ZodObject<{
     errors: {
         status: string;
         condition: string;
+        kind?: "backend" | "guard" | "internal" | undefined;
         note?: string | undefined;
     }[];
     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -125,6 +140,12 @@ export declare const InterfaceEntitySchema: z.ZodObject<{
         default?: string | undefined;
         desc?: string | undefined;
     }[] | undefined;
+    request_example?: string | undefined;
+    success_response_example?: string | undefined;
+    failure_response_example?: string | undefined;
+    side?: "internal" | "console" | "worker" | undefined;
+    consumers?: string[] | undefined;
+    producers?: string[] | undefined;
 }, {
     path: string;
     id: string;
@@ -132,6 +153,7 @@ export declare const InterfaceEntitySchema: z.ZodObject<{
     errors: {
         status: string;
         condition: string;
+        kind?: "backend" | "guard" | "internal" | undefined;
         note?: string | undefined;
     }[];
     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -150,6 +172,12 @@ export declare const InterfaceEntitySchema: z.ZodObject<{
         required?: boolean | undefined;
         desc?: string | undefined;
     }[] | undefined;
+    request_example?: string | undefined;
+    success_response_example?: string | undefined;
+    failure_response_example?: string | undefined;
+    side?: "internal" | "console" | "worker" | undefined;
+    consumers?: string[] | undefined;
+    producers?: string[] | undefined;
 }>;
 export type InterfaceEntity = z.infer<typeof InterfaceEntitySchema>;
 export declare const TableEntitySchema: z.ZodObject<{
@@ -208,12 +236,18 @@ export type TableEntity = z.infer<typeof TableEntitySchema>;
 export declare const DecisionEntitySchema: z.ZodObject<{
     id: z.ZodString;
     text: z.ZodString;
+    background: z.ZodOptional<z.ZodString>;
+    alternative: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     id: string;
     text: string;
+    background?: string | undefined;
+    alternative?: string | undefined;
 }, {
     id: string;
     text: string;
+    background?: string | undefined;
+    alternative?: string | undefined;
 }>;
 export type DecisionEntity = z.infer<typeof DecisionEntitySchema>;
 export declare const EntitiesSchema: z.ZodObject<{
@@ -264,16 +298,26 @@ export declare const EntitiesSchema: z.ZodObject<{
             condition: z.ZodString;
             status: z.ZodString;
             note: z.ZodOptional<z.ZodString>;
+            /** 错误类别：backend=gRPC→HTTP 映射；guard=前端守卫行为；internal=Worker 内部语义（P5 拆分）。 */
+            kind: z.ZodOptional<z.ZodEnum<["backend", "guard", "internal"]>>;
         }, "strip", z.ZodTypeAny, {
             status: string;
             condition: string;
+            kind?: "backend" | "guard" | "internal" | undefined;
             note?: string | undefined;
         }, {
             status: string;
             condition: string;
+            kind?: "backend" | "guard" | "internal" | undefined;
             note?: string | undefined;
         }>, "many">;
         failure_examples: z.ZodArray<z.ZodString, "many">;
+        request_example: z.ZodOptional<z.ZodString>;
+        success_response_example: z.ZodOptional<z.ZodString>;
+        failure_response_example: z.ZodOptional<z.ZodString>;
+        side: z.ZodOptional<z.ZodEnum<["console", "worker", "internal"]>>;
+        consumers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        producers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     }, "strip", z.ZodTypeAny, {
         path: string;
         id: string;
@@ -281,6 +325,7 @@ export declare const EntitiesSchema: z.ZodObject<{
         errors: {
             status: string;
             condition: string;
+            kind?: "backend" | "guard" | "internal" | undefined;
             note?: string | undefined;
         }[];
         method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -299,6 +344,12 @@ export declare const EntitiesSchema: z.ZodObject<{
             default?: string | undefined;
             desc?: string | undefined;
         }[] | undefined;
+        request_example?: string | undefined;
+        success_response_example?: string | undefined;
+        failure_response_example?: string | undefined;
+        side?: "internal" | "console" | "worker" | undefined;
+        consumers?: string[] | undefined;
+        producers?: string[] | undefined;
     }, {
         path: string;
         id: string;
@@ -306,6 +357,7 @@ export declare const EntitiesSchema: z.ZodObject<{
         errors: {
             status: string;
             condition: string;
+            kind?: "backend" | "guard" | "internal" | undefined;
             note?: string | undefined;
         }[];
         method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -324,6 +376,12 @@ export declare const EntitiesSchema: z.ZodObject<{
             required?: boolean | undefined;
             desc?: string | undefined;
         }[] | undefined;
+        request_example?: string | undefined;
+        success_response_example?: string | undefined;
+        failure_response_example?: string | undefined;
+        side?: "internal" | "console" | "worker" | undefined;
+        consumers?: string[] | undefined;
+        producers?: string[] | undefined;
     }>, "many">>, {
         path: string;
         id: string;
@@ -331,6 +389,7 @@ export declare const EntitiesSchema: z.ZodObject<{
         errors: {
             status: string;
             condition: string;
+            kind?: "backend" | "guard" | "internal" | undefined;
             note?: string | undefined;
         }[];
         method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -349,6 +408,12 @@ export declare const EntitiesSchema: z.ZodObject<{
             default?: string | undefined;
             desc?: string | undefined;
         }[] | undefined;
+        request_example?: string | undefined;
+        success_response_example?: string | undefined;
+        failure_response_example?: string | undefined;
+        side?: "internal" | "console" | "worker" | undefined;
+        consumers?: string[] | undefined;
+        producers?: string[] | undefined;
     }[], {
         path: string;
         id: string;
@@ -356,6 +421,7 @@ export declare const EntitiesSchema: z.ZodObject<{
         errors: {
             status: string;
             condition: string;
+            kind?: "backend" | "guard" | "internal" | undefined;
             note?: string | undefined;
         }[];
         method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -374,6 +440,12 @@ export declare const EntitiesSchema: z.ZodObject<{
             required?: boolean | undefined;
             desc?: string | undefined;
         }[] | undefined;
+        request_example?: string | undefined;
+        success_response_example?: string | undefined;
+        failure_response_example?: string | undefined;
+        side?: "internal" | "console" | "worker" | undefined;
+        consumers?: string[] | undefined;
+        producers?: string[] | undefined;
     }[] | undefined>;
     tables: z.ZodEffects<z.ZodDefault<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -456,18 +528,28 @@ export declare const EntitiesSchema: z.ZodObject<{
     decisions: z.ZodEffects<z.ZodDefault<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         text: z.ZodString;
+        background: z.ZodOptional<z.ZodString>;
+        alternative: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         id: string;
         text: string;
+        background?: string | undefined;
+        alternative?: string | undefined;
     }, {
         id: string;
         text: string;
+        background?: string | undefined;
+        alternative?: string | undefined;
     }>, "many">>, {
         id: string;
         text: string;
+        background?: string | undefined;
+        alternative?: string | undefined;
     }[], {
         id: string;
         text: string;
+        background?: string | undefined;
+        alternative?: string | undefined;
     }[] | undefined>;
 }, "strip", z.ZodTypeAny, {
     interfaces: {
@@ -477,6 +559,7 @@ export declare const EntitiesSchema: z.ZodObject<{
         errors: {
             status: string;
             condition: string;
+            kind?: "backend" | "guard" | "internal" | undefined;
             note?: string | undefined;
         }[];
         method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -495,6 +578,12 @@ export declare const EntitiesSchema: z.ZodObject<{
             default?: string | undefined;
             desc?: string | undefined;
         }[] | undefined;
+        request_example?: string | undefined;
+        success_response_example?: string | undefined;
+        failure_response_example?: string | undefined;
+        side?: "internal" | "console" | "worker" | undefined;
+        consumers?: string[] | undefined;
+        producers?: string[] | undefined;
     }[];
     tables: {
         id: string;
@@ -513,6 +602,8 @@ export declare const EntitiesSchema: z.ZodObject<{
     decisions: {
         id: string;
         text: string;
+        background?: string | undefined;
+        alternative?: string | undefined;
     }[];
 }, {
     interfaces?: {
@@ -522,6 +613,7 @@ export declare const EntitiesSchema: z.ZodObject<{
         errors: {
             status: string;
             condition: string;
+            kind?: "backend" | "guard" | "internal" | undefined;
             note?: string | undefined;
         }[];
         method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -540,6 +632,12 @@ export declare const EntitiesSchema: z.ZodObject<{
             required?: boolean | undefined;
             desc?: string | undefined;
         }[] | undefined;
+        request_example?: string | undefined;
+        success_response_example?: string | undefined;
+        failure_response_example?: string | undefined;
+        side?: "internal" | "console" | "worker" | undefined;
+        consumers?: string[] | undefined;
+        producers?: string[] | undefined;
     }[] | undefined;
     tables?: {
         id: string;
@@ -558,6 +656,8 @@ export declare const EntitiesSchema: z.ZodObject<{
     decisions?: {
         id: string;
         text: string;
+        background?: string | undefined;
+        alternative?: string | undefined;
     }[] | undefined;
 }>;
 export type Entities = z.infer<typeof EntitiesSchema>;

package/dist/core/document/schemas.js

@@ -25,6 +25,8 @@ export const ErrorSpecSchema = z.object({
     condition: z.string().min(1),
     status: z.string().min(1),
     note: z.string().optional(),
+    /** 错误类别：backend=gRPC→HTTP 映射；guard=前端守卫行为；internal=Worker 内部语义（P5 拆分）。 */
+    kind: z.enum(['backend', 'guard', 'internal']).optional(),
 });
 // ============= Contract entities =============
 export const InterfaceEntitySchema = z.object({
@@ -36,6 +38,13 @@ export const InterfaceEntitySchema = z.object({
     response_fields: z.array(FieldSchema).optional(),
     errors: z.array(ErrorSpecSchema).min(1), // G2: errors required
     failure_examples: z.array(z.string()).min(1), // G2 hard gate
+    // 整体性文档扩展（P3/P4/P11）：真实示例 body + 契约面与消费方/生产方（契约单一定义）。
+    request_example: z.string().optional(), // JSON body（无请求体方法省略或标注"无请求体"）
+    success_response_example: z.string().optional(),
+    failure_response_example: z.string().optional(),
+    side: z.enum(['console', 'worker', 'internal']).optional(),
+    consumers: z.array(z.string()).optional(), // 消费方仓
+    producers: z.array(z.string()).optional(), // 生产方仓
 });
 export const TableEntitySchema = z.object({
     id: z.string().trim().min(1), // stable id, e.g. "T1"
@@ -47,7 +56,9 @@ export const TableEntitySchema = z.object({
 });
 export const DecisionEntitySchema = z.object({
     id: z.string().trim().min(1), // e.g. "D1"
-    text: z.string().min(1),
+    text: z.string().min(1), // 结论
+    background: z.string().optional(), // ADR 背景（P6：决策前移为独立章节）
+    alternative: z.string().optional(), // 备选（已否决）
 });
 export const EntitiesSchema = z.object({
     interfaces: nullish(z.array(InterfaceEntitySchema).default([])),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gordon.gan/specflow",
-  "version": "1.8.2-beta",
+  "version": "1.8.4-beta",
   "type": "module",
   "description": "SpecFlow — unified spec-driven development: OpenSpec planning + Superpowers execution in one CLI and cross-IDE workflow",
   "keywords": [

package/prompts/document/map/api-design.md

@@ -1,4 +1,4 @@
-# 章节填充：api-design（接口设计 · 契约 + 前端对接）
+# 章节填充：api-design（接口与数据设计 · 契约 + 数据模型 + 前端对接）
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
 - kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
@@ -7,20 +7,36 @@
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
 - **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
 
+## 本章定位：接口与数据整合呈现（P11）
+
+本章同时承载**接口契约**与**数据模型**，二者不得游离：
+
+1. 固定顺序：接口总览（含面/消费方/生产方）→ 请求字段表 → 请求示例 → 响应字段表 → 响应示例 → 失败示例 → 错误表（按类别）→ **数据流总览与契约-表映射**（每接口 ↔ 读写表/列）→ 表结构与 DDL → 存量填充（G3）→ 回滚兼容（G4）。
+2. **契约-表映射表（强制）**：每个接口一行，列 = 契约 / 读写 / 表·列 / 关键说明。例：`step-results → 写 scenario_step_results（幂等键 execution_job_uid+step_order）`。契约字段与表列必须对得上，禁止接口讲接口、表讲表。
+3. DDL 就近：表结构在本章给出说明，完整 CREATE TABLE 可放附录并交叉引用（零 DDL 迭代必须显式声明「零迁移」，并展示现网 DDL 参考，禁止假装不涉及数据库）。
+4. **跨仓合成（≥2 仓）**：接口**单一定义**——同一 method+path 只定义一个实体，用 `side`（console/worker/internal）与 `consumers`/`producers`（仓名）标注；`<repo>_<id>` 仅作追溯别名，禁止按仓重复。仓归属用 `[repo]` 内联标注或表格「归属」列。
+
 ## 接口章节硬规则（借鉴 approval api-guidance + F1/F2 前端对接合并）
 
 1. **分层契约，禁止混层**：每个契约面对应一个独立 `In`（L2 Worker HTTP / L3 RPC+HTTP / L4 客户端 RPC），禁止「内部经 I7 一行代替 L4 详设」。
 2. **RPC / 服务名冻结**：禁止「暂定 / 如 Xxx / 实现时命名」；给出冻结的 RPC 名 + proto 字段号 + http_path。
 3. **proto 最小集**：新接口尽量给出可生成的 Proto 草案（rpc 名 / message / field 编号 / google.api.http）。
 4. **G2 失败示例（强制）**：清单中每个接口（含「不变」）除成功示例外，必须 ≥1 组失败示例（参数校验失败/租约过期/未认证），附完整 HTTP 或等价示例。只有错误码表不合格。
-5. **固定顺序**：元信息 → 请求体字段（或路径/Query/CLI flags）→ 请求示例 → 成功响应字段 → 响应示例(成功) → 响应示例(失败)(G2) → 错误表 →（可选）处理顺序。
+5. **固定顺序**：元信息（面/消费方/生产方）→ **请求字段表** → **请求示例（真实 JSON body，禁止空壳；无请求体方法显式标注「无请求体」）** → **响应字段表** → **成功响应示例（真实 JSON）** → **失败示例（G2，可附失败响应 body）** → **错误表（backend/guard/internal 分类）**。
 6. **接口清单稳定编号**：`In` 稳定，供页面引用与跨章交叉引用。
+7. **契约-表映射**：见上文「本章定位」第 2 条，接口清单后紧跟映射表。
+
+## 数据模型硬规则（G3/G4）
+
+8. 每张表必须有完整 CREATE TABLE（含 ENGINE/CHARSET）与字段说明。
+9. JSON/新列必须有存量填充策略（G3）；必须有回滚数据兼容说明（G4）。
+10. 零 DDL 迭代仍须展示现网 DDL（禁止假装不涉及数据库），并显式声明「零迁移」。
 
 ## 前端对接维度（O5–O7，F1 §2.2 合并「契约+对接」）
 
-7. **前端请求封装**：统一请求层（拦截器：token 注入/统一错误处理/超时/重试策略/缓存），DTO → VO 映射层。禁止「每个页面自己 fetch + 自己处理错误」。
-8. **前端错误处理统一**：后端错误码 → 前端统一错误态映射（Loading-Empty-Error），禁止前后端各写一套错误码约定。
-9. **接口 Mock 与契约先行**：前端并行开发用 Mock，Mock 的数据结构必须与冻结契约一致（R5）；联调时切换真实接口不改变前端代码结构。
-10. **优先级**：项目约定 + 现网 OpenAPI/proto > SpecFlow 骨架 > LLM。
+11. **前端请求封装**：统一请求层（拦截器：token 注入/统一错误处理/超时/重试策略/缓存），DTO → VO 映射层。禁止「每个页面自己 fetch + 自己处理错误」。
+12. **前端错误处理统一**：后端错误码 → 前端统一错误态映射（Loading-Empty-Error），禁止前后端各写一套错误码约定。
+13. **接口 Mock 与契约先行**：前端并行开发用 Mock，Mock 的数据结构必须与冻结契约一致（R5）；联调时切换真实接口不改变前端代码结构。
+14. **优先级**：项目约定 + 现网 OpenAPI/proto > SpecFlow 骨架 > LLM。
 
 > 前后端契约一致性是本章最高门禁：字段名、错误码、DTO 结构前后端必须对齐，禁止各写各的。

package/prompts/document/map/component-design.md

@@ -27,4 +27,6 @@
 
 6. **禁臆造组件树（README §1.1）**：组件树必须能追溯到页面/路由清单与设计输入；不存在于输入或推断来源的页面树禁止臆造。
 
+7. **只列真实存在的组件（跨仓整体性，P1）**：只列出实际存在的组件/模块（前端组件树、后端逻辑模块、Worker 模块），每个标注归属仓（如 `[web]`/`[talos]`）；**某仓在某维度没有内容就不出现**（禁止「某仓无 UI」「某仓无组件」类占位小节）。
+
 > 优先级：项目约定 > SpecFlow guidance > LLM。项目禁令不得被通用规则覆盖。

package/prompts/document/map/core-flow.md

@@ -8,7 +8,10 @@
 
 ## 时序图硬规则（README §1.7 架构图规范 + seqdiagram 精神）
 
-1. **必须有图**：主链路时序图用 Mermaid `sequenceDiagram` 源码块（diagram as code，可进 git/diff）。禁止用文字描述代替图，也禁止贴图片。
+1. **必须有图（≥2 张，P12）**：
+   - **整体流程图**：Mermaid `flowchart` 源码块，覆盖「编排 → 编译 → 入队 → 执行 → 上报 → 展示」全链路，**含失败分支**（编译失败不写库 / 执行失败 / 上报失败 abort）。
+   - **主链路时序图**：Mermaid `sequenceDiagram` 源码块（diagram as code，可进 git/diff）。禁止用文字描述代替图，也禁止贴图片。
+   - **失败路径决策图**：执行失败 vs 上报失败的分支单独成图（可并入整体流程图，但分支必须可见）。
 
 2. **必须有文字说明图（图 + 文成对）**：
    - 图前写一段「本图说明」：这条链路在讲什么、参与者（lifeline）分别是谁。

package/prompts/document/map/data-model.md

@@ -1,5 +1,7 @@
 # 章节填充：data-model（数据结构/数据模型变更）
 
+> **整合说明（P11）**：跨仓合成（≥2 仓）时，本章内容并入「接口与数据设计」章（api-design）——接口、数据模型与契约-表映射同章呈现，不单独成章。单仓文档可继续独立使用本章。无论哪种形态，**契约-表映射**（每接口 ↔ 读写表/列）都必须给出，禁止接口讲接口、表讲表。
+
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
 - kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
@@ -15,4 +17,5 @@
 4. **G3 存量填充**：JSON 形状变更或新增列时必须写存量默认值填充策略（回填 SQL/读时默认值/禁止空读/上线顺序）。
 5. **G4 回滚兼容**：回滚后旧版本能否安全跳过/忽略新数据？写明机制（omitempty/忽略未知键/version 分派）。禁止只写「回滚应用」。
 6. **零 DDL 迭代**：仍须展示现网 DDL，禁止假装「不涉及数据库」。
-7. **优先级**：项目约定 > SpecFlow guidance > LLM。项目禁令（如「本迭代禁止迁移」）不得被通用规则覆盖。
+7. **契约-表映射（强制）**：本章（或并入的接口与数据设计章）必须给出契约-表映射表——每个相关接口一行（契约 / 读写 / 表·列 / 关键说明），字段与列对齐。
+8. **优先级**：项目约定 > SpecFlow guidance > LLM。项目禁令（如「本迭代禁止迁移」）不得被通用规则覆盖。

package/prompts/document/outline/general.md

@@ -44,3 +44,9 @@
 5. **source_segments**：要点尽量标注来源段 id（来自全局摘要的段 id）。
 6. **每要点引用 ≤3 个实体**。
 7. **要点数量**：每章 2-5 个要点，覆盖该章必须覆盖的维度。
+8. **接口与数据整合（P11）**：当 `api-design` 与 `data-model` 同时被选中时，合并为单一「接口与数据设计」章（id 用 `api-design`），数据模型作为该章小节（数据流总览 → 契约-表映射 → 表结构/DDL → 存量填充 G3 → 回滚 G4），不再单列 `data-model` 章；DDL 可放附录并交叉引用。
+9. **完整性骨架（P7）**：涉及 ≥2 仓的合成文档必须含 `术语与约定`、`非目标汇总`、`风险与开放问题`、`决策记录（ADR）` 章节位（决策在正文用 `[D#]` 引用，先定义后引用）。
+10. **实体注册表增强**：接口实体注册时记录 `side`（console/worker/internal）、`consumers`、`producers`（仓名）；同一 method+path 只注册一个实体，`<repo>_<id>` 前缀仅作追溯别名（防 `duplicate_contract`）。
+11. **主流程含图（P12）**：`core-flow` 章必须输出整体流程图（含失败分支）+ 时序图 + 失败路径决策图，图必须有文字说明。
+12. **文档头与目录**：最终文档由引擎确定性渲染元信息头（标题/参与仓/生成时间）与目录；大纲只决定章节序与要点，不写文档头。
+13. **契约质量**：接口要点要求示例带真实 JSON body（`request_example`/`success_response_example`/`failure_response_example`）、请求/响应字段分列、错误表按 backend/guard/internal 分类。

package/prompts/document/shared/grounding.md

@@ -82,3 +82,10 @@ OpenAPI（`openapi.yaml`/`swagger.json` 等）、proto3（`*.proto`）、SQL DDL
 - 组件/页面：组件名、路由路径、状态 store 名应来自工程；页面清单可与用户核对。
 - 性能：基准数值必须来自实测（或标注"待实测"），禁止编造 LCP/包体数字。
 - 依赖升级：当前版本/目标版本来自 package.json；升级理由与收益向用户确认。
+
+## 七、整体性文档写作约定（P9/P11，所有章节通用）
+
+1. **首次定义、后续引用**：术语、决策（`[D#]`）、关键事实（幂等键、零 DDL、禁直连等）只在首次出现处定义，后续一律引用，禁止跨章重复整段（防 P9 重复）。
+2. **接口与数据同源**：接口字段与表列来自同一工程数据源；写契约-表映射时，字段↔列必须一一对齐，禁止接口讲接口、表讲表（P11）。
+3. **主流程必有图**：涉及多步流程的章节（core-flow 等）必须给出 mermaid 图（整体流程图/时序图），图必须有文字说明（P12）。
+4. **某仓无内容则不出现**：跨仓写作时，某仓在某维度无内容（如后端无 UI 组件）就**不写该仓的占位小节**，只写真实存在的内容（防"无 X"占位）。

package/skills/specflow-techdoc-synth/SKILL.md

@@ -47,18 +47,18 @@ Cursor: `specflow:techdoc-synth run ...`; Codex: `$specflow-techdoc-synth run ..
    - 无 `--text` → **回退 `approve`**（原合成默认，不打断流程，保持向后兼容）。
 5. 可选：`specflow techdoc detect --text "..."` 查看确定性关键词识别的结果作为参考。
 
-> 场景识别决定合成文档的**章节结构**（如 bugfix → reproduce/root-cause/fix；feature → requirement/test-strategy；poc → research/poc-demo/benchmark/tech-selection；migration → compat-migration/migration-guide）。跨仓合成规则（统一大纲/命名空间/分仓小节/全局视角/跨仓依赖）对任何 profile 都适用。
+> 场景识别决定合成文档的**章节结构**（如 bugfix → reproduce/root-cause/fix；feature → requirement/test-strategy；poc → research/poc-demo/benchmark/tech-selection；migration → compat-migration/migration-guide）。跨仓合成规则（统一大纲/契约单一定义/整体性组织/全局视角/跨仓依赖）对任何 profile 都适用。
 
 ## 与 `techdoc approve --bundle` 的区别（为什么用 synth）
 
 | 维度 | `approve --bundle`（拼接） | `techdoc-synth`（合成） |
 |---|---|---|
 | 大纲 | 每仓独立 | **一次统一大纲**，章节覆盖所有仓 |
-| 契约实体 | 每仓独立 I1/T1，跨仓冲突 | **命名空间隔离**（`<repo>_<id>`） |
-| 章节内容 | 各仓各写各的 | **每章按仓分节**（`### <repo>`），细节不互相稀释 |
+| 契约实体 | 每仓独立 I1/T1，跨仓冲突 | **单一定义 + 追溯别名**（`<repo>_<id>`），同一端点不重复 |
+| 章节内容 | 各仓各写各的 | **整体性叙述**（仓归属用 `[repo]` 标注），某仓无内容则不出现 |
 | 全局视角 | 无 | goal 写多仓总目标；closed-loop/implementability 跨仓统一结论 |
 | 跨仓依赖 | 不识别 | 显式标注「跨仓依赖」（接口调用/数据共享/发布顺序） |
-| 质量门禁 | 无 | **分仓小节门禁**（validate 强制：每必选章含所有仓的 `### <repo>` 小节） |
+| 质量门禁 | 无 | **整体性门禁**（validate 强制：全文仓覆盖 `repo_coverage_missing` + 空壳小节 `repo_section_stub` + 契约质量 lint） |
 
 > 原有多仓多产物（`techdoc approve --workspace-root ... --bundle` 各仓独立文档 + 主仓合订）**保持不变**；`techdoc-synth` 是新增的"真正合成"路径，两者并存。
 
@@ -96,17 +96,20 @@ run [--workspace-root <root>]
 ## 跨仓合成规则（必须遵守，validate 强制）
 
 1. **统一大纲**：一次生成一份 outline，章节覆盖所有仓，**不按仓分章**（跨仓对比/汇总放进对应章节）。
-2. **契约实体命名空间**：跨仓实体 id 用 `<repo>_<id>` 前缀（如 `repo1_I1`、`repo2_T1`），**禁止不同仓共用裸 id**。
-3. **每章必须分仓小节（质量门禁）**：每个必选章节的叙述按仓分节，用 `### <repo>` 小节标题（可带后缀如 `### repo1 · 目标`），且**每个仓都必须出现**。禁止把多仓内容混写成一段（会导致细节互相稀释）。
-4. **全局视角**（若所选 profile 包含对应章节）：goal 写多仓总目标与边界；tech-selection 对比各仓技术方案；api-design/data-model 分仓列契约；closed-loop 跨仓统一闭环检查；implementability 跨仓统一可实施性评估。其他场景章节（如 reproduce/root-cause/fix、requirement/test-strategy、research/poc-demo/benchmark）同样按仓分节并给出跨仓结论。
+2. **契约单一定义**：同一物理端点（method+path）只定义一个实体，用 `side`（console/worker/internal）与 `consumers`/`producers`（仓名）标注面与消费方/生产方；`<repo>_<id>` 前缀仅作**追溯别名**，禁止不同仓重复定义同一接口（validate 以 `duplicate_contract` 拦截）。
+3. **整体性组织（替代按仓分节）**：每章按主题写成一段整体叙述，仓归属用内联 `[repo]` 标注或表格「归属」列；**禁止**为无内容的仓写占位小节（如「某仓无 UI」，validate 以 `repo_section_stub` 拦截）；validate 以全文级 `repo_coverage_missing` 防某仓被概括掉。
+4. **全局视角**（若所选 profile 包含对应章节）：goal 写多仓总目标与边界；tech-selection 对比各仓技术方案；**接口与数据合并为「接口与数据设计」章**（含契约-表映射表：每接口 ↔ 读写表/列）；closed-loop 跨仓统一闭环检查；implementability 跨仓统一可实施性评估。其他场景章节（如 reproduce/root-cause/fix、requirement/test-strategy、research/poc-demo/benchmark）同样给出跨仓结论。
 5. **跨仓依赖/风险**：涉及仓间依赖（接口调用/数据共享/发布顺序）时显式标注「跨仓依赖」。
+6. **完整性骨架**：合成文档必须含术语与约定表、非目标汇总、风险与开放问题、决策记录（ADR，正文用 `[D#]` 引用且先定义后引用）。
+7. **契约质量**：接口示例带真实 JSON body（空壳示例拦截）、请求/响应字段分列、错误表按 backend/guard/internal 分类。
+8. **主流程必须含图**：主业务流程章输出整体流程图（含失败分支）+ 时序图 + 失败路径决策图。
 
-> 门禁是确定性的：`synthesize` 在 workRoot 写入 `repos.json`，`document validate` 读取后对每个必选章节检查 `### <repo>` 小节，缺失 → error（`repo_section_missing`）。非 synthesize 工作目录（`document run` / `approve --bundle`）不写 repos.json，门禁不触发。
+> 门禁是确定性的：`synthesize` 在 workRoot 写入 `repos.json`，`document validate` 读取后执行**整体性组织门禁**（全文级仓覆盖 `repo_coverage_missing` + 空壳小节 `repo_section_stub`）与契约质量 lint（`duplicate_contract`/`request_example_missing`/`response_example_missing`/`data_contract_mapping_missing`/`forward_decision_ref`）。非 synthesize 工作目录（`document run` / `approve --bundle`）不写 repos.json，跨仓门禁不触发。
 
 ## 产物
 
 - `<workspaceRoot>/.specflow/document-synthesized/document.md`（可用 `--work-root` 指定输出目录）
-- `repos.json`：参与合成的仓清单（门禁依据，自动写入）
+- `repos.json`：参与合成的仓清单（整体性门禁依据，自动写入）
 
 ## 说明
 

package/templates/document/chapters/api-design.yaml

@@ -1,29 +1,50 @@
-# 接口设计（候选；依赖架构；0→1 全栈/功能场景合并「契约+前端对接」）
+# 接口与数据设计（候选；依赖架构）
+# 整合呈现：接口契约（分层契约 + 前端对接）与数据模型（DDL/G3/G4）同章，含契约-表映射表。
+# 跨仓合成时遵循 buildSynthRules：接口单一定义（side/consumers/producers）、字段表请求/响应分列、
+# 示例带真实 JSON body、错误表按 backend/guard/internal 分类。
 id: api-design
-title: 接口设计
-when: input.containsApiChange
+title: 接口与数据设计
+when: input.containsApiChange || input.hasPersistence
 depends_on: [architecture]
 outline_points:
-  - { id: O1, text: 接口总览与调用方/鉴权, required: true, kind: narrative }
-  - { id: O2, text: 逐接口字段表 + 成功示例, required: true, kind: mixed }
+  - { id: O1, text: 接口总览与调用方/鉴权（含面/消费方/生产方）, required: true, kind: narrative }
+  - { id: O2, text: 逐接口请求/响应字段表分列 + 请求/成功响应示例（真实 JSON body）, required: true, kind: mixed }
   - { id: O3, text: 每个接口 ≥1 失败示例（G2）, required: true, kind: entity }
-  - { id: O4, text: 错误码映射, required: true, kind: entity }
+  - { id: O4, text: 错误码映射（backend/guard/internal 分类）, required: true, kind: entity }
   - { id: O5, text: 前端请求封装（拦截器/重试/缓存/DTO→VO）, required: false, kind: narrative }
   - { id: O6, text: 前端错误处理（错误码统一/Loading-Empty-Error 状态）, required: false, kind: narrative }
   - { id: O7, text: 接口 Mock 与联调（Mock 策略/契约先行，前端可并行开发）, required: false, kind: narrative }
+  - { id: DM1, text: 数据流总览与契约-表映射（每接口 ↔ 读写表/列）, required: true, kind: mixed }
+  - { id: DM2, text: 表结构与 DDL（既有表参考标注）, required: true, kind: entity }
+  - { id: DM3, text: 字段说明 + 本迭代用法, required: true, kind: entity }
+  - { id: DM4, text: 存量填充策略（G3）, required: true, kind: narrative }
+  - { id: DM5, text: 回滚数据兼容（G4）, required: true, kind: narrative }
 entities:
   interfaces:
     required: [id, name, method, path, errors]
     each:
       failure_example: required
       errors_table: required
+      request_example: required
+      success_response_example: required
+  tables:
+    required: [id, name, ddl]
+    each:
+      migration: required
+      rollback: required
 narratives:
   design_notes: required
 gates:
   - 禁止「暂定/如/实现时」接口名
   - 每个接口必须 ≥1 失败示例
   - 接口编号稳定可交叉引用
+  - 请求字段与响应字段分列（禁止混成一张表）
+  - POST/PUT/PATCH 必须给真实 JSON 请求示例（无请求体显式标注「无请求体」）；有响应字段必须有成功响应示例
+  - 错误表按 backend（gRPC→HTTP 映射）/ guard（前端守卫行为）/ internal（Worker 内部语义）分类
   - 涉及前端对接时，请求封装与错误码统一方案必须与契约对齐（R5，字段名/错误码禁各写各的）
   - 前端接口 Mock 必须与契约一致（禁 Mock 一套、真实接口另一套）
+  - 有表实体时必须给出「契约-表映射」（每接口 ↔ 读写表/列）
+  - 每张表必须有完整 CREATE TABLE（含 ENGINE/CHARSET）；零 DDL 迭代仍须展示现网 DDL（禁止假装不涉及数据库）
+  - JSON/新列必须有存量填充策略（G3）；必须有回滚数据兼容说明（G4）
 map_prompt: prompts/document/map/api-design.md
-output_budget_tokens: 8000
+output_budget_tokens: 12000

package/templates/document/chapters/core-flow.yaml

@@ -18,6 +18,8 @@ narratives:
   core_flow: required
 gates:
   - 主链路时序图必须 Mermaid 源码（```mermaid sequenceDiagram）+ 可渲染（diagram as code）
+  - 必须含整体流程图（```mermaid flowchart，覆盖编排→编译→入队→执行→上报→展示，含失败分支）
+  - 失败路径/决策部分必须单独成图（执行失败 vs 上报失败分支）
   - 时序图必须有文字说明（逐消息/逐分支），禁止只有图无文字
   - 每条主链路必须画异常/失败分支（禁只画 happy path）
   - 有写操作的链路必须给幂等/并发结论（禁「前端按钮防抖」当幂等方案）