@gordon.gan/specflow 1.4.0-beta → 1.4.2-beta

package/prompts/approval/generate.md

@@ -38,12 +38,15 @@ SKILL.md caller which are missing.
 ## Part A: Closed-Loop Verification (7 Passes)
 
 Each Pass examines cross-artifact or artifact-to-reality coherence from one angle.
-Every Pass MUST produce:
+Every Pass MUST produce (for analysis / conversation):
 
 1. A **Verdict**: `PASS` | `WARNING` | `FAIL` | `SKIPPED`
-2. **Evidence**: concrete citations (file path, section heading, requirement/scenario name, task ID, or for Pass 6/7: actual code file + function/section)
+2. **Evidence**: concrete citations (keep brief; full matrices only when WARNING/FAIL)
 3. A brief **rationale** linking evidence to verdict
 
+**Document output (§8)**: collapse all 7 Passes into **one table** — see Part E §8.
+Do not paste per-Pass essays into `approval.md`.
+
 Verdict calibration:
 
 - `PASS` — no gaps found in this dimension.
@@ -99,7 +102,7 @@ testable? Are delta operations structurally complete?"
 5. RENAMED Requirements have `FROM:` and `TO:`. Missing is a `FAIL`.
 6. MODIFIED Requirements reference names that exist in the main specs baseline (if baseline exists). Mismatched name is a `FAIL`.
 7. Run `specflow validate` on each delta spec file. Any validation error is a `FAIL`.
-8. **Detailed-design coverage** (cross-check with §6 方案详细设计): every spec Requirement
+8. **Detailed-design coverage** (cross-check with §4 方案详细设计): every spec Requirement
    that involves data/interface/flow changes must have a corresponding detailed-design
    element. A Requirement whose implementation needs a data structure, interface, or state
    flow but has NO detailed-design element (or an element marked "待 refine 澄清") is a
@@ -331,6 +334,31 @@ The recommendation must include a 1-2 sentence rationale citing the specific ver
 Generate `approval.md` following this exact structure. Adapt narrative language to
 `artifacts.language`; keep protocol markers, IDs, paths, commands, and code in English.
 
+**Chapter order (implementer-first, aligned with scenario-job-compile readability)**:
+
+1. 绪论与边界 — proposal + optional explore + AI; absorbs What/Impact; **no 变更摘要 chapter**
+2. 技术方案评估 — decisions / risks / design quality
+3. 架构整体设计 — diagrams + **图要点说明** + components (before acceptance)
+4. 方案详细设计 — 设计要点 + Happy Path + 业务场景(+说明) + data/API/…
+5. 验收标准 — **after** architecture & detailed design
+6. 测试策略 → 7. 部署 → 8. 闭环 → 9. 可实施性 → 10. 审批
+
+### ⚠️ 质量红线 (Quality Gates) — 必须严格执行
+
+生成 `approval.md` 全文时下列红线**缺一不可**;违反则详细设计/接口/数据章节视为不合格,确认前必须补全。
+
+| # | 红线 | 要求 |
+|---|------|------|
+| G1 | 一图胜千言 | 任何超过 **5 行**的文字流程描述,**必须**改为 Mermaid 代码块(`sequenceDiagram` / `flowchart` / `stateDiagram-v2`),禁止长段落散文流程 |
+| G2 | 必须有「失败」示例 | §4.5 每个「新增/修改/行为扩展」接口:除成功请求/响应示例外,**必须**另附 ≥1 组**报错**请求或响应示例(如参数校验失败、租约过期、未认证);仅有错误码表、无 HTTP/正文示例 → 不合格 |
+| G3 | 必须有「数据迁移方案」 | 凡涉及 **JSON 字段形状变更**或**新增列**:必须写明**存量数据的默认值填充策略**(回填脚本 / 读时默认 / 禁止空读等);零 DDL 但改 JSON 语义同样适用 |
+| G4 | 必须有「回滚兼容」说明 | 若发布失败回滚:新代码已写入的数据,旧版代码是否能**安全跳过/忽略**?必须给出明确方案(如 `omitempty`、忽略未知字段、`schema_version` 分派、双写兼容窗口);禁止只写「回滚镜像」而无数据兼容结论 |
+
+### Style & Tone (文风要求) — 全文适用
+
+1. **通俗易懂**:面向要动手的开发同学;避免生僻英文缩写,**首次出现必须注解**(例:`DDL`(数据定义语言)、`RPC`(远程过程调用));协议字段名/路径/代码标识符保持原文。
+2. **逻辑严密**:拒绝模棱两可词 —— **禁止**使用「尽量」「大概」「一般情况下」「可能需要」「酌情」「视情况」等;应使用「**必须**」「**禁止**」「**采用 XX 方案**」「固定为…」。若确有分支,写成显式条件表(若 A → 做 X;若 B → 做 Y),不得用含糊副词搪塞。
+
 ```markdown
 # 技术方案审批文档: <change-name>
 
@@ -340,79 +368,99 @@ Generate `approval.md` following this exact structure. Adapt narrative language
 
 ---
 
-## 1. 变更概览 (Dashboard)
-
-| 维度 | 值 |
-|------|-----|
-| Change 名称 | <change-name> |
-| 创建日期 | <from .specflow.yaml created> |
-| 当前 phase | refined |
-| 技术栈 | <Node/TypeScript / Go / Python / Rust / unknown> |
-| Capability 数 | N (新增 X / 修改 Y) |
-| Requirement 数 | N |
-| Scenario 数 | N (功能可测试 A / 文档可测试 B / 不可测试 C) |
-| 任务总数 | N (已完成 X / 待实施 Y) |
-| Design 决策数 | N |
-| 识别风险数 | N |
-| 代码锚点文件数 | N (存在 M / 不存在 K / 新建 L) |
-| 基线 spec 数 | N (或 "无基线 — greenfield") |
-| 过度设计信号数 | N (0 = PASS / 1-2 = WARNING / 3+ = FAIL) |
-| 扩展性信号数 | N (4-5 = PASS / 0-3 = WARNING) |
-
-> 上述计数基于四件套文件 + 项目代码 + 主 specs 精确统计,非 AI 估算。
+## 1. 绪论与边界 (Introduction & Boundaries)
 
----
+> 本章以**业务叙事**说明"为什么做、做什么、影响面、做完后如何闭环、坚决不做什么"。
+> **数据来源**:`proposal.md`(必选)+ `explore.md`(若存在且可用则吸收)+ **AI 提炼**。
+> **不再单列「变更摘要」章**:原 Why / What Changes / Impact 并入本章 1.1–1.2。
 
-## 2. 变更摘要 (Executive Summary)
+### 1.1 背景与痛点 (Background & Pain Points)
 
-### 2.1 为什么做 (Why)
-[2-3 句话提炼 proposal.md 的 Why]
+用一段话说明当前现状,并用 **Mermaid 现状流程图** 直观呈现,痛点节点**用红色标注**。
 
-### 2.2 做什么 (What Changes)
-[按 新增/修改/移除/重命名 分类,标注 BREAKING]
+**要求**:
 
-### 2.3 影响面 (Impact)
-[整合 proposal.md Impact,AI 评估影响等级]
+1. 描述当前业务/系统的实际流程(用户如何完成目标、经过了哪些步骤)
+2. 用 Mermaid `flowchart` 绘制现状流程
+3. **痛点节点用红色标注**:`classDef pain fill:#ffcccc,stroke:#cc0000,color:#000` + `:::pain` 或 `class X pain`
+4. 每个痛点一句话说明**它造成的代价**(返工/延迟/错误/成本)
+5. 痛点应可追溯到 proposal.md 的 `## Why`;若有 `explore.md`,吸收其中已确认的痛点/约束洞察(勿编造)
 
----
+**痛点清单**(对应图中红色节点):
 
-## 3. 验收标准 (Acceptance Criteria)
+| 痛点 | 代价 |
+|------|------|
+| <痛点> | <代价> |
 
-[按 capability 分组,完整列出所有 Requirement + Scenario,每个 Scenario 3 级可测试性标注]
+### 1.2 做什么与影响面 (What & Impact)
 
-### 3.1 Capability: <name>
-[Delta 操作类型: ADDED / MODIFIED / REMOVED / RENAMED]
+AI 从 proposal `## What Changes` / `## Impact`(及 explore 相关结论)提炼,替代原「变更摘要」章。
 
-#### Requirement: <name>
-<描述>
+**做什么**(按 新增/修改/移除/重命名;BREAKING 显式标注):
 
