@gordon.gan/specflow 1.4.3-beta → 1.4.4-beta

package/templates/approval.md

@@ -1,386 +1,169 @@
 <!--
-  Approval document template (v3 — implementer-first narrative).
+  Approval document template (v4 — implementer-first, optional chapters).
   Generated by /specflow:approval after refine converges (phase=refined).
   OPTIONAL artifact — does not affect phase, apply gate, or archive.
 
-  Chapter order (v3):
-  1. 绪论与边界 — proposal + optional explore + AI; absorbs former Executive Summary
-  2. 技术方案评估 — decisions / risks / design quality
-  3. 架构整体设计 — diagrams + 图要点说明 + components (moved up before acceptance)
-  4. 方案详细设计 — 设计要点 + Happy Path + 业务场景时序 + data/API/...
-  5. 验收标准 — after design (契约放在开发设计讲完之后)
+  Chapter order:
+  1. 绪论与边界
+  2. 技术方案评估
+  3. 架构整体设计
+  4. 方案详细设计
+  5. 验收标准 — 可选(写入前询问用户)
   6. 测试策略
-  7. 部署/发布/回滚
-  8. 闭环性检查
+  7. 部署/发布/回滚 — 可选(写入前询问用户)
+  8. 闭环性检查 — 可选(写入前询问用户;分析仍必做)
   9. 可实施性评估
-  10. 审批意见
+  10. 审批意见 — 仅人工签字栏(AI 预审只在对话反馈)
 
-  Quality Gates (G1–G4) + Style & Tone: see prompts/approval/generate.md Part E;
-  enforced on every generated approval.md.
+  质量红线 G1–G6 + 文风(含禁止代码腔):见 prompts/approval/generate.md Part E。
 -->
 
 # 技术方案审批文档: <change-name>
 
 > 本文档由 `/specflow:approval` 基于 refine 收敛后的四件套 + 现有代码与 spec 基线生成,
-> 经 AI 7 维闭环检查、架构整体设计、方案详细设计、测试策略、部署/发布/回滚、设计质量评估与可实施性评估,供人工审批使用。
-> 生成时间: YYYY-MM-DD HH:MM | phase: refined | 产物语言: <en|zh-CN> | 技术栈: <stack>
+> 含架构与详细设计等章节,供人工审批使用。AI 闭环/预审结论在对话中反馈,不写入本文。
+> 生成时间: YYYY-MM-DD HH:MM | phase: refined | 产物语言: <en|zh-CN> | 技术栈: <stack> | 项目模式: <greenfield|brownfield>
 
-> **质量红线(生成时必须满足)**:G1 超 5 行流程→Mermaid · G2 接口须有失败示例 · G3 JSON/新列须有存量填充策略 · G4 须有回滚数据兼容说明。文风:通俗、缩写首次注解、禁用「尽量/大概/一般情况下」。
+> **质量红线(必须满足)**:G1 超 5 行流程→图示 · G2 接口须有失败示例 · G3 JSON/新列须有存量填充策略 · G4 须有回滚数据兼容说明 · G5 有 UI 须有页面/路由清单+栈五元组 · G6 关键页须有空/加载/错态。  
+> **文风**:通俗中文、缩写首次注解、禁用含糊词;**正文禁止代码腔**(路径/函数名堆砌→可读中文)。
 
 ---
 
 ## 1. 绪论与边界 (Introduction & Boundaries)
 
-<!-- 数据来源: proposal.md(必选) + explore.md(若存在且 Status: confirmed 则吸收) + AI 提炼。
-     本章同时承担原「变更摘要」职责:Why / What Changes / Impact 写入 1.1–1.4,不再单独设变更摘要章。 -->
-
 ### 1.1 背景与痛点 (Background & Pain Points)
 
