@gordon.gan/specflow 1.8.3-beta → 1.8.5-beta

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 [
@@ -70,28 +83,36 @@ export function renderTable(t) {
         ...(t.rollback ? ['**回滚兼容**', '', t.rollback, ''] : []),
     ].join('\n');
 }
-export function renderDecisions(decisions) {
-    if (decisions.length === 0)
-        return '';
-    return [
-        '**决策记录**',
-        '',
-        '| 决策 | 结论 |',
-        '|------|------|',
-        ...decisions.map((d) => `| ${escapeTableCell(d.id)} | ${escapeTableCell(d.text)} |`),
-    ].join('\n');
-}
 export function renderEntities(entities) {
+    return [renderInterfaces(entities.interfaces), renderTables(entities.tables)].filter(Boolean).join('\n\n');
+}
+/** 契约实体按「面」分组渲染（Console 面 / 内部与 Worker 面），供接口与数据设计章就地展开。 */
+export function renderInterfaces(interfaces) {
     const parts = [];
-    for (const i of entities.interfaces)
-        parts.push(renderInterface(i));
-    for (const t of entities.tables)
-        parts.push(renderTable(t));
-    const decisionsMd = renderDecisions(entities.decisions);
-    if (decisionsMd)
-        parts.push(decisionsMd);
+    const groups = new Map();
+    for (const i of 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'));
+    }
     return parts.join('\n\n');
 }
+export function renderTables(tables) {
+    return tables.map(renderTable).join('\n\n');
+}
 /** 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
  *  internal fix notes. */
@@ -179,30 +200,56 @@ export function demoteHeadings(text, levels = 1) {
     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)}`, ''];
+    // 文档头元信息（P7）：确定性渲染，不依赖 LLM。
+    const meta = [];
+    if (repos && repos.length > 0)
+        meta.push(`| 参与仓 | ${repos.map(escapeTableCell).join('、')} |`);
+    if (meta.length > 0) {
+        body.push('| 项 | 值 |', '|------|------|', ...meta, '');
+    }
+    // 目录（P7）：按大纲章节序确定性生成。
+    body.push('## 目录', '');
+    let tocNo = 0;
+    outline.chapters.forEach((ch) => {
+        tocNo += 1;
+        body.push(`${tocNo}. ${escapeInline(ch.title)}`);
+    });
+    body.push('');
+    // 契约明细按章节组件落位：
+    //  - 接口实体（请求/响应字段表、示例、错误表）内联进「接口与数据设计」章（接口明细）；
+    //  - 数据库表（DDL/存量填充/回滚）必须由「数据模型」章组件承载（数据表），不并入接口章。
+    const interfacesMd = renderInterfaces(entities.interfaces);
+    const tablesMd = renderTables(entities.tables);
+    const hasApiDesign = outline.chapters.some((c) => c.id === 'api-design');
+    const hasDataModel = outline.chapters.some((c) => c.id === 'data-model');
     for (const ch of outline.chapters) {
         body.push(`## ${escapeInline(ch.title)}`, '');
         // 依次净化：剥内嵌契约 JSON 块（机器中间格式）→ 剥与章节标题重复的首行 H1 → 剥引擎修复注记，
-        // 再把叙述内标题降级一级（章节头已占 H2，叙述小节 H2→H3、分仓 H3→H4），保证目录层级正确。
+        // 再把叙述内标题降级一级（章节头已占 H2，叙述小节 H2→H3），保证目录层级正确。
         const narrative = demoteHeadings(stripLeadingTitle(stripEntityJsonBlocks(stripReviewNotes(narratives.get(ch.id) ?? '')), ch.title));
         if (narrative.trim())
             body.push(narrative.trim(), '');
+        if (ch.id === 'api-design' && interfacesMd.trim())
+            body.push('### 接口明细', '', interfacesMd, '');
+        if (ch.id === 'data-model' && tablesMd.trim())
+            body.push('### 数据表', '', tablesMd, '');
     }