-| Scenario | WHEN | THEN | 可测试性 | 说明 |
-|----------|------|------|---------|------|
-| <name> | <条件> | <期望> | ✅ 功能可测试 / ⚠️ 文档可测试 / ❌ 不可测试 | <原因 if ⚠️/❌> |
+| 类别 | 内容 | BREAKING? |
+|------|------|-----------|
+| 新增 | | |
+| 修改 | | |
+| 移除 / 重命名 | | |
+
+**影响面**:
+
+| 影响区域 | 影响等级 | 说明 |
+|---------|---------|------|
+| | 高/中/低 | |
+
+### 1.3 业务闭环与目标 (Business Loop & Goals)
+
+说明"本次变更完成后,业务如何形成闭环",并给出 **用户操作路径(User Journey)**。
+
+**要求**:
+
+1. 描述完成本次变更后,用户完成目标的完整路径
+2. 用 Mermaid `sequenceDiagram` 或 `flowchart` 绘制 User Journey
+3. 标注每一步的价值/产出
+4. Goals 应可验证,引用 **§5 验收标准**
+
+**业务目标**(可验证):
+
+| 目标 | 可验证方式(引用 §5) |
+|------|---------------------|
+| <目标> | §5 <Scenario 名> |
+
+### 1.4 非目标 (Non-Goals)
+
+**必须明确列出本次迭代坚决不做的事项,并说明不做理由**(防止需求蔓延)。
+
+1. 从 proposal.md / design.md / explore.md 的 Non-Goals 提炼,必须补充"不做理由"
+2. 若确实没有,写明 `proposal/design 未声明 Non-Goals,建议在 refine 补充边界`
+
+| 非目标 | 不做理由 |
+|--------|---------|
+| <非目标> | <理由> |
 
 ---
 
-## 4. 技术方案评估 (Technical Design Review)
+## 2. 技术方案评估 (Technical Design Review)
 
-### 4.1 现状与约束 (Context & Constraints)
+### 2.1 现状与约束 (Context & Constraints)
 [整合 design.md Context + AI 补充的隐含约束]
 
-### 4.2 目标与非目标 (Goals & Non-Goals)
+### 2.2 目标与非目标 (Goals & Non-Goals)
 [整合 design.md Goals/Non-Goals]
 
-### 4.3 决策评审表 (Decision Review)
+### 2.3 决策评审表 (Decision Review)
 
 | 决策 | 选定方案 | 备选方案 | 理由 | 影响评估 | 状态 |
 |------|---------|---------|------|---------|------|
 | D1: <name> | <方案> | <A/B> | <理由> | <评估> | Proposed |
 
-### 4.4 风险与权衡 (Risks & Trade-offs)
+### 2.4 风险与权衡 (Risks & Trade-offs)
 
 | 风险 | 严重等级 | 缓解措施 | 就绪度 |
 |------|---------|---------|--------|
 | <name> | 高/中/低 | <措施> | ✅/⚠️/❌ |
 
-### 4.5 设计质量评估 (Design Quality)
+### 2.5 设计质量评估 (Design Quality)
 
 #### 过度设计检查
 | # | 信号 | 检测到? | 证据(design/tasks 位置) |
@@ -438,192 +486,396 @@ Generate `approval.md` following this exact structure. Adapt narrative language
 
 ---
 
-## 5. 架构整体设计 (Architecture Design)
+
+## 3. 架构整体设计 (Architecture Design)
 
 > 本章回答"系统由哪些模块组成、模块间如何依赖与交互、每个模块的职责与边界是什么"。
-> 它聚焦**宏观结构**(模块图 + 交互图),与 §6 方案详细设计(模块内部实现)互补:
-> 架构讲"模块之间的关系",详细设计讲"模块内部怎么做"。
+> 聚焦**宏观结构**;与 §4 方案详细设计(模块内部实现 / 时序)互补。
+> 质量标杆:`scenario-job-compile` §3 —— **图 + 图要点说明 + 核心组件表**。
 
-### 5.1 总体架构 (Architecture Overview)
+### 3.1 总体架构 (Architecture Overview)
 
-用 Mermaid 图绘制 **系统交互图 或 模块依赖图**,直观呈现变更后的系统结构。
+用 Mermaid 绘制 **模块依赖/分层图**(推荐),并可附加 **系统交互总览**。
 
-**图型选择**:
+**绘制要求**:
 
-- **模块依赖图 / 分层架构图** — `mermaid flowchart LR`(模块为节点,依赖为边),展示新增/修改模块在整体中的位置
-- **系统交互图** — `mermaid sequenceDiagram`(参与者为模块/角色),展示变更涉及的模块间调用时序
+1. 标注变更模块(`[新增]` / `[修改]`),影响面一眼可见
+2. 边标注依赖方向或交互消息
+3. CLI/库 → `src/core/*`、`src/cli/*`;Web → 服务/组件;多仓 → 仓库/服务
+4. 图与 **§2 决策**一致
 
-**绘制要求**:
+**设计说明 / 图要点**(强制,紧跟每张架构图之后):
 
-1. 标注**变更涉及的模块**(用颜色/形状/标注 `[新增]` `[修改]` 区分),让评审者一眼看出本次变更影响面
-2. 边标注**依赖方向**(谁依赖谁)或**交互消息**(谁调用谁,传递什么)
-3. 对纯 CLI/库项目,模块 = 源码模块(`src/core/*`、`src/cli/*`);对 Web 项目,模块 = 服务/组件;对多仓,模块 = 仓库/服务
-4. 图应**与 §4 决策一致** —— 图上体现的结构必须能追溯到某个决策
+用编号列表解释图中**读图关键点**(不是复述节点名),对齐标杆「设计说明(总体架构)」:
 
-**示例(模块依赖图)**:
-```mermaid
-flowchart LR
-    subgraph CLI["CLI 层 (src/cli/)"]
-        INIT["init 命令 [修改]"]
-        CHANGE["change 命令"]
-        STORE["store 命令 [新增]"]
-    end
-    subgraph CORE["核心层 (src/core/)"]
-        CONFIG["project-config [修改]"]
-        ART["artifact-language [新增]"]
-        STORECORE["store/ [新增]"]
-        ROOT["root-selection [新增]"]
-    end
-    INIT --> CONFIG
-    INIT --> ART
-    STORE --> STORECORE
-    CHANGE --> ROOT
-    CONFIG --> ART
-```
+1. 分层/边界怎么划、谁不直连谁
+2. 本迭代不变式(如零 DDL、双通道、一场景一作业)
+3. 复用 vs 新增的落点
+4. 与 §2 决策的对应关系
+
+若有第二张交互图,另写 **交互要点**(一段或短列表):谁感知、谁禁止直连 DB/绕过网关等。
+
+### 3.2 核心组件说明 (Core Components)
+
+| 组件 | 职责 | 边界(做什么 / 不做什么) | 依赖 | 变更类型 |
+|------|------|-------------------------|------|---------|
+| `<组件名>` | 一句话职责 | 做什么;不做什么 | 依赖的组件 | 新增/修改/不变 |
+
+**填写要求**:列出新增+修改组件;边界写「不做什么」;与 §3.1 图一一对应;边界可追溯到 §2 决策。
+
+可附 **组件边界总原则**(短列表:平台/Worker/控制台各做什么、禁止什么)。
+
+**不涉及架构变更时写**:`不涉及架构变更(单模块/单文件调整,模块边界无变化)`。
+
+### 3.3 架构一致性自检(生成后检查)
+
+- [ ] §3.1 图标注了新增/修改模块
+- [ ] **每张架构图后有「设计说明 / 图要点」**(非空编号列表)
+- [ ] §3.2 每个组件有「不做什么」边界
+- [ ] 图与表一一对应
+- [ ] 组件边界可追溯到 §2 决策
+- [ ] 未涉及时显式标注「不涉及架构变更」
+
+---
+
+## 4. 方案详细设计 (Detailed Design)
+
+> 将方案从宏观决策落到实现者可照写的细节。
+> **只呈现本变更涉及的部分**;不涉及显式写「不涉及 X」。
+> 每个元素可追溯到 **§5 验收标准**与 **§2 决策**。
+> 质量标杆:`scenario-job-compile` §4 —— **设计要点一览 → 业务时序(含设计要点说明) → 表/接口**。
+
+### 4.1 设计要点一览(强制)
+
+从 design 决策提炼实现**不可随便推翻**的要点(P1…Pn):
+
+| 编号 | 要点 | 说明 |
+|------|------|------|
+| P1 | <短名> | <一句话不变量/策略> |
+
+### 4.2 核心业务时序 · Happy Path(强制)
+
+**必须**给出主成功路径的**完整** Mermaid `sequenceDiagram`(建议 `autonumber`),覆盖主角色从发起到成功终态的端到端调用;不得用一句话替代。
+
+**结构**:
+
+1. **目的**:一句话
+2. **时序图**:Happy Path 全链路
+3. **设计要点**:图后强制说明(不变式、与 P1…Pn 对应、本图不展开的失败边界)
 
-**示例(系统交互图)**:
 ```mermaid
 sequenceDiagram
-    participant U as User
-    participant C as CLI (init)
-    participant F as Filesystem
-    participant P as Parity check
-    U->>C: specflow init --artifact-language zh-CN
-    C->>F: 创建 specflow/{changes,specs}
-    C->>F: 写入 config.yaml (artifacts.language)
-    C->>F: 复制 IDE 资产
-    C->>P: parity 严格校验
-    P-->>C: ok / fail
-    C-->>U: status + message
+  autonumber
+  %% Happy Path — 成功路径完整时序
 ```
 