-<!-- proposal.md ## Why (+ explore 洞察);Mermaid 现状流程;痛点红色标注;每痛点一句话代价。 -->
-
-```mermaid
-<!-- 现状流程图 + 红色痛点节点 -->
-```
-
-**痛点清单**(对应图中红色节点):
-
-| 痛点 | 代价 |
-|------|------|
-| <痛点1> | <代价> |
-
 ### 1.2 做什么与影响面 (What & Impact)
 
-<!-- AI 从 proposal What Changes / Impact (+ explore) 提炼;按 新增/修改/移除/重命名,标注 BREAKING。 -->
-
-**做什么**:
-
-| 类别 | 内容 | BREAKING? |
-|------|------|-----------|
-| 新增 | | |
-| 修改 | | |
-| 移除 / 重命名 | | |
-
-**影响面**:
-
-| 影响区域 | 影响等级 | 说明 |
-|---------|---------|------|
-| | 高/中/低 | |
-
 ### 1.3 业务闭环与目标 (Business Loop & Goals)
 
-<!-- 完成后业务如何闭环;User Journey;目标可验证(引用 §5 验收标准)。 -->
-
-```mermaid
-<!-- User Journey -->
-```
-
-**业务目标**(可验证):
-
-| 目标 | 可验证方式(引用 §5) |
-|------|---------------------|
-| <目标1> | §5 <Scenario 名> |
-
 ### 1.4 非目标 (Non-Goals)
 
-| 非目标 | 不做理由 |
-|--------|---------|
-| <非目标1> | <理由> |
-
 ---
 
 ## 2. 技术方案评估 (Technical Design Review)
 
 ### 2.1 现状与约束 (Context & Constraints)
 
-### 2.2 目标与非目标 (Goals & Non-Goals)
+<!-- 可读中文要点;禁止代码腔。绿场可写「尚无存量代码」。 -->
 
-### 2.3 决策评审表 (Decision Review)
+### 2.2 技术选型 (Tech Stack Selection)
 
-| 决策 | 选定方案 | 备选方案 | 理由 | 影响评估 | 状态 |
-|------|---------|---------|------|---------|------|
-| D1: <name> | <方案> | <A/B> | <理由> | <评估> | Proposed |
+<!-- 0→1 或四件套缺选型时强制;来源=用户确认优先。棕地小改可写「沿用现网」。 -->
 
-### 2.4 风险与权衡 (Risks & Trade-offs)
+| 方向 | 选定方案 | 备选(若有) | 选择理由 | 来源 |
+|------|----------|------------|----------|------|
+| 前端 | | | | |
+| 后端 | | | | |
+| 数据库与缓存 | | | | |
+| 基础设施 | | | | |
 
-| 风险 | 严重等级 | 缓解措施 | 就绪度 |
-|------|---------|---------|--------|
-| <name> | 高/中/低 | <措施> | ✅ 已缓解 / ⚠️ 待落实 / ❌ 未识别 |
+### 2.3 目标与非目标 (Goals & Non-Goals)
 
-### 2.5 设计质量评估 (Design Quality)
+### 2.4 决策评审表 (Decision Review)
 
-#### 过度设计检查
-
-| # | 信号 | 检测到? | 证据(design/tasks 位置) |
-|---|------|--------|----------------------|
-| 1 | 为未提出的需求设计接口 | ✅是/❌否 | |
-| 2 | 不必要的抽象层 | | |
-| 3 | 预建未使用的基础设施 | | |
-| 4 | 配置项超出当前需求 | | |
-| 5 | 复杂度超出问题规模 | | |
-
-**过度设计结论:** PASS / WARNING / FAIL
-
-#### 扩展性评估
-
-| # | 信号 | 检测到? | 证据(design 位置) |
-|---|------|--------|----------------|
-| 1 | 命名空间预留 | | |
-| 2 | 接口稳定,实现可替换 | | |
-| 3 | 显式 Non-Goals | | |
-| 4 | 向后兼容路径 | | |
-| 5 | 决策理由提及扩展性权衡 | | |
+| 决策 | 选定方案 | 备选方案 | 理由 | 影响评估 | 状态 |
+|------|---------|---------|------|---------|------|
+| | | | | | |
 