-    // Contract entities: append to the chapters that reference them (simplified: append in a
-    // final "契约" section, since entities are cross-chapter).
-    const contractMd = renderEntities(entities);
-    if (contractMd.trim()) {
-        body.push('---', '', '## 契约实体', '', contractMd, '');
+    // 无 api-design / data-model 章时的兜底（如 bugfix 等 profile 的契约实体仍须呈现）。
+    if (!hasApiDesign && !hasDataModel && (interfacesMd.trim() || tablesMd.trim())) {
+        body.push('---', '', '## 附录 A：契约实体明细', '', [interfacesMd, tablesMd].filter(Boolean).join('\n\n'), '');
     }
-    // 产物溯源附录 (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.3-beta",
+  "version": "1.8.5-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,19 +1,27 @@
-# 章节填充：api-design（接口设计 · 契约 + 前端对接）
+# 章节填充：api-design（接口与数据设计 · 接口契约 + 前端对接）
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
 - kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
-- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.；**正文中文化**；**叙述分条 + 图文结合**）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
 - **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
 
+## 本章定位：接口契约承载（P11/P13）
+
+本章承载**接口契约**（渲染为「接口明细」），与「数据模型」章分工：
+
+1. 固定顺序：接口总览（含面/消费方/生产方）→ 请求字段表 → 请求示例 → 响应字段表 → 响应示例 → 失败示例 → 错误表（按类别）。
+2. **数据库表不由本章承载**：表结构与 DDL、存量填充（G3）、回滚兼容（G4）、**契约-表映射**全部由「数据模型」章给出；本章在涉及表实体时给一句指引（如"契约-表映射见数据模型章"），**不**在本章写建表语句。
+3. **跨仓合成（≥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` 稳定，供页面引用与跨章交叉引用。
 
 ## 前端对接维度（O5–O7，F1 §2.2 合并「契约+对接」）

package/prompts/document/map/architecture.md

@@ -18,7 +18,7 @@
 
 3. **C4 分层（AR4）**：按需给 Context（系统上下文，外部系统/用户）/ Container（可部署单元：Web/API/DB/消息）/ Component（模块组件）分层；每层给依赖方向。与 core-flow 的组件层交互时序对接（R5，交叉引用冻结 id）。
 
-4. **ADR 决策记录（AR5）**：把 tech-selection 的关键决策沉淀为 ADR——背景 / 决策 / 后果 / 备选（为什么不用备选）。引用 tech-selection 的 decisions 实体 id，不另起名。
+4. **决策理由就地沉淀（AR5，可读性整改）**：关键取舍（如"为什么不用备选方案"）写在技术选型章的否决/备选列与风险章的缓解列，**不设独立的 ADR/决策记录章节**。
 
 5. **架构一致性自检（AR3）**：对照目标（可扩展/可维护/性能），检查架构是否满足，给出自检结论。
 

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/core-logic.md

@@ -1,9 +1,16 @@
-# 章节填充：core-logic
+# 章节填充：core-logic（关键实现规则）
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
-- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
-- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.；**正文中文化**）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
 - **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
 - 涉及项目规约/DB/API/前端约束时，遵循「项目约定 > SpecFlow guidance > LLM」优先级
+
+## 关键实现规则章节硬规则（可读性整改：承接主流程、只写图中未覆盖的规则）
+
+1. **开头必须承接上下文（禁孤立开头）**：第一段用一两句话说明"本章规则承接主业务流程（核心链路/失败分支），回答'每一步在实现上怎么落地'"。禁止直接从"校验 xxx"开始。
+2. **只写主流程图/时序图未覆盖的细节**：链路、失败分支、幂等并发已在主业务流程章画图并说明的，本章**不得整段重复**——重复内容改用交叉引用（如"失败分叉见主业务流程·失败路径决策图"）。
+3. **按环节分节**：编译规则（排序/展开/校验/信封冻结）→ 执行规则（信封校验/共享变量/失败策略细节）→ 上报规则（写入顺序/幂等键/abort 语义）。每节 1. 2. 3. 编号，一条一句。
+4. **正文中文化**：正文用中文业务术语（如「运行时信封」「步骤序号」「租约世代」），代码标识符只允许在术语表/字段表/示例中（见 artifact-language.md）。
+5. **位置**：本章属于主业务流程的"下一环节"——渲染时紧随主业务流程之后；若你发现本章内容 90% 以上已在别章讲过，则应大幅精简并只保留真正新增的规则。

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

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