-### 5.2 核心组件说明 (Core Components)
+**设计要点**:
 
-用表格定义**每个模块/组件的职责与边界**。这是实现者判断"某逻辑该放哪个模块"的依据,也是评审者验证"模块边界是否清晰"的依据。
+- …
 
-| 组件 | 职责 | 边界(做什么 / 不做什么) | 依赖 | 变更类型 |
-|------|------|-------------------------|------|---------|
-| `<组件名>` | 一句话职责 | 做什么;不做什么(明确边界) | 依赖的组件 | 新增/修改/不变 |
+### 4.3 业务场景时序(强制有说明)
 
-**填写要求**:
+对每个关键业务场景输出同构小节(对齐标杆「业务流程 A/B/C…」):
 
-1. **列出变更涉及的所有组件**(新增 + 修改),并为每个标注职责、边界、依赖
-2. 边界要写"不做什么" —— 明确职责归属,防止实现时逻辑放错模块(如:CLI 不解析斜杠参数、核心层不做 AI 推理)
-3. 依赖方向要明确(谁依赖谁),避免循环依赖
-4. **与 §5.1 图一致**:每个表格组件应在图中出现
-5. 每个组件边界可追溯到 §4 决策(如 D1 选择"在 skill 层解释 --yes" → 边界"CLI 不解析斜杠参数")
+#### 场景 X · `<名称>`
 
-**示例**:
+1. **目的**
+2. **时序/状态/流程开**(Mermaid `sequenceDiagram` / `flowchart` / `stateDiagram-v2`)
+3. **设计要点**(强制 — 禁止有图无说明;可用列表或小表)
 
-| 组件 | 职责 | 边界 | 依赖 | 变更 |
-|------|------|------|------|------|
-| `src/core/artifact-language.ts` | 定义语言类型、别名规范化、指导渲染 | 只定义策略,不写文件;不做自然语言检测 | 无 | 新增 |
-| `src/cli/commands/init.ts` | 初始化项目、写入 config、调用资产生成 | 只写新配置;不覆盖已有 config;不做 AI 推理 | project-config, artifact-language | 修改 |
-| `src/core/project-config.ts` | 解析 config.yaml,产出诊断 | 只解析,不校验 IDE 资产;错误恢复为默认值 | artifact-language | 修改 |
+至少覆盖本变更的核心分支(如失败策略、幂等、兼容缺省、计划 vs 调试等)。纯单步无分支时可写:`不涉及多业务场景(主路径已由 §4.2 Happy Path 覆盖)`——但仍须保留 §4.2。
 
-**不涉及架构变更时写**:`不涉及架构变更(单模块/单文件调整,模块边界无变化)`。
+### 4.4 数据结构 / 数据模型变更 (Data Structures)
 
-### 5.3 架构一致性自检(生成后检查)
+**适用范围**:涉及持久化、状态存储、数据模型的变更。纯 CLI/库项目若无数据库,覆盖配置结构 / 状态文件 / 缓存结构 / YAML schema 等"数据模型"(走下方「非库表路径」)。
 
-- [ ] §5.1 图标注了新增/修改模块,评审者一眼看出影响面
-- [ ] §5.2 每个组件有"不做什么"的边界,避免逻辑放错模块
-- [ ] §5.1 与 §5.2 一一对应(图中有,表中有;表中依赖与图边一致)
-- [ ] 组件边界可追溯到 §4 决策
-- [ ] 未涉及架构变更时显式标注"不涉及架构变更"
+> **DB 技能路由(先于起草)**:执行 `prompts/approval/database-guidance.md`。  
+> - **命中** `mysql` / `postgresql` / `oracle`(及确需时的 redis/es):`Read`  
+>   `skills/database/<stack>/SKILL.md` 与路由表中的 DDL/索引/JSON 参考,用其惯例补强类型、引擎、字符集、索引与 Gotchas。  
+> - **未命中**(`dbStack=none`):不硬套某厂商 skill,**交给大模型**按下方 SpecFlow 硬门槛生成。  
+> - 技能是 **Read 知识包**,不是 MCP tool;不得用「调 tool」替代读文件。  
+> - 在总则「DDL 来源」旁注明:`skills/database/<stack>`(本地) 或 `LLM-fallback`。
 
----
+> **质量硬门槛(库表路径)**:只要本变更读写/依赖任何数据库表(含"零 DDL、只改读写语义"),§4.4 **必须**按下列结构输出,不得用一句话带过、不得省略 ER / DDL / 字段说明表。参考质量标杆:`scenario-job-compile` 类审批文档的「表与数据设计」章(总则结论表 → ER → 表一览 → 逐表 DDL+字段表 → 非表字段与回滚)。
 
-## 6. 方案详细设计 (Detailed Design)
+> **大纲 / 标题层级(硬门槛 — 防 TOC 爆炸)**:Markdown 预览大纲**只允许**下列标题进入目录;「DDL」「字段说明」「JSON 形状」等**禁止**写成 `####`/`#####`/`######`,一律用 **加粗标签** + 正文/代码块/表格。
 
-> 本章节将方案从"宏观决策"落到"实现者可直接照写的细节"。它回答:具体怎么实现每个部分?
-> **只呈现本变更涉及的部分**,不涉及的类型显式标注 "本变更不涉及 X" 而非留空。
-> 每个详细设计元素必须**可追溯到 §3 验收标准**(Requirement/Scenario)和 §4 决策(design.md 的 D1-Dn)。
+```text
+### 4.4 数据结构 / 数据模型变更
+├── #### 4.4.1 总则与本迭代结构变更结论
+├── #### 4.4.2 ER 图(核心实体关系)
+├── #### 4.4.3 逐表详设
+│   ├── ##### `table_a`(中文名)     ← 每张表仅此一级标题
+│   └── ##### `table_b`(中文名)
+└── #### 4.4.4 非表字段、数据迁移与回滚兼容
+```
 
-### 6.1 数据结构 / 数据模型变更 (Data Structures)
+表内固定顺序用加粗标签(不是标题):`**本迭代动作**` → `**本迭代变更语句**` → `**DDL(现网/目标)**` → `**字段说明**` →(可选)`**JSON 形状 · <字段名>**`。
 
-**适用范围**:涉及持久化、状态存储、数据模型的变更。纯 CLI/库项目若无数据库,覆盖配置结构 / 状态文件 / 缓存结构 / YAML schema 等"数据模型"。
+#### A. 库表路径(MySQL / PostgreSQL / SQLite 等关系库)——强制结构
 
-| 元素 | 内容 |
-|------|------|
-| 新增/修改的表结构或数据模型 | 名称、字段、类型、长度、约束(主键/外键/唯一/非空/默认值) |
-| 索引建议 | 由查询模式驱动的索引(覆盖查询/联合/唯一),不盲目加索引;说明每条索引支撑的查询 |
-| 数据迁移 | 存量数据转换方式、迁移脚本、回滚方案 |
-| 配置结构 | 新增/修改的配置键、类型、默认值、生效时机 |
+按以下小节**顺序**生成。缺任一强制项 → 视为详细设计质量不合格,在确认摘要中报告用户并标记 `[待 refine 澄清]` 或补全后再写入。
 