-**扩展性结论:** PASS / WARNING
+### 2.5 风险与权衡 (Risks & Trade-offs)
 
-**设计质量总评:** PASS / WARNING / FAIL
+### 2.6 设计质量评估 (Design Quality)
 
 ---
 
 ## 3. 架构整体设计 (Architecture Design)
 
-<!-- 宏观结构;标杆对齐 scenario-job-compile §3:图 + 图要点说明 + 组件职责边界。
-     与 §4 详细设计互补。不涉及则写:不涉及架构变更(单模块/单文件调整,模块边界无变化)。 -->
+<!-- 起草前:project-conventions-guidance.md topic=architecture;图要点注明项目约定路径。 -->
 
 ### 3.1 总体架构 (Architecture Overview)
 
-<!-- 至少一张模块依赖/分层图;推荐再加系统交互总览。标注 [新增]/[修改]。 -->
-
-```mermaid
-<!-- 模块依赖 / 分层架构图 -->
-```
-
-**设计说明 / 图要点**(强制,紧跟图后;编号列表,解释分层、边界、不变式——不是重复念节点名):
-
-1. …
-2. …
-
-```mermaid
-<!-- 可选:系统交互总览(谁调用谁) -->
-```
-
-**交互要点**(若有交互图): …
-
 ### 3.2 核心组件说明 (Core Components)
 
-| 组件 | 职责 | 边界(做什么 / 不做什么) | 依赖 | 变更类型 |
-|------|------|-------------------------|------|---------|
-| `<组件名>` | 一句话职责 | 做什么;不做什么 | 依赖的组件 | 新增/修改/不变 |
-
 ### 3.3 架构一致性自检
 
-<!-- 图有要点说明;组件有「不做什么」;图与表一一对应;可追溯到 §2 决策 -->
-
 ---
 
 ## 4. 方案详细设计 (Detailed Design)
 
-<!-- 实现级细节。标杆对齐 scenario-job-compile §4:设计要点 → Happy Path → 业务场景(+说明) → 数据/接口等。
-     可追溯到 §5 验收标准与 §2 决策。不涉及的类别显式「不涉及 X」。 -->
-
 ### 4.1 设计要点一览
 
-<!-- 从 design 决策提炼 P1…Pn;实现时不可推翻的不变量。 -->
-
-| 编号 | 要点 | 说明 |
-|------|------|------|
-| P1 | | |
-
 ### 4.2 核心业务时序 · Happy Path(强制)
 
-<!-- 成功路径完整 Mermaid sequenceDiagram(建议 autonumber);覆盖主角色从发起到成功终态。
-     图后必须有「设计要点」说明(不变式、失败不在本图展开的边界)。 -->
-
-**目的**: …
-
-```mermaid
-sequenceDiagram
-  autonumber
-  %% Happy Path:成功路径完整时序
-```
-
-**设计要点**:
-
-- …
-
 ### 4.3 业务场景时序
 
-<!-- 每个关键业务场景一小节:目的 + sequenceDiagram/flowchart/stateDiagram + 设计要点说明。
-     至少覆盖本变更核心分支(失败/幂等/兼容缺省等);禁止有图无说明。 -->
-
-#### 场景 A · `<名称>`
-
-**目的**: …
-
-```mermaid
-sequenceDiagram
-  autonumber
-```
-
-**设计要点**:
-
-- …
-
 ### 4.4 数据结构 / 数据模型变更 (Data Structures)
 
-<!-- 库表硬门槛 + DB guidance pack:init 安装到 {ide}/specflow/guidance/database/;
-     路由见 prompts/approval/database-guidance.md。总则表填写实际「DB 技能」路径。
-     大纲硬门槛:仅 4.4.1–4.4.4 + ##### 表名;DDL/字段说明/JSON 用 **加粗**,禁止再开标题。 -->
+<!-- 顺序:项目约定(database) → SpecFlow DB guidance → 现网 DDL。
+     总则必填「项目约定」「DB 技能」「DDL 来源」。优先级:项目>guidance>LLM。 -->
 
 #### 4.4.1 总则与本迭代结构变更结论
 
 | 项 | 结论 |
 |----|------|
