@gordon.gan/specflow 1.3.3-beta → 1.4.1

package/templates/approval.md

@@ -0,0 +1,464 @@
+<!--
+  Approval document template (v3 — implementer-first narrative).
+  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 (契约放在开发设计讲完之后)
+  6. 测试策略
+  7. 部署/发布/回滚
+  8. 闭环性检查
+  9. 可实施性评估
+  10. 审批意见
+
+  Quality Gates (G1–G4) + Style & Tone: see prompts/approval/generate.md Part E;
+  enforced on every generated approval.md.
+-->
+
+# 技术方案审批文档: <change-name>
+
+> 本文档由 `/specflow:approval` 基于 refine 收敛后的四件套 + 现有代码与 spec 基线生成,
+> 经 AI 7 维闭环检查、架构整体设计、方案详细设计、测试策略、部署/发布/回滚、设计质量评估与可实施性评估,供人工审批使用。
+> 生成时间: YYYY-MM-DD HH:MM | phase: refined | 产物语言: <en|zh-CN> | 技术栈: <stack>
+
+> **质量红线(生成时必须满足)**:G1 超 5 行流程→Mermaid · G2 接口须有失败示例 · G3 JSON/新列须有存量填充策略 · G4 须有回滚数据兼容说明。文风:通俗、缩写首次注解、禁用「尽量/大概/一般情况下」。
+
+---
+
+## 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)
+
+| 决策 | 选定方案 | 备选方案 | 理由 | 影响评估 | 状态 |
+|------|---------|---------|------|---------|------|
+| D1: <name> | <方案> | <A/B> | <理由> | <评估> | Proposed |
+
+### 2.4 风险与权衡 (Risks & Trade-offs)
+
+| 风险 | 严重等级 | 缓解措施 | 就绪度 |
+|------|---------|---------|--------|
+| <name> | 高/中/低 | <措施> | ✅ 已缓解 / ⚠️ 待落实 / ❌ 未识别 |
+
+### 2.5 设计质量评估 (Design Quality)
+
+#### 过度设计检查
+
+| # | 信号 | 检测到? | 证据(design/tasks 位置) |
+|---|------|--------|----------------------|
+| 1 | 为未提出的需求设计接口 | ✅是/❌否 | |
+| 2 | 不必要的抽象层 | | |
+| 3 | 预建未使用的基础设施 | | |
+| 4 | 配置项超出当前需求 | | |
+| 5 | 复杂度超出问题规模 | | |
+
+**过度设计结论:** PASS / WARNING / FAIL
+
+#### 扩展性评估
+
+| # | 信号 | 检测到? | 证据(design 位置) |
+|---|------|--------|----------------|
+| 1 | 命名空间预留 | | |
+| 2 | 接口稳定,实现可替换 | | |
+| 3 | 显式 Non-Goals | | |
+| 4 | 向后兼容路径 | | |
+| 5 | 决策理由提及扩展性权衡 | | |
+
+**扩展性结论:** PASS / WARNING
+
+**设计质量总评:** PASS / WARNING / FAIL
+
+---
+
+## 3. 架构整体设计 (Architecture Design)
+
+<!-- 宏观结构;标杆对齐 scenario-job-compile §3:图 + 图要点说明 + 组件职责边界。
+     与 §4 详细设计互补。不涉及则写:不涉及架构变更(单模块/单文件调整,模块边界无变化)。 -->
+
+### 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 技能路由:命中 skills/database/<stack> 则 Read 补强;
+     未命中 LLM-fallback。总则表填写「DB 技能」列。详见 prompts/approval/database-guidance.md。 -->
+
+#### 4.4.1 总则与本迭代结构变更结论
+
+| 项 | 结论 |
+|----|------|
+| 数据库迁移 | <有 / 本迭代零迁移> |
+| 新建表 | <表名 / 无> |
+| 新增/修改/删除列 | <清单 / 无> |
+| 新增索引 | <清单 / 无> |
+| DDL 来源 | <migrations 路径 / 本迭代新增> |
+| DB 技能 | <skills/database/mysql|…(本地) / LLM-fallback> |
+
+```sql
+-- 本迭代变更语句
+```
+
+#### 4.4.2 ER 图(核心实体关系)
+
+```mermaid
+erDiagram
+```
+
+**图说明**:
+
+| 表名 | 中文名 | 职责(一句话) | 结构 | 本迭代动作 |
+|------|--------|--------------|------|------------|
+| | | | | |
+
+#### 4.4.3 逐表详设
+
+##### `<table_name>`(中文名)
+
+**本迭代动作**: …
+**本迭代变更语句**: …
+
+```sql
+CREATE TABLE `table_name` (
+  ...
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+  COMMENT='...';
+```
+
+| 字段名称 | 字段类型 | 是否有默认值 | 字段说明 | 本迭代用法 |
+|----------|----------|--------------|----------|------------|
+| | | | | |
+
+#### 4.4.4 非表字段、数据迁移与回滚兼容
+
+| 项 | 说明 |
+|----|------|
+| 协议/计算字段(不落库) | |
+| **存量数据默认值填充策略**(G3) | JSON 变更或新增列时必填 |
+| 结构回滚 | |
+| **回滚数据兼容**(G4) | 旧代码能否安全忽略新数据(`omitempty` / `schema_version` 等) |
+| 数据保留 | |
+
+### 4.5 接口设计 (Interface Design)
+
+<!-- 硬门槛:通道 → 清单 → 错误约定 → 逐接口字段/示例/错误表 → 调用关系。详见 generate.md §4.5。 -->
+
+#### 4.5.1 总览与约定
+
+**调用方与通道**:
+
+| 通道 | 路径前缀 / 入口 | 调用方 | 鉴权 |
+|------|-----------------|--------|------|
+| | | | |
+
+**本迭代接口清单**:
+
+| 编号 | 接口 | 变更类型 | 应用场景 |
+|------|------|----------|----------|
+| I1 | | 新增/修改/行为扩展/不变(本迭代消费) | |
+
+**通用错误码约定**:
+
+| 错误类别 / 状态 | 典型 HTTP 或退出码 | 含义(本迭代) |
+|-----------------|-------------------|--------------|
+| | | |
+
+#### 4.5.2 逐接口详设
+
+##### I1 · `<短名>`(`<变更类型>`)
+
+| 项 | 内容 |
+|----|------|
+| 应用场景 | |
+| 协议 | |
+| 本迭代变更 | |
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| | | | | |
+
+**请求示例** / **成功响应示例** / **失败示例(G2 强制)** / **错误表** …
+
+#### 4.5.3 调用关系
+
+```text
+调用方: I1 → …
+```
+
+### 4.6 核心算法 / 逻辑说明 (Core Logic)
+
+<!-- 不涉及则写:不涉及非平凡算法(逻辑简单,无复杂数据处理)。 -->
+
+### 4.7 配置与运行环境 (Configuration & Runtime)
+
+<!-- 不涉及则写:不涉及配置或运行环境变更。 -->
+
+### 4.8 兼容性与迁移 (Compatibility & Migration)
+
+<!-- 含 G3 存量填充、G4 回滚数据兼容;无风险也须一句话声明「无新旧数据互读问题」。
+     不涉及则写:不涉及破坏性变更(向后兼容);无新形状写入,回滚仅回退应用即可。 -->
+
+---
+
+## 5. 验收标准 (Acceptance Criteria)
+
+<!-- 放在架构与详细设计之后:开发先读怎么做,再对照契约验收。
+     按 capability 列出全部 Requirement + Scenario,3 级可测试性。来源 specs/**/*.md。 -->
+
+### 5.1 Capability: <name>
+
+<!-- Delta 操作类型: ADDED / MODIFIED / REMOVED / RENAMED -->
+
+#### Requirement: <name>
+
+| Scenario | WHEN | THEN | 可测试性 | 说明 |
+|----------|------|------|---------|------|
+| <name> | <条件> | <期望> | ✅ 功能可测试 / ⚠️ 文档可测试 / ❌ 不可测试 | |
+
+---
+
+## 6. 测试策略 (Test Strategy)
+
+### 6.1 分层测试矩阵
+
+| 测试层级 | 覆盖对象 | 工具/框架 | 目标(证明什么) | 覆盖的验收标准 |
+|---------|---------|----------|---------------|---------------|
+| 单元测试 | 核心函数/类 | <框架> | 逻辑正确、边界处理 | §5 Scenario 引用 |
+| 集成测试 | 模块交互/接口契约 | <框架> | 协作正确、契约一致 | §5 Scenario 引用 |
+| 验收测试 | spec 的 WHEN/THEN | <E2E/CLI> | 逐 Scenario 验证行为 | §5 核心 Scenario |
+| 回归测试 | 主 specs 基线 | <框架> | 不破坏已有功能 | 主 specs |
+| 性能/安全/兼容 | 如适用 | <工具> | NFR 目标 | NFR |
+
+### 6.2 测试环境与数据
+
+### 6.3 测试策略自检
+
+**不涉及测试变更时写**:`不涉及测试变更(纯文档/配置变更,无行为逻辑需要测试)`。
+
+---
+
+## 7. 部署/发布/回滚方案 (Deployment & Release)
+
+### 7.1 部署方案 (Deployment)
+
+### 7.2 发布策略 (Release Strategy)
+
+### 7.3 回滚方案 (Rollback)
+
+### 7.4 监控与可观测性 (Monitoring & Observability)
+
+### 7.5 部署方案自检
+
+**不涉及运行时部署时写**:`不涉及运行时部署(纯库/CLI/文档项目,无服务上线,变更通过包发布/版本发布交付)`。
+
+---
+
+## 8. 闭环性检查 (Closed-Loop Verification)
+
+<!-- 简练输出:一张表即可。PASS/SKIPPED 一句话证据;WARNING/FAIL 最多 2–3 条要点。
+     禁止每个 Pass 开长小节、禁止再贴第二张总评表。内部分析仍跑满 Pass 1–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
+
+---
+
+## 9. 可实施性评估 (Implementability Assessment)
+
+| 评估维度 | 结论 | 说明 |
+|---------|------|------|
+| 完整性 | READY / NEEDS REFINEMENT / BLOCKED | |
+| 规格对齐 | | |
+| 任务可执行性 | | |
+| 技术可行性 | | |
+| 依赖明确性 | | |
+| 架构一致性 | | |
+| 实施风险 | | |
+
+**可实施性总评:** READY / NEEDS REFINEMENT / BLOCKED
+
+---
+
+## 10. 审批意见 (Approval Decision)
+
+### 10.1 AI 预审建议
+
+**建议:** 建议批准 / 有条件批准 / 退回 refine / 拒绝
+**理由:**
+
+### 10.2 人工审批签字栏
+
+| 角色 | 姓名 | 审批结论 | 日期 | 意见 |
+|------|------|---------|------|------|
+| 技术负责人 | | □ 批准 □ 退回 □ 拒绝 | | |
+| 产品负责人 | | □ 批准 □ 退回 □ 拒绝 | | |
+| 架构师 | | □ 批准 □ 退回 □ 拒绝 | | |
+
+> 审批结论填写说明:批准 → 可执行 `/specflow:apply`;退回 → 执行 `/specflow:refine` 修复后重新审批;拒绝 → 废弃本次 change。
+
+---
+
+## 附录 A: 产物溯源
+
+| 章节 | 数据来源 | 处理方式 |
+|------|---------|---------|
+| 绪论与边界 | 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 预审 + 人工签字栏 |