-示例(数据库):
-```sql
-CREATE TABLE artifact_language (
-  id         INTEGER PRIMARY KEY AUTOINCREMENT,
-  project_id INTEGER NOT NULL REFERENCES project(id),
-  language   TEXT NOT NULL DEFAULT 'en' CHECK (language IN ('en','zh-CN')),
-  updated_at TEXT NOT NULL,
-  UNIQUE (project_id)
-);
--- 索引 idx_project_language:支撑 "按 project_id 查语言" 高频查询
-CREATE INDEX idx_artifact_language_project ON artifact_language(project_id);
+##### 4.4.1 总则与本迭代结构变更结论
+
+用结论表一眼说清本迭代对库结构做什么(即使结论是「零迁移」也要写明):
+
+| 项 | 结论 |
+|----|------|
+| 数据库迁移(脚本/工具名) | 有 / **本迭代零迁移** |
+| 新建表 | 表名列表 / **无** |
+| 新增 / 修改 / 删除列 | 列清单 / **无** |
+| 新增索引 | 索引清单 / **无** |
+| DDL 来源 | 仓库基线路径 或 本迭代新增 |
+| DB 技能 | `skills/database/<stack>`(本地) / `LLM-fallback` |
+
+紧接一段 **本迭代变更语句** 代码块:
+
+- 有变更:给出可执行的 `CREATE` / `ALTER` / `DROP`(与下方逐表 DDL 一致)。
+- **零变更**:显式写「无(明确不执行)」,并可用注释列出**禁止合入**的反例 `ALTER`/`CREATE`(防止实现时偷偷加列)。
+
+##### 4.4.2 ER 图(核心实体关系)——强制
+
+用 Mermaid `erDiagram` 画出**本变更涉及的核心实体**(新增 + 修改 + 本迭代强依赖的既有表),标注:
+
+1. 实体名(= 表名)与**中文表意**(可用实体注释或紧随其后的说明)。
+2. 关系基数(`||--o{` / `}o--||` 等)与关联键语义(如「作业 1 — N 逐步结果」)。
+3. 每个实体列出 **3–8 个关键属性**(主键、业务主键、外键、本迭代读写的关键列);勿堆砌全量字段(全量在字段说明表)。
+4. 与 §2 决策、§3 组件一致:图中实体必须在表一览与逐表章节出现。
+
+```mermaid
+erDiagram
+  PARENT_TABLE ||--o{ CHILD_TABLE : "1:N 业务关系说明"
+  PARENT_TABLE {
+    char uid PK "业务主键"
+    varchar name "名称"
+  }
+  CHILD_TABLE {
+    char uid PK
+    char parent_uid FK
+    int step_order "本迭代幂等键之一"
+  }
 ```
 
-示例(CLI/库项目的配置结构):
+**图说明(强制,紧跟 ER 图)**:用表格描述图中每张表,提升可读性 —— 不是重复 ER 属性列表,而是回答「这张表是干什么的、本迭代怎么动」:
+
+| 表名 | 中文名 | 职责(一句话) | 结构 | 本迭代动作 |
+|------|--------|--------------|------|------------|
+| `parent_table` | … | … | 不变 / 新增 / 改列 | 只读 / 写入 / 新建 |
+
+##### 4.4.3 逐表详设(强制骨架)
+
+对表一览中的**每一张表**输出同构小节 `##### \`table_name\`(中文名)`(**仅此一级**进大纲;其下**禁止**再开标题)。顺序固定,标签一律 `**加粗**`:
+
+1. **本迭代动作**:只读 / 写入(既有路径) / 新建 / 改结构(列清单) —— 一句话 + 关键不变量(如幂等键)。
+2. **本迭代变更语句**:`无` 或完整 `ALTER`/`CREATE` 片段(可执行)。
+3. **DDL(现网/目标)**:完整 `CREATE TABLE ...`(即使本迭代零 DDL 也给出对照用完整表定义)。
+   - **必须含存储引擎与字符集**(MySQL:`ENGINE=InnoDB DEFAULT CHARSET=utf8mb4` …;PostgreSQL 写明 schema;SQLite 可省略 ENGINE)。
+   - 含 PRIMARY KEY、UNIQUE、KEY/INDEX、必要时列/表 `COMMENT`;首行注释标明 DDL 来源。
+4. **字段说明**:紧跟一张表(强制列):
+
+| 字段名称 | 字段类型 | 是否有默认值 | 字段说明 | 本迭代用法 |
+|----------|----------|--------------|----------|------------|
+
+   - 「本迭代用法」写清:读 / 写 / 不涉及 / **固定赋值**等;索引已在 DDL 声明即可。
+5. 若含 JSON / 大字段契约:用 `**JSON 形状 · <列名或逻辑名>**` 加粗标签 + 形状表/代码块,**不要**再开 `##### 字段说明` / `##### runtime_payload…` 标题。
+
+##### 4.4.4 非表字段、数据迁移与回滚兼容
+
+| 项 | 说明 |
+|----|------|
+| 协议/计算字段(不落库) | 如列表聚合计数;说明计算方式 |
+| **存量数据默认值填充策略**(G3) | JSON 形状变更或新增列时**必须**填写:回填 SQL/脚本、读路径默认值、是否允许空、上线顺序(先兼容读再写新形状等) |
+| 结构回滚 | 有 DDL → 回滚脚本要点;无 DDL →「无结构可回滚,回滚应用即可」 |
+| **回滚数据兼容**(G4) | 新版本已写入行/JSON,旧版本代码能否安全忽略未知字段或旧 `schema_version`?写明机制(`omitempty` / 忽略未知键 / version 分派等) |
+| 数据保留 | 已写入行是否保留、是否需清洗 |
+
+**零结构变更且不改 JSON 语义时**:在上表写明「无存量填充;无新形状回滚兼容问题」,不得整节留空。
+
+#### B. 库表路径 —— 质量自检(生成后必过)
+
+- [ ] 有总则结论表 + 本迭代变更语句(零变更也显式写「无」)
+- [ ] 有 Mermaid `erDiagram`,且图后有「表名/中文名/职责/结构/本迭代动作」说明表
+- [ ] 每张涉及表均有:动作、变更语句、**完整 CREATE TABLE(含引擎与字符集)**、字段说明表
+- [ ] 字段说明表含「本迭代用法」列;幂等键 / 外键 / 枚举合法值写清
+- [ ] **G3**:JSON 变更或新增列时有存量默认值填充策略;否则显式写「无存量填充」
+- [ ] **G4**:回滚数据兼容有明确方案或显式「无新旧互读问题」
+- [ ] 无「仅文字描述表结构、无 DDL」或「DDL 缺 ENGINE/CHARSET」的偷懒写法
+- [ ] 零 DDL 迭代禁止假装「不涉及数据库」—— 只要读写表,仍走库表路径并展示现网 DDL
+- [ ] **大纲干净**:§4.4 目录仅为 `4.4.1–4.4.4` + 各表 `##### \`name\``;**无**「DDL / 字段说明 / JSON 形状」标题节点
+
+#### C. 非库表路径(CLI / 库 / 配置 / 状态文件)
+
+无关系库表时,覆盖配置结构 / 状态文件 / YAML schema / 缓存键:
+
+| 元素 | 内容 |
+|------|------|
+| 配置或状态结构 | 键路径、类型、默认值、生效时机 |
+| 约束 | 合法值、校验失败行为 |
+| 迁移 | 缺省兼容、是否改写存量文件 |
+
+示例:
 ```yaml
 # specflow/config.yaml 新增
 artifacts:
   language: zh-CN   # en | zh-CN,缺省 en
 ```
 
-**不涉及数据库变更时写**:`不涉及数据库变更(纯逻辑/CLI 变更,无持久化数据模型)`。
+**完全不涉及任何持久化/配置结构时写**:`不涉及数据库变更(纯逻辑/CLI 变更,无持久化数据模型)`。
 
-### 6.2 接口设计 (Interface Design)
+#### D. 库表 DDL 示例(完整度标杆)
 
-**适用范围**:暴露 API/RPC/CLI 命令/函数间接口的变更。
-**项目类型适配**:CLI 项目 → commander 命令参数;库项目 → 导出函数签名;Web 项目 → HTTP API。
+```sql
+-- 来源:migrations/example/ddl/orders.sql(或:本迭代新增)
+CREATE TABLE `orders` (
+  `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '内部自增主键',
+  `uid` CHAR(36) NOT NULL COMMENT '业务主键',
+  `project_id` VARCHAR(64) NOT NULL,
+  `status` VARCHAR(32) NOT NULL DEFAULT 'pending',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_uid` (`uid`),
+  KEY `idx_project_status` (`project_id`, `status`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+  COMMENT='订单';
+```
 
-| 元素 | 内容 |
-|------|------|
-| 接口签名 | 方法名/路径/CLI 命令;参数名、类型、必选/可选、校验规则 |
-| 入参说明 | 每个参数的语义、合法值、默认值 |
-| 出参说明 | 返回类型、成功/失败结构 |
-| 错误码定义 | 错误码枚举、含义、HTTP 状态码 / CLI 退出码映射 |
+### 4.5 接口设计 (Interface Design)
+
+**适用范围**:暴露 API / RPC / CLI 命令 / 跨模块函数接口的变更(含「协议不变但本迭代新消费」)。
+**项目类型适配**:Web/服务 → HTTP(+RPC);CLI → commander 等命令参数;库 → 导出函数签名。
+
+> **质量硬门槛(对外/跨端接口路径)**:只要本变更新增、修改、行为扩展或**新消费**对外接口,§4.5 **必须**按下列结构输出。参考质量标杆:`scenario-job-compile`「接口设计」章(总览与约定 → 接口清单 → 通用错误码 → 逐接口字段表+HTTP 示例 → 调用关系)。禁止只有路径名、无字段表、无错误约定、无请求/响应示例。
+
+> **大纲 / 标题层级(硬门槛 — 防 TOC 爆炸)**:大纲**只允许**下列标题;「请求体字段」「请求示例」「响应示例」「错误」等**禁止**写成标题,一律 `**加粗**`。
 
-示例(CLI):
 ```text
-specflow init --artifact-language <language>
-  入参: language?: string   可选,默认 'en';合法值 en | zh-CN | zh(zh 别名→zh-CN)
-  出参: { status: 'initialized' | 'already_initialized' | 'updated_assets', message: string }
-  错误码:
-    E_INVALID_LANGUAGE   退出码 1 — 不支持的 language 值
-    E_PARITY_STRICT      退出码 1 — 资产生成后 parity 校验失败
+### 4.5 接口设计
+├── #### 4.5.1 总览与约定          ← 通道 / 清单 / 通用错误码 均用加粗小标题,不进更深目录
+├── #### 4.5.2 逐接口详设
+│   ├── ##### I1 · <短名>(变更类型)  ← 每个接口仅此一级标题
+│   └── ##### I2 · …
+└── #### 4.5.3 调用关系
 ```
 
-**不涉及接口变更时写**:`不涉及接口变更(内部实现调整,无对外/跨模块接口变化)`。
+接口内固定顺序用加粗标签:`**元信息**` → `**请求体字段**`(或路径/Query/CLI flags) → `**请求示例**` → `**成功响应字段**` → `**响应示例(成功)**` → `**响应示例(失败)**`(G2) → `**错误**` →(可选)`**处理顺序**`。
 
-### 6.3 业务流程 (Business Flow)
+#### A. 对外/跨端接口路径——强制结构
 
-**适用范围**:有状态流转、多步骤逻辑、并发时序的变更。即使无显式状态机,任何多步骤流程都应画时序图。
+##### 4.5.1 总览与约定
 
-| 元素 | 内容 |
-|------|------|
-| 时序说明 | 谁调用谁、顺序、分支、异常路径(可用 Mermaid `sequenceDiagram`) |
-| 状态机流转 | 状态集合、迁移事件、迁移条件、终态(可用 Mermaid `stateDiagram-v2`) |
+**1) 调用方与通道**(多通道时必填;单通道也建议写明鉴权):
 