-| 数据库迁移 | <有 / 本迭代零迁移> |
-| 新建表 | <表名 / 无> |
-| 新增/修改/删除列 | <清单 / 无> |
-| 新增索引 | <清单 / 无> |
-| DDL 来源 | <migrations 路径 / 本迭代新增> |
-| DB 技能 | <.cursor|…/guidance/database/mysql 或 LLM-fallback> |
-
-```sql
--- 本迭代变更语句
-```
+| 数据库迁移 | |
+| 新建表 | |
+| 新增/修改/删除列 | |
+| 新增索引 | |
+| DDL 来源 | |
+| 项目约定 | <path / 未发现> |
+| DB 技能 | <guidance 路径 / LLM-fallback> |
 
 #### 4.4.2 ER 图(核心实体关系)
 
-```mermaid
-erDiagram
-```
-
-**图说明**:
-
-| 表名 | 中文名 | 职责(一句话) | 结构 | 本迭代动作 |
-|------|--------|--------------|------|------------|
-| | | | | |
-
 #### 4.4.3 逐表详设
 
-##### `<table_name>`(中文名)
-
-**本迭代动作**: …
-
-**本迭代变更语句**: …
-
-**DDL(现网/目标)**:
-
-```sql
-CREATE TABLE `table_name` (
-  ...
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
-  COMMENT='...';
-```
-
-**字段说明**:
-
-| 字段名称 | 字段类型 | 是否有默认值 | 字段说明 | 本迭代用法 |
-|----------|----------|--------------|----------|------------|
-| | | | | |
-
-<!-- 可选:**JSON 形状 · runtime_payload** + 形状表/代码块 — 仍用加粗,不要 ##### -->
-
 #### 4.4.4 非表字段、数据迁移与回滚兼容
 
-| 项 | 说明 |
-|----|------|
-| 协议/计算字段(不落库) | |
-| **存量数据默认值填充策略**(G3) | JSON 变更或新增列时必填 |
-| 结构回滚 | |
-| **回滚数据兼容**(G4) | 旧代码能否安全忽略新数据(`omitempty` / `schema_version` 等) |
-| 数据保留 | |
-
 ### 4.5 接口设计 (Interface Design)
 
-<!-- 硬门槛:通道 → 清单 → 错误约定 → 逐接口字段/示例/错误表 → 调用关系。
-     大纲硬门槛:仅 4.5.1–4.5.3 + ##### In;请求体字段/示例/错误用 **加粗**,禁止再开标题。
-     详见 generate.md §4.5。 -->
-
-#### 4.5.1 总览与约定
-
-**调用方与通道**:
-
-| 通道 | 路径前缀 / 入口 | 调用方 | 鉴权 |
-|------|-----------------|--------|------|
-| | | | |
-
-**本迭代接口清单**:
+<!-- 起草前:project-conventions-guidance.md topic=api。
+     大纲仅 4.5.1–4.5.3 + ##### In;字段/示例用加粗。 -->
 
-| 编号 | 接口 | 变更类型 | 应用场景 |
-|------|------|----------|----------|
-| I1 | | 新增/修改/行为扩展/不变(本迭代消费) | |
+### 4.6 前端 / UI 设计 (Frontend / UI Design)
 
-**通用错误码约定**:
+<!-- 仅 uiInScope=yes。起草前:topic=frontend + frontend-guidance.md §3
+     (强制扫 IDE skills/rules + 落地文档 ≤5)。大纲仅 4.6.1–4.6.5 + ##### Page。G5/G6。 -->
 