-示例(时序):
-```mermaid
-sequenceDiagram
-  participant U as User
-  participant I as init CLI
-  participant FS as Filesystem
-  participant P as Parity check
-  U->>I: specflow init --artifact-language zh-CN
-  I->>FS: 创建 specflow/{changes,specs}
-  I->>FS: 写入 config.yaml (artifacts.language: zh-CN)
-  I->>FS: 复制 IDE 资产 (skills/commands/prompts)
-  I->>P: parity 严格校验
-  P-->>I: ok / fail
-  I-->>U: status + message
+| 通道 | 路径前缀 / 入口 | 调用方 | 鉴权 |
+|------|-----------------|--------|------|
+| 例:控制台 API | `/api/v1/...` | 前端经网关 | 用户/项目身份 |
+| 例:内部 API | `/internal/v1/...` | Worker/服务 | 租约/服务身份 |
+
+**2) 本迭代接口清单**(强制总表,编号稳定便于交叉引用):
+
+| 编号 | 接口 | 变更类型 | 应用场景 |
+|------|------|----------|----------|
+| I1 | <短名> | **新增** / **修改** / **行为扩展**(请求体不变) / **不变**(本迭代消费) | 谁在什么时候用 |
+
+变更类型约定(优化自标杆文档,强制统一用语):
+
+| 类型 | 含义 | §4.5 展开深度 |
+|------|------|---------------|
+| 新增 | 新路径或新 RPC | 完整展开(字段+示例+错误) |
+| 修改 | 请求/响应形状变化(加字段、改语义) | 完整展开,并标明**本迭代变更点** |
+| 行为扩展 | 消息形状不变,服务端认新取值/新分支 | 完整展开侧重点:行为差异与错误;可注明「请求/响应消息不变」 |
+| 不变(本迭代消费) | 协议不动,本迭代开始依赖 | 可精简:场景+协议+关键字段/查询约定+为何本迭代需要;仍建议有成功响应要点 |
+| 不变(不展开) | 已落地且本迭代不改、不新消费 | **清单可一句带过或不列入**,勿重复粘贴既有文档 |
+
+**3) 通用错误码约定**(强制;按项目现网风格映射):
+
+| 错误类别 / 状态 | 典型 HTTP 或退出码 | 含义(本迭代) |
+|-----------------|-------------------|--------------|
+| 参数非法 | 400 / 退出码 1 | … |
+| 未找到 | 404 | … |
+| 无权限 / 未认证 | 403 / 401 | … |
+| 冲突 / 前置失败 | 409 / 412 | … |
+| 内部错误 | 500 | … |
+
+**约定**(按项目裁剪,至少覆盖命名与错误风格):
+
+1. **字段命名**:与现网一致(如 JSON 蛇形 `project_id`;proto `json_name`;CLI kebab-case 等)。
+2. **错误风格**:业务错误进 `message` / 状态详情;**禁止**「HTTP 200 + 业务错误码」混用(除非项目现网已是该风格且 design 显式沿用)。
+3. **幂等 / 终态语义**:若存在上报类接口,写清「成功 ≠ 资源终态」等不变量(对齐 §2 决策)。
+4. **兼容缺省**:可选字段缺省时的兼容行为写进字段表「默认」列。
+5. **与流程对齐**:接口编号可被 §4.2/§4.3 时序与 §6 测试引用。
+
+##### 4.5.2 逐接口详设(强制骨架)
+
+对清单中每个需展开的编号 `In`,输出同构小节 `##### In · <短名>(<变更类型>)`(**仅此一级**进大纲;其下**禁止**再开 `####`/`#####`/`######`)。顺序固定,标签一律 `**加粗**`:
+
+1. **元信息**(强制表):
+
+| 项 | 内容 |
+|----|------|
+| 应用场景 | 谁、在什么用户动作/系统时机下调用 |
+| 协议 | 方法 + 路径(或 CLI 命令 / 导出函数签名) |
+| Content-Type / 编码 | 如 `application/json`(若适用) |
+| 对应 RPC / 内部名 | 若有(可写暂定名 +「实现时与 OpenAPI/proto 对齐」) |
+| 鉴权 | 本接口鉴权要点(可引用通道表) |
+| 本迭代变更 | 一句话(新增字段 / 行为扩展 / 不变仅消费 …) |
+
+2. **请求体字段**(有则写;路径参数 / Query / CLI flags 用同级加粗标签分块,如 `**Query 参数**`,仍**不要**升为标题):
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+
+   - 合法值枚举、别名归一、与表字段差异写在「说明」;互斥参数用引用块。
+
+3. **请求示例**(强制 ≥1 主路径成功请求):Web 用完整 `http` 块;CLI/库用等价示例。多场景时用加粗副标区分,例:`**请求示例(场景)**` / `**请求示例(接口用例 · 兼容旧客户端)**` —— **不是**标题。
+
+4. **成功响应字段** + **响应示例(成功)**(强制)。
+
+5. **响应示例(失败)**(质量红线 G2 — 强制):每个「新增/修改/行为扩展」接口 **≥1** 组报错示例(完整 HTTP 或等价);副标可写失败原因,例:`**响应示例(失败 · 无启用步)**`,仍**不是**标题。
+
+6. **错误**(强制表:条件 → 状态/退出码 → 说明):
+
+| 条件 | 状态 / 退出码 | 说明 |
+|------|---------------|------|
+
+7. **处理顺序**(可选):多步服务端合同用编号列表;与 §4.2/§4.3、§4.4 对齐。
+
+##### 4.5.3 调用关系(推荐)
+
+用短文本或 Mermaid 概括调用方如何串起 `I1…In`(主路径一条线即可),便于实现与联调对照。
+
+```text
+调用方A: I3 → I1 → I4 → I7
+调用方B: … → I5 → I6
 ```
 
-**不涉及业务流程变更时写**:`不涉及复杂业务流程(单步/线性实现,无状态流转)`。
+#### B. 接口路径 —— 质量自检(生成后必过)
+
+- [ ] 有通道/鉴权表(或多通道说明)+ 本迭代接口清单(编号+变更类型+场景)
+- [ ] 有通用错误码约定 + 命名/错误风格约定
+- [ ] 每个「新增/修改/行为扩展」接口具备:元信息、字段表、成功请求/响应示例、**失败示例(G2)**、错误表
+- [ ] 「不变·本迭代消费」接口至少有场景+协议+关键消费约定,不假装不存在
+- [ ] 无「只有路径、无字段/无示例/无错误」的偷懒写法;示例与字段表一致
+- [ ] 接口编号可被 §4.2/§4.3 流程、§6 测试引用
+- [ ] **大纲干净**:§4.5 目录仅为 `4.5.1–4.5.3` + 各 `##### In · …`;**无**「请求体字段 / 请求示例 / 响应示例 / 错误」标题节点
+
+#### C. CLI / 库项目路径(无 HTTP 时)
 
-### 6.4 核心算法 / 逻辑说明 (Core Logic)
+无 HTTP 时仍用「清单 + 逐接口」骨架,将「协议」换为命令/导出签名;错误码换为退出码或抛错类型。示例:
+
+```text
+specflow init --artifact-language <language>
+  入参: language?: string   可选,默认 'en';合法值 en | zh-CN | zh(zh 别名→zh-CN)
+  出参: { status: 'initialized' | 'already_initialized' | 'updated_assets', message: string }
+  错误码:
+    E_INVALID_LANGUAGE   退出码 1 — 不支持的 language 值
+    E_PARITY_STRICT      退出码 1 — 资产生成后 parity 校验失败
+```
+
+**完全不涉及接口变更时写**:`不涉及接口变更(内部实现调整,无对外/跨模块接口变化)`。
+
+### 4.6 核心算法 / 逻辑说明 (Core Logic)
 
 **适用范围**:有非平凡算法或数据处理逻辑的变更。
 | 元素 | 内容 |