-| 错误类别 / 状态 | 典型 HTTP 或退出码 | 含义(本迭代) |
-|-----------------|-------------------|--------------|
-| | | |
+#### 4.6.1 总则与本迭代结论
 
-#### 4.5.2 逐接口详设
-
-##### I1 · `<短名>`(`<变更类型>`)
-
-**元信息**:
-
-| 项 | 内容 |
+| 项 | 结论 |
 |----|------|
-| 应用场景 | |
-| 协议 | |
-| 本迭代变更 | |
-
-**请求体字段**:
-
-| 字段 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| | | | | |
-
-**请求示例**: …
-
-**成功响应字段**: …
-
-**响应示例(成功)**: …
-
-**响应示例(失败)** *(G2 强制)*: …
+| Surface | |
+| Framework | |
+| Styling / 设计系统 | |
+| State | |
+| UI kit | |
+| FE testing | |
+| 本迭代页面 | |
+| 项目约定 | <path / 未发现> |
+| IDE skills/rules | <path / 未发现> |
 
-**错误**:
+#### 4.6.2 信息架构与路由
 
-| 条件 | 状态 / 退出码 | 说明 |
-|------|---------------|------|
-| | | |
+#### 4.6.3 关键页面 / 组件详设
 
-#### 4.5.3 调用关系
+#### 4.6.4 状态与数据获取
 
-```text
-调用方: I1 → …
-```
+#### 4.6.5 视觉与验证回路
 
-### 4.6 核心算法 / 逻辑说明 (Core Logic)
+### 4.7 核心算法 / 逻辑说明 (Core Logic)
 
-<!-- 不涉及则写:不涉及非平凡算法(逻辑简单,无复杂数据处理)。 -->
+### 4.8 配置与运行环境 (Configuration & Runtime)
 
-### 4.7 配置与运行环境 (Configuration & Runtime)
-
-<!-- 不涉及则写:不涉及配置或运行环境变更。 -->
-
-### 4.8 兼容性与迁移 (Compatibility & Migration)
-
-<!-- 含 G3 存量填充、G4 回滚数据兼容;无风险也须一句话声明「无新旧数据互读问题」。
-     不涉及则写:不涉及破坏性变更(向后兼容);无新形状写入,回滚仅回退应用即可。 -->
+### 4.9 兼容性与迁移 (Compatibility & Migration)
 
 ---
 
 ## 5. 验收标准 (Acceptance Criteria)
 
-<!-- 放在架构与详细设计之后:开发先读怎么做,再对照契约验收。
-     按 capability 列出全部 Requirement + Scenario,3 级可测试性。来源 specs/**/*.md。 -->
+<!-- 可选:用户确认「要」才输出本整章;否则删除本节。 -->
 
 ### 5.1 Capability: <name>
 
-<!-- Delta 操作类型: ADDED / MODIFIED / REMOVED / RENAMED -->
-
-#### Requirement: <name>
-
 | Scenario | WHEN | THEN | 可测试性 | 说明 |
 |----------|------|------|---------|------|
-| <name> | <条件> | <期望> | ✅ 功能可测试 / ⚠️ 文档可测试 / ❌ 不可测试 | |
+| | | | | |
 
 ---
 