@@ -634,7 +886,7 @@ sequenceDiagram
 
 **不涉及非平凡算法时写**:`不涉及非平凡算法(逻辑简单,无复杂数据处理)`。
 
-### 6.5 配置与运行环境 (Configuration & Runtime)
+### 4.7 配置与运行环境 (Configuration & Runtime)
 
 **适用范围**:新增配置项、环境变量、运行时依赖的变更。
 | 元素 | 内容 |
@@ -645,48 +897,74 @@ sequenceDiagram
 
 **不涉及配置变更时写**:`不涉及配置或运行环境变更`。
 
-### 6.6 兼容性与迁移 (Compatibility & Migration)
+### 4.8 兼容性与迁移 (Compatibility & Migration)
+
+**适用范围**:破坏性变更、JSON/列变更、或任何「新版本写入、旧版本仍可能读」的发布窗口。
 
-**适用范围**:有破坏性变更。
 | 元素 | 内容 |
 |------|------|
-| 旧行为 → 新行为 | 映射表 |
-| 迁移路径 | 存量用户如何升级、迁移步骤 |
-| 回滚方案 | 失败时如何回滚 |
+| 旧行为 → 新行为 | 映射表(禁止含糊「基本兼容」) |
+| 迁移路径 | 存量用户如何升级、步骤顺序 |
+| **存量默认值填充**(G3) | 与 §4.4.4 一致;JSON/新列必须写明填充策略 |
+| **回滚数据兼容**(G4) | 发布失败回滚后:新代码已写数据,旧代码是否安全忽略/跳过?必须给出方案(`omitempty` / 忽略未知字段 / `schema_version` 等) |
+| 应用回滚 | 镜像/包回退步骤 |
 
-**不涉及破坏性变更时写**:`不涉及破坏性变更(向后兼容)`。
+**完全无兼容风险时写**:`不涉及破坏性变更(向后兼容);无新形状写入,回滚仅回退应用即可` —— 仍须一句话点明「无新旧数据互读问题」。
 
 ### 详细设计质量自检(生成后检查)
 
-- [ ] 每个详细设计元素可追溯到 §3 验收标准的某个 Requirement/Scenario
-- [ ] 每个详细设计选择引用了 §4 的某个决策(不另起炉灶)
-- [ ] 涉及数据/接口/流程的,均非留空(写了真实签名/字段/状态)
-- [ ] 不涉及的类别显式标注 "不涉及",而非留空
-- [ ] 若某个元素无法写出实现级细节,标记 `[待 refine 澄清: <元素>]` — 这是方案未想透的质量信号,应报告给用户
+- [ ] 有 §4.1 设计要点一览(P1…Pn)
+- [ ] 有 §4.2 Happy Path **完整**时序图 + 设计要点说明
+- [ ] 每个 §4.3 业务场景均有图 + **设计要点说明**(无裸图)
+- [ ] **G1**:超过 5 行的文字流程已改为 Mermaid,无长散文流程
+- [ ] 每个详细设计元素可追溯到 §5 Requirement/Scenario 与 §2 决策
+- [ ] 涉及数据/接口的均非留空;不涉及类别显式标注
+- [ ] **§4.4**:ER + DDL + 字段说明;若 JSON/新列变更则有**存量填充策略(G3)**与回滚数据兼容(G4)
+- [ ] **§4.5**:通道/清单/错误码 + 字段/成功示例 + **失败示例(G2)** + 错误表
+- [ ] **§4.4/§4.5 大纲**:目录仅含 `4.4.x`/`4.5.x` + 表名/`In` 小节;字段/示例/DDL/错误均为加粗标签,无标题节点
+- [ ] **§4.8**:回滚兼容结论明确(或显式声明无新旧数据互读问题)
+- [ ] **文风**:无「尽量/大概/一般情况下」等含糊词;生僻缩写首次已注解
+- [ ] 若无法写出实现级细节,标记 `[待 refine 澄清: <元素>]`
+
+---
+
+## 5. 验收标准 (Acceptance Criteria)
+
+[按 capability 分组,完整列出所有 Requirement + Scenario,每个 Scenario 3 级可测试性标注]
+
+### 5.1 Capability: <name>
+[Delta 操作类型: ADDED / MODIFIED / REMOVED / RENAMED]
+
+#### Requirement: <name>
+<描述>
+
+| Scenario | WHEN | THEN | 可测试性 | 说明 |
+|----------|------|------|---------|------|
+| <name> | <条件> | <期望> | ✅ 功能可测试 / ⚠️ 文档可测试 / ❌ 不可测试 | <原因 if ⚠️/❌> |
 
 ---
 
-## 7. 测试策略 (Test Strategy)
+## 6. 测试策略 (Test Strategy)
 
-> 本章从"§3 验收标准可不可测"升级为"**用分层测试证明方案正确**"。它回答:
+> 本章从"§5 验收标准可不可测"升级为"**用分层测试证明方案正确**"。它回答:
 > 每个验收标准(WHEN/THEN)由哪一层测试覆盖、用什么工具、目标是证明什么。
 > **选择性呈现**:只列出本变更实际需要的测试层级;不涉及的层级显式标注"不涉及"。
 
-### 7.1 分层测试矩阵
+### 6.1 分层测试矩阵
 
 | 测试层级 | 覆盖对象 | 工具/框架 | 目标(证明什么) | 覆盖的验收标准 |
 |---------|---------|----------|---------------|---------------|
-| 单元测试 | 核心函数/类/模块内部逻辑 | <框架,如 vitest/jest/pytest> | 逻辑正确、边界处理 | 引用 §3 的 Scenario |
-| 集成测试 | 模块间交互、接口契约、外部依赖 | <框架> | 模块协作正确、契约一致 | 引用 §3 的 Scenario |
-| 验收测试 | spec 的 WHEN/THEN 行为 | <E2E/CLI 测试> | 逐 Scenario 验证用户可见行为 | §3 全部核心 Scenario |
-| 回归测试 | 主 specs 基线 + 既有行为 | <框架> | 不破坏已有功能 | 主 specs(§3 基线对照) |
+| 单元测试 | 核心函数/类/模块内部逻辑 | <框架,如 vitest/jest/pytest> | 逻辑正确、边界处理 | 引用 §5 的 Scenario |
+| 集成测试 | 模块间交互、接口契约、外部依赖 | <框架> | 模块协作正确、契约一致 | 引用 §5 的 Scenario |
+| 验收测试 | spec 的 WHEN/THEN 行为 | <E2E/CLI 测试> | 逐 Scenario 验证用户可见行为 | §5 全部核心 Scenario |
+| 回归测试 | 主 specs 基线 + 既有行为 | <框架> | 不破坏已有功能 | 主 specs(§5 基线对照) |
 | 性能测试 | 关键路径/高并发 | <如 k6/jmeter/bench> | NFR 性能目标达成 | NFR 章节 |
 | 安全测试 | 认证/授权/输入边界 | <SAST/渗透> | 无已知漏洞 | NFR 安全目标 |
 | 兼容性测试 | 多平台/多版本/多浏览器 | <如 playwright> | 跨环境一致 | 兼容性 Requirement |
 
 **填写要求**:
 
-1. 每个测试层级**映射到 §3 验收标准**(引用具体 Scenario 名)—— 这是"测试策略与验收标准闭环"的关键
+1. 每个测试层级**映射到 §5 验收标准**(引用具体 Scenario 名)—— 这是"测试策略与验收标准闭环"的关键
 2. 每个层级标注**工具/框架**(呼应 full-stack-skills 的"阶段→技能映射":测试阶段→test-writer/playwright/pytest)
 3. **目标要可验证**("证明 P95 < 200ms" 而非 "测性能")
 4. 新增测试 vs 修改既有测试要区分
@@ -700,7 +978,7 @@ sequenceDiagram
 | 验收测试 | `specflow init --artifact-language zh-CN` 全流程 | CLI 测试 | 端到端产物符合预期 | "Reject an unsupported language" 等 |
 | 回归测试 | 既有 init 行为(无语言参数) | vitest | 缺省仍为 en,不破坏既有 | "Initialize without an explicit language" |
 
-### 7.2 测试环境与数据
+### 6.2 测试环境与数据
 
 | 项 | 说明 |
 |----|------|
@@ -709,9 +987,9 @@ sequenceDiagram
 | 并行/隔离 | 测试间是否可并行、是否需要隔离(文件锁/独立目录) |
 | 覆盖率目标 | 核心模块目标覆盖率(如 ≥80%) |
 
-### 7.3 测试策略自检
+### 6.3 测试策略自检
 