@@ -390,22 +173,18 @@ CREATE TABLE `table_name` (
 
 | 测试层级 | 覆盖对象 | 工具/框架 | 目标(证明什么) | 覆盖的验收标准 |
 |---------|---------|----------|---------------|---------------|
-| 单元测试 | 核心函数/类 | <框架> | 逻辑正确、边界处理 | §5 Scenario 引用 |
-| 集成测试 | 模块交互/接口契约 | <框架> | 协作正确、契约一致 | §5 Scenario 引用 |
-| 验收测试 | spec 的 WHEN/THEN | <E2E/CLI> | 逐 Scenario 验证行为 | §5 核心 Scenario |
-| 回归测试 | 主 specs 基线 | <框架> | 不破坏已有功能 | 主 specs |
-| 性能/安全/兼容 | 如适用 | <工具> | NFR 目标 | NFR |
+| | | | | 有 §5 则引 Scenario;无 §5 则引 specs 名 |
 
 ### 6.2 测试环境与数据
 
 ### 6.3 测试策略自检
 
-**不涉及测试变更时写**:`不涉及测试变更(纯文档/配置变更,无行为逻辑需要测试)`。
-
 ---
 
 ## 7. 部署/发布/回滚方案 (Deployment & Release)
 
+<!-- 可选:用户确认「要」才输出本整章;否则删除本节。 -->
+
 ### 7.1 部署方案 (Deployment)
 
 ### 7.2 发布策略 (Release Strategy)
@@ -416,14 +195,11 @@ CREATE TABLE `table_name` (
 
 ### 7.5 部署方案自检
 
-**不涉及运行时部署时写**:`不涉及运行时部署(纯库/CLI/文档项目,无服务上线,变更通过包发布/版本发布交付)`。
-
 ---
 
 ## 8. 闭环性检查 (Closed-Loop Verification)
 
-<!-- 简练输出:一张表即可。PASS/SKIPPED 一句话证据;WARNING/FAIL 最多 2–3 条要点。
-     禁止每个 Pass 开长小节、禁止再贴第二张总评表。内部分析仍跑满 Pass 1–7。 -->
+<!-- 可选:用户确认「要」才输出。内部分析仍必跑 Pass 1–7,结论在对话反馈。 -->
 
 | Pass | 检查项 | 结论 | 关键证据(一句话;⚠️/❌ 可列 2–3 条要点) |
 |------|--------|------|--------------------------------------|
@@ -457,12 +233,9 @@ CREATE TABLE `table_name` (
 
 ## 10. 审批意见 (Approval Decision)
 
-### 10.1 AI 预审建议
-
-**建议:** 建议批准 / 有条件批准 / 退回 refine / 拒绝
-**理由:**
+<!-- 禁止写入 AI 预审建议;仅人工签字栏。 -->
 
-### 10.2 人工审批签字栏
+### 10.1 人工审批签字栏
 
 | 角色 | 姓名 | 审批结论 | 日期 | 意见 |
 |------|------|---------|------|------|
@@ -470,7 +243,7 @@ CREATE TABLE `table_name` (
 | 产品负责人 | | □ 批准 □ 退回 □ 拒绝 | | |
 | 架构师 | | □ 批准 □ 退回 □ 拒绝 | | |
 
-> 审批结论填写说明:批准 → 可执行 `/specflow:apply`;退回 → 执行 `/specflow:refine` 修复后重新审批;拒绝 → 废弃本次 change。
+> 批准 → `/specflow:apply`;退回 → `/specflow:refine`;拒绝 → 废弃本次 change。
 
 ---
 
@@ -478,13 +251,11 @@ CREATE TABLE `table_name` (
 
 | 章节 | 数据来源 | 处理方式 |
 |------|---------|---------|
-| 绪论与边界 | 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;**正文只输出一张结论表** |
-| 可实施性评估 | tasks + design + specs + 代码 | AI 推理 |
-| 审批意见 | 三重 verdict | AI 预审 + 人工签字栏 |
+| 绪论与边界 | proposal + explore(可选) | AI 提炼 |
+| 技术方案评估 | design + 用户确认选型(若有) | 约束 + **技术选型(绿场/补缺)** + 决策/风险/质量 |
+| 架构 / 详细设计 | design + specs + 锚点 + FE 约定(若有 UI) | 图+要点+数据/接口/**前端** |
+| 验收标准 | specs | **可选** |
+| 测试策略 | §5 或 specs 名 | 分层矩阵 |
+| 部署/闭环 | 运行环境 / Pass 1–7 | **可选** |
+| 可实施性 | 四件套+代码 | 写入文档 |
+| 审批意见 | 人工 | 仅签字栏 |