-- [ ] 每个 §3 验收标准至少被一个测试层级覆盖(闭环)
+- [ ] 每个 §5 验收标准至少被一个测试层级覆盖(闭环)
 - [ ] 每个测试层级有工具、有可验证目标
 - [ ] 既有行为有回归测试保护(对应 Pass 7 基线)
 - [ ] 新增测试与修改既有测试已区分
@@ -720,12 +998,12 @@ sequenceDiagram
 
 ---
 
-## 8. 部署/发布/回滚方案 (Deployment & Release)
+## 7. 部署/发布/回滚方案 (Deployment & Release)
 
 > 本章回答"方案实现后如何上线、如何发布、出问题如何回滚、上线后如何监控"。
 > **选择性呈现**:对有运行系统的项目必须;对纯库/CLI/文档项目可显式标注"不涉及运行时部署"。
 
-### 8.1 部署方案 (Deployment)
+### 7.1 部署方案 (Deployment)
 
 | 项 | 方案 |
 |----|------|
@@ -735,7 +1013,7 @@ sequenceDiagram
 | 配置管理 | 新配置项如何在各环境生效、密钥管理 |
 | 环境差异 | dev/staging/prod 的环境差异与处理 |
 
-### 8.2 发布策略 (Release Strategy)
+### 7.2 发布策略 (Release Strategy)
 
 | 项 | 方案 |
 |----|------|
@@ -743,7 +1021,7 @@ sequenceDiagram
 | 发布窗口 | 是否需停机窗口、灰度比例 |
 | 兼容性 | 新旧版本共存期间的兼容(如 API 版本化、DB 兼容) |
 
-### 8.3 回滚方案 (Rollback)
+### 7.3 回滚方案 (Rollback)
 
 | 项 | 方案 |
 |----|------|
@@ -752,7 +1030,7 @@ sequenceDiagram
 | 回滚的数据一致性 | 数据迁移的回滚(若有)、缓存/队列的清理 |
 | 回滚验证 | 回滚后如何确认恢复正常 |
 
-### 8.4 监控与可观测性 (Monitoring & Observability)
+### 7.4 监控与可观测性 (Monitoring & Observability)
 
 | 项 | 方案 |
 |----|------|
@@ -760,7 +1038,7 @@ sequenceDiagram
 | 日志/追踪 | 日志规范、链路追踪 |
 | 告警 | 告警阈值与负责人 |
 
-### 8.5 部署方案自检
+### 7.5 部署方案自检
 
 - [ ] 部署目标/方式/顺序明确
 - [ ] 发布策略与兼容性说明
@@ -771,63 +1049,30 @@ sequenceDiagram
 
 ---
 
-## 9. 闭环性检查 (Closed-Loop Verification)
-
-### Pass 1: 需求闭环 (Requirement Closure)
-**Verdict:** PASS / WARNING / FAIL
-**证据:** <proposal→spec 覆盖表>
-
-### Pass 2: 方案闭环 (Design Closure)
-**Verdict:** PASS / WARNING / FAIL
-**证据:** <decision↔requirement 双向表>
-
-### Pass 3: 规格闭环 (Spec Closure)
-**Verdict:** PASS / WARNING / FAIL
-**证据:** <Scenario 可测试性表 + delta 结构检查>
+## 8. 闭环性检查 (Closed-Loop Verification)
 
-### Pass 4: 实施闭环 (Implementation Closure)
-**Verdict:** PASS / WARNING / FAIL
-**证据:** <requirement×task 覆盖矩阵 + 范围蔓延检查>
+> **写法要简练**:内部仍跑完 Pass 1–7,但写入本文只保留下表。  
+> - `PASS` / `SKIPPED`:「关键证据」一句话即可(不必贴大表)。  
+> - `WARNING` / `FAIL`:「关键证据」写清缺口(文件/Requirement/Scenario/任务 ID),最多 2–3 条要点。  
+> - **禁止**为每个 Pass 再开长小节、禁止重复贴总评表。
 
-### Pass 5: 风险闭环 (Risk Closure)
-**Verdict:** PASS / WARNING / FAIL
-**证据:** <风险表 + 未识别风险>
-
-### Pass 6: 代码落地性 (Code Grounding)
-**Verdict:** PASS / WARNING / FAIL / SKIPPED (greenfield)
-**证据:**
-
-| 锚点文件 | 存在? | 计划动作 | 结构兼容性 |
-|---------|------|---------|-----------|
-| <path> | ✅/❌ | extend/create/modify | <评估> |
-
-**技术栈一致性:** <一行结论 + 理由>
-
-### Pass 7: 基线对照 (Baseline Cross-Check)
-**Verdict:** PASS / WARNING / FAIL / SKIPPED (no baseline)
-**证据:**
-
-| Capability | Requirement | 操作 | 基线状态 | 结论 |
-|-----------|-------------|------|---------|------|
-| <name> | <name> | ADDED/MODIFIED/... | exists/duplicate/not-found | ✅/⚠️/❌ |
-
-### 闭环性总评
-
-| 维度 | 结论 |
-|------|------|
-| Pass 1 需求闭环 | ✅/⚠️/❌/⊘(skipped) |
-| Pass 2 方案闭环 | |
-| Pass 3 规格闭环 | |
-| Pass 4 实施闭环 | |
-| Pass 5 风险闭环 | |
-| Pass 6 代码落地性 | |
-| Pass 7 基线对照 | |
+| Pass | 检查项 | 结论 | 关键证据(一句话;⚠️/❌ 可列 2–3 条要点) |
+|------|--------|------|--------------------------------------|
+| 1 | 需求闭环 proposal↔specs | ✅/⚠️/❌ | |
+| 2 | 方案闭环 design↔specs | ✅/⚠️/❌ | |
+| 3 | 规格闭环 场景/可测试性/delta | ✅/⚠️/❌ | |
+| 4 | 实施闭环 tasks↔specs | ✅/⚠️/❌ | |
+| 5 | 风险闭环 缓解/BREAKING | ✅/⚠️/❌ | |
+| 6 | 代码落地性 锚点/结构/栈 | ✅/⚠️/❌/⊘ | |
+| 7 | 基线对照 主 specs | ✅/⚠️/❌/⊘ | |
 
 **整体闭环性:** PASS / PASS WITH WARNINGS / FAIL
 
+判定:任一 ❌ → FAIL;无 ❌ 但有 ⚠️ → PASS WITH WARNINGS;全 ✅(⊘ 不计)→ PASS。
+
 ---
 
-## 10. 可实施性评估 (Implementability Assessment)
+## 9. 可实施性评估 (Implementability Assessment)
 
 | 评估维度 | 结论 | 说明 |
 |---------|------|------|
@@ -843,14 +1088,14 @@ sequenceDiagram
 
 ---
 
-## 11. 审批意见 (Approval Decision)
+## 10. 审批意见 (Approval Decision)
 
-### 7.1 AI 预审建议
+### 10.1 AI 预审建议
 
 **建议:** 建议批准 / 有条件批准 / 退回 refine / 拒绝
 **理由:** <1-2 句话,引用具体 verdict>
 
-### 7.2 人工审批签字栏
+### 10.2 人工审批签字栏
 
 | 角色 | 姓名 | 审批结论 | 日期 | 意见 |
 |------|------|---------|------|------|
@@ -866,47 +1111,112 @@ sequenceDiagram
 
 | 章节 | 数据来源 | 处理方式 |
 |------|---------|---------|
-| 变更概览 | .specflow.yaml + specs/ + tasks.md + design.md + 项目代码 + 主 specs | 精确统计 |
-| 变更摘要 | proposal.md (+ explore.md) | AI 提炼 |
-| 验收标准 | specs/**/*.md | AI 整合 + 3 级可测试性评估 |
-| 技术方案评估 | design.md | AI 用 arc42 重组 + 决策表 + 风险表 + 设计质量评估 |
-| 架构整体设计 | design.md 决策 + 项目代码(锚点)+ specs 契约 | AI 绘制 Mermaid 模块依赖/系统交互图 + 组件职责边界表;每组件追溯到 §4 |
-| 方案详细设计 | design.md 决策 + specs 契约 + 项目代码(锚点) | AI 落地为数据/接口/流程/算法/配置/兼容性;每元素追溯到 §3+§4 |
-| 测试策略 | §3 验收标准 + 项目测试栈 | AI 分层测试矩阵(单元/集成/验收/回归/性能/安全),每层映射到验收标准 |
-| 部署/发布/回滚 | §4 决策 + 项目运行环境 | AI 部署方式/发布策略/回滚/监控方案;纯库项目标注"不涉及运行时部署" |
-| 闭环性检查 Pass 1-5 | 四件套交叉验证 | AI 推理 |
-| 闭环性检查 Pass 6 | 项目锚点文件(只读文件本身) | AI 代码结构分析 |
-| 闭环性检查 Pass 7 | specflow/specs/ 主基线 | AI 交叉对照 |
-| 可实施性评估 | tasks + design + specs + 项目代码 | AI 推理 |
-| 审批意见 | 闭环性 + 设计质量 + 可实施性三重 verdict | AI 预审 + 人工签字栏 |
+| 绪论与边界 | proposal.md + explore.md(可选) + design Non-Goals | AI 提炼;痛点图 + What/Impact + User Journey + 非目标;**无变更摘要章** |
+| 技术方案评估 | design.md | 决策表 + 风险表 + 设计质量 |
+| 架构整体设计 | design + 锚点代码 + specs | Mermaid 图 + **图要点说明** + 组件边界表;追溯 §2 |
+| 方案详细设计 | design + specs + 锚点 + 现网 DDL/API | 设计要点 + Happy Path + 业务场景(+说明) + 数据/接口等;追溯 §5+§2 |
+| 验收标准 | specs/**/*.md | **置于设计之后**;3 级可测试性 |
+| 测试策略 | §5 验收标准 + 项目测试栈 | 分层矩阵映射验收标准 |
+| 部署/发布/回滚 | §2 决策 + 运行环境 | 部署/发布/回滚/监控 |
+| 闭环性检查 | 四件套 + 锚点 + 主 specs | 内部跑 Pass 1–7;**正文只输出一张结论表**(PASS 一句话;⚠️/❌ 要点化) |
+| 可实施性评估 | tasks + design + specs + 代码 | AI 推理 |
+| 审批意见 | 三重 verdict | AI 预审 + 人工签字栏 |
 ```
 
 ### Generation Rules
 
-1. **Dashboard counts are precise**: read every delta spec file, count headers. Read anchor
-   files, count exists/missing/new. Read `specflow/specs/`, count baseline specs. If a count
-   cannot be determined, state "无法精确统计" rather than guess.
+1. **§1 绪论 must be truthful and precise**: every pain point in the current-flow diagram
+   must be grounded in proposal.md `## Why` / design.md Context / confirmed explore.md
+   (do not invent pains). Absorb What Changes + Impact into §1.2 (no separate 变更摘要
+   chapter). Every User Journey step must trace to a §5 acceptance criterion. Every
+   Non-Goal must state its "不做理由".
 
-2. **Acceptance Criteria is exhaustive**: include every Requirement and Scenario from every
-   delta spec. Do not summarize or omit.
+2. **Acceptance Criteria (§5) is exhaustive and placed after design**: include every
+   Requirement and Scenario from every delta spec. Do not summarize or omit. Do NOT place
+   acceptance before architecture/detailed design.
 
-3. **Pass 6 evidence must cite real code**: every anchor file in the evidence table must be
-   a file you actually read. "Structure compatibility" must reference concrete findings
-   (function name, module pattern, export shape). "I didn't read the file" is not acceptable —
-   either read it or mark it `SKIPPED (greenfield)`.
+3. **Pass 6 evidence must cite real code**: when Pass 6 is ⚠️/❌, §8「关键证据」must cite
+   actual anchor paths and concrete findings. PASS may be one line
+   (e.g. `锚点 N 个均存在,结构可扩展`). Greenfield → `⊘` with the SKIPPED reason.
 
-4. **Pass 7 evidence must cite baseline specs**: every row must reference the actual main
-   spec file and requirement name you compared against. If baseline is absent, use the
-   verbatim `SKIPPED (no baseline — greenfield or no archived changes yet)` line.
+4. **Pass 7 evidence must cite baseline specs**: when ⚠️/❌, cite capability/requirement
+   names compared. PASS → one line; no baseline → `⊘`.
 
 5. **Over-engineering evidence must cite design/tasks location**: "Signal 2 detected in
    `design.md` § D3, which defines a `ReviewerFactory` for a single reviewer type" — not
    just "over-engineered".
 
-6. **Language policy**: narrative follows `artifacts.language`; protocol markers, IDs,
-   paths, commands, code stay in original form.
+6. **Language policy + Style & Tone**: narrative follows `artifacts.language`; protocol
+   markers, IDs, paths, commands, code stay in original form. Apply Style & Tone hard
+   rule (通俗 + 首次注解缩写 + 禁止含糊词) to all human-readable narrative.
 
 7. **No file modification**: this prompt only generates `approval.md`. Do not modify the
    four artifacts, project code, or main specs.
 
 8. **Sign-off table is empty**: human sign-off fields must be blank.
+
+9. **§4.4 database section quality (hard rule)**: if the change reads/writes any
+   relational table (including zero-DDL semantic-only changes), §4.4 MUST include:
+   (a) structure-change conclusion table + explicit change SQL (or explicit「无」),
+   (b) Mermaid `erDiagram` of core entities + a table-description legend
+   (表名/中文名/职责/结构/本迭代动作),
+   (c) per-table complete `CREATE TABLE` with storage engine + charset (MySQL:
+   `ENGINE=InnoDB DEFAULT CHARSET=utf8mb4` …), and
+   (d) per-table field description table with「本迭代用法」.
+   Do NOT substitute prose-only schema descriptions. Do NOT omit ENGINE/CHARSET on
+   MySQL DDL. Zero-DDL iterations still show current-baseline DDL — never claim
+   「不涉及数据库」when tables are in the read/write path.
+
+10. **§4.5 interface section quality (hard rule)**: if the change adds, modifies,
+    behavior-extends, or newly consumes external/cross-service interfaces, §4.5 MUST
+    include: (a) caller/channel + auth overview, (b) numbered interface inventory with
+    change type (新增/修改/行为扩展/不变·本迭代消费), (c) common error-code mapping and
+    naming/error-style conventions, (d) per-interface meta table, field tables
+    (name/type/required/default/description), at least one success request example and
+    success response example, **(e) ≥1 failure request/response example (G2)**, and an
+    error-condition table. Do NOT ship path-only stubs without fields/examples/errors.
+    Unchanged APIs that this iteration does not consume need not be fully re-documented.
+
+11. **§3 architecture diagram key points (hard rule)**: every architecture Mermaid diagram
+    MUST be followed by a numbered「设计说明 / 图要点」list (boundary/invariants/reuse) —
+    not a mere restatement of node names. Component table alone is not enough.
+
+12. **§4 Happy Path + scenario design notes (hard rule)**: §4.1 design-points table, §4.2
+    complete Happy Path `sequenceDiagram`, and each §4.3 business scenario MUST include
+    post-diagram「设计要点」explanations. Bare diagrams without notes are a quality failure.
+
+13. **Quality Gates G1–G4 (hard rule)**:
+    - **G1**: any process description longer than 5 prose lines MUST be a Mermaid
+      `sequenceDiagram` / `flowchart` / `stateDiagram-v2` (no long prose flows).
+    - **G2**: every added/modified/behavior-extended interface in §4.5 MUST include ≥1
+      failure request/response example (validation failure, lease expiry, etc.), not only
+      an error-code table.
+    - **G3**: JSON shape changes or new columns MUST document存量数据默认值填充策略 in
+      §4.4.4 / §4.8.
+    - **G4**: MUST state rollback data compatibility — whether old code can safely
+      ignore/skip data written by new code (`omitempty`, unknown-field ignore,
+      `schema_version`, etc.). "Rollback the image" alone is insufficient.
+
+14. **Style & Tone (hard rule)**: plain language for implementers; obscure English
+    abbreviations MUST be glossed on first use. Ban weasel words「尽量」「大概」
+    「一般情况下」「可能需要」「酌情」「视情况」; use「必须」「禁止」「采用 XX 方案」
+    or explicit if/then tables instead.
+
+15. **§8 closed-loop must be concise (hard rule)**: write exactly one summary table
+    (Pass | 检查项 | 结论 | 关键证据). Do NOT open seven Pass subsections or a second
+    summary table. PASS/SKIPPED → one short phrase; WARNING/FAIL → ≤3 concrete bullets.
+
+16. **§4.4 database skill routing**: before drafting relational DDL, run
+    `prompts/approval/database-guidance.md`. On stack hit, Read local
+    `skills/database/<stack>/…` (in-repo, no remote fetch) and apply idioms; on miss,
+    LLM-only SpecFlow §4.4 rules. Do not invent MCP tools; do not `npx skills add`.
+    Record `skills/database/<stack>` or `LLM-fallback` in the §4.4.1 总则 table.
+
+17. **§4.4 / §4.5 outline hygiene (hard rule)**: Markdown TOC must stay shallow.
+    - §4.4 headings only: `#### 4.4.1–4.4.4` + per-table `##### \`table\`(中文名)`.
+    - §4.5 headings only: `#### 4.5.1–4.5.3` + per-interface `##### In · <短名>(类型)`.
+    - Labels such as「请求体字段」「请求示例」「响应示例」「错误」「DDL」「字段说明」
+      「JSON 形状」「通用错误码约定」MUST be `**bold**` body labels — **never**
+      `####` / `#####` / `######` headings. Multiple examples use bold sub-labels
+      (e.g. `**响应示例(失败 · 无启用步)**`), not extra heading nodes.
+