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

package/templates/approval.md

@@ -0,0 +1,390 @@
+<!--
+  Approval document template (v2 — grounded & quality-guarded).
+  Generated by /specflow:approval after refine converges (phase=refined).
+  This is an OPTIONAL artifact — it does not affect phase, apply gate, or archive.
+
+  The actual document is AI-generated; this template defines the section structure.
+  v2 additions vs v1:
+  - Pass 6 (Code Grounding) and Pass 7 (Baseline Cross-Check)
+  - Design Quality section (over-engineering + extensibility)
+  - Implementability expanded to 7 dimensions (added architecture consistency + implementation risk)
+  - Scenario testability uses 3-level grading (functional / document / untestable)
+  - Dashboard includes anchor files, baseline specs, tech stack, design-quality signals
+-->
+
+# 技术方案审批文档: <change-name>
+
+> 本文档由 `/specflow:approval` 基于 refine 收敛后的四件套 + 现有代码与 spec 基线生成,
+> 经 AI 7 维闭环检查、架构整体设计、方案详细设计、测试策略、部署/发布/回滚、设计质量评估与可实施性评估,供人工审批使用。
+> 生成时间: YYYY-MM-DD HH:MM | phase: refined | 产物语言: <en|zh-CN> | 技术栈: <stack>
+
+---
+
+## 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 估算。
+
+---
+
+## 2. 变更摘要 (Executive Summary)
+
+### 2.1 为什么做 (Why)
+<!-- 2-3 句话提炼 proposal.md 的 Why -->
+
+### 2.2 做什么 (What Changes)
+<!-- 按 新增/修改/移除/重命名 分类,标注 BREAKING -->
+
+### 2.3 影响面 (Impact)
+<!-- 整合 proposal.md Impact,AI 评估影响等级 -->
+
+---
+
+## 3. 验收标准 (Acceptance Criteria)
+
+<!-- 按 capability 分组,完整列出所有 Requirement + Scenario,3 级可测试性标注。
+     这里的内容来自 specs/**/*.md,是 /specflow:verify 将检查的契约。 -->
+
+### 3.1 Capability: <name>
+
+<!-- Delta 操作类型: ADDED / MODIFIED / REMOVED / RENAMED -->
+
+#### Requirement: <name>
+<!-- requirement 描述 -->
+
+| Scenario | WHEN | THEN | 可测试性 | 说明 |
+|----------|------|------|---------|------|
+| <name> | <条件> | <期望> | ✅ 功能可测试 / ⚠️ 文档可测试 / ❌ 不可测试 | <!-- 仅 ⚠️/❌ 时填写原因 --> |
+
+---
+
+## 4. 技术方案评估 (Technical Design Review)
+
+### 4.1 现状与约束 (Context & Constraints)
+<!-- 整合 design.md Context + AI 补充的隐含约束 -->
+
+### 4.2 目标与非目标 (Goals & Non-Goals)
+<!-- 整合 design.md Goals/Non-Goals -->
+
+### 4.3 决策评审表 (Decision Review)
+
+<!-- 包含 design.md 中的每一个决策 -->
+
+| 决策 | 选定方案 | 备选方案 | 理由 | 影响评估 | 状态 |
+|------|---------|---------|------|---------|------|
+| D1: <name> | <方案> | <A/B> | <理由> | <评估> | Proposed |
+
+### 4.4 风险与权衡 (Risks & Trade-offs)
+
+<!-- design 识别的风险 + AI 识别的未声明风险 -->
+
+| 风险 | 严重等级 | 缓解措施 | 就绪度 |
+|------|---------|---------|--------|
+| <name> | 高/中/低 | <措施> | ✅ 已缓解 / ⚠️ 待落实 / ❌ 未识别 |
+
+### 4.5 设计质量评估 (Design Quality)
+
+#### 过度设计检查
+
+| # | 信号 | 检测到? | 证据(design/tasks 位置) |
+|---|------|--------|----------------------|
+| 1 | 为未提出的需求设计接口 | ✅是/❌否 | <!-- 若是,引用 design 章节 --> |
+| 2 | 不必要的抽象层 | | |
+| 3 | 预建未使用的基础设施 | | |
+| 4 | 配置项超出当前需求 | | |
+| 5 | 复杂度超出问题规模 | | |
+
+**过度设计结论:** PASS (0 signals) / WARNING (1-2) / FAIL (3+)
+
+#### 扩展性评估
+
+| # | 信号 | 检测到? | 证据(design 位置) |
+|---|------|--------|----------------|
+| 1 | 命名空间预留 | | |
+| 2 | 接口稳定,实现可替换 | | |
+| 3 | 显式 Non-Goals | | |
+| 4 | 向后兼容路径 | | |
+| 5 | 决策理由提及扩展性权衡 | | |
+
+**扩展性结论:** PASS (4-5) / WARNING (0-3)
+
+**设计质量总评:** PASS / WARNING / FAIL
+<!-- 特别:过度设计 WARNING/FAIL + 扩展性 WARNING → 升级 FAIL -->
+
+---
+
+## 5. 架构整体设计 (Architecture Design)
+
+<!-- 回答"系统由哪些模块组成、模块间如何依赖与交互、每个模块职责与边界"。聚焦宏观结构,与 §6 详细设计(模块内部实现)互补。 -->
+
+### 5.1 总体架构 (Architecture Overview)
+
+<!-- 用 Mermaid 图绘制系统交互图或模块依赖图。
+     图型:模块依赖图/分层架构图用 flowchart LR;系统交互图用 sequenceDiagram。
+     要求:标注新增/修改模块(让影响面一眼可见);边标注依赖方向或交互消息;
+          纯 CLI/库项目模块 = src/core/*、src/cli/*;Web = 服务/组件;多仓 = 仓库/服务。
+     不涉及则写:不涉及架构变更(单模块/单文件调整,模块边界无变化)。 -->
+
+```mermaid
+<!-- 在此放置模块依赖图或系统交互图 -->
+```
+
+### 5.2 核心组件说明 (Core Components)
+
+<!-- 表格定义每个模块/组件职责与边界。边界要写"不做什么",防止逻辑放错模块。 -->
+
+| 组件 | 职责 | 边界(做什么 / 不做什么) | 依赖 | 变更类型 |
+|------|------|-------------------------|------|---------|
+| `<组件名>` | 一句话职责 | 做什么;不做什么 | 依赖的组件 | 新增/修改/不变 |
+
+<!-- 要求:列出变更涉及的所有组件(新增+修改);边界写"不做什么";依赖方向明确避免循环;
+     与 §5.1 图一一对应;组件边界可追溯到 §4 决策。 -->
+
+### 5.3 架构一致性自检
+
+<!-- - 图标注了新增/修改模块
+     - 每个组件有"不做什么"的边界
+     - 图与表一一对应(表依赖与图边一致)
+     - 组件边界可追溯到 §4 决策
+     - 未涉及架构变更时显式标注 -->
+
+---
+
+## 6. 方案详细设计 (Detailed Design)
+
+<!-- 方案从宏观决策落到实现级细节。只呈现本变更涉及的部分;不涉及的类别显式标注"不涉及 X"而非留空。
+     每个元素须可追溯到 §3 验收标准和 §4 决策。若无法写出实现级细节,标记 [待 refine 澄清: <元素>]。 -->
+
+### 6.1 数据结构 / 数据模型变更 (Data Structures)
+
+<!-- 涉及持久化/状态/配置结构时:表结构、字段、类型、约束、索引建议(由查询驱动)、数据迁移、回滚。
+     纯 CLI/库项目覆盖配置结构 / 状态文件 / YAML schema。
+     不涉及则写:不涉及数据库变更(纯逻辑/CLI 变更,无持久化数据模型)。 -->
+
+### 6.2 接口设计 (Interface Design)
+
+<!-- 涉及 API/RPC/CLI 命令/函数接口时:签名、入参(参数/类型/必选/合法值/默认值)、出参(类型/结构)、错误码(枚举/含义/状态码映射)。
+     项目类型适配:CLI→commander 参数;库→导出函数签名;Web→HTTP API。
+     不涉及则写:不涉及接口变更(内部实现调整,无对外/跨模块接口变化)。 -->
+
+### 6.3 业务流程 (Business Flow)
+
+<!-- 涉及状态流转/多步骤/并发时序时:时序说明(谁调用谁、顺序、分支、异常路径)或状态机流转(状态/迁移事件/条件/终态)。
+     可用 Mermaid sequenceDiagram / stateDiagram-v2。
+     不涉及则写:不涉及复杂业务流程(单步/线性实现,无状态流转)。 -->
+
+### 6.4 核心算法 / 逻辑说明 (Core Logic)
+
+<!-- 涉及非平凡算法/数据处理时:输入输出、处理步骤、复杂度、边界条件。
+     不涉及则写:不涉及非平凡算法(逻辑简单,无复杂数据处理)。 -->
+
+### 6.5 配置与运行环境 (Configuration & Runtime)
+
+<!-- 涉及新配置项/环境变量/运行时依赖时:名称、类型、默认值、生效时机、用途。
+     不涉及则写:不涉及配置或运行环境变更。 -->
+
+### 6.6 兼容性与迁移 (Compatibility & Migration)
+
+<!-- 涉及破坏性变更时:旧行为→新行为映射、迁移路径、回滚方案。
+     不涉及则写:不涉及破坏性变更(向后兼容)。 -->
+
+<!-- 详细设计质量自检:每个元素可追溯到 §3;每个选择引用 §4 决策;涉及类别均非留空;未涉及类别显式标注。 -->
+
+---
+
+## 7. 测试策略 (Test Strategy)
+
+<!-- 从"§3 验收标准可不可测"升级为"用分层测试证明方案正确"。
+     只列出本变更实际需要的测试层级;不涉及的层级显式标注"不涉及"。 -->
+
+### 7.1 分层测试矩阵
+
+<!-- 每个测试层级映射到 §3 验收标准(引用 Scenario 名);标注工具/框架;目标可验证。 -->
+
+| 测试层级 | 覆盖对象 | 工具/框架 | 目标(证明什么) | 覆盖的验收标准 |
+|---------|---------|----------|---------------|---------------|
+| 单元测试 | 核心函数/类 | <框架> | 逻辑正确、边界处理 | §3 Scenario 引用 |
+| 集成测试 | 模块交互/接口契约 | <框架> | 协作正确、契约一致 | §3 Scenario 引用 |
+| 验收测试 | spec 的 WHEN/THEN | <E2E/CLI> | 逐 Scenario 验证行为 | §3 核心 Scenario |
+| 回归测试 | 主 specs 基线 | <框架> | 不破坏已有功能 | 主 specs |
+| 性能/安全/兼容 | 如适用 | <工具> | NFR 目标 | NFR |
+
+### 7.2 测试环境与数据
+
+<!-- 环境/数据/并行隔离/覆盖率目标 -->
+
+### 7.3 测试策略自检
+
+<!-- - 每个 §3 验收标准至少被一个测试层级覆盖
+     - 每个层级有工具、可验证目标
+     - 既有行为有回归测试保护
+     - 新增测试与修改既有测试已区分 -->
+
+**不涉及测试变更时写**:`不涉及测试变更(纯文档/配置变更,无行为逻辑需要测试)`。
+
+---
+
+## 8. 部署/发布/回滚方案 (Deployment & Release)
+
+<!-- 对有运行系统的项目必须;纯库/CLI/文档项目可显式标注"不涉及运行时部署"。 -->
+
+### 8.1 部署方案 (Deployment)
+
+<!-- 部署目标/方式/顺序/配置管理/环境差异 -->
+
+### 8.2 发布策略 (Release Strategy)
+
+<!-- 发布方式(蓝绿/金丝雀/滚动)/发布窗口/新旧兼容 -->
+
+### 8.3 回滚方案 (Rollback)
+
+<!-- 回滚触发条件/方式/数据一致性/回滚验证 -->
+
+### 8.4 监控与可观测性 (Monitoring & Observability)
+
+<!-- 关键指标/日志追踪/告警 -->
+
+### 8.5 部署方案自检
+
+<!-- - 部署目标/方式/顺序明确
+     - 发布策略与兼容性说明
+     - 回滚触发/方式/数据一致性/验证明确
+     - 上线后监控指标与告警明确 -->
+
+**不涉及运行时部署时写**:`不涉及运行时部署(纯库/CLI/文档项目,无服务上线,变更通过包发布/版本发布交付)`。
+
+---
+
+## 9. 闭环性检查 (Closed-Loop Verification)
+
+### Pass 1: 需求闭环 (Requirement Closure)
+<!-- proposal What Changes ↔ specs 覆盖 -->
+**Verdict:** PASS / WARNING / FAIL
+**证据:** <!-- 覆盖表 -->
+
+### Pass 2: 方案闭环 (Design Closure)
+<!-- design decisions ↔ spec requirements 双向追溯 -->
+**Verdict:** PASS / WARNING / FAIL
+**证据:**
+
+### Pass 3: 规格闭环 (Spec Closure)
+<!-- scenario 完整性 + 3 级可测试性 + delta 结构 -->
+**Verdict:** PASS / WARNING / FAIL
+**证据:**
+
+### Pass 4: 实施闭环 (Implementation Closure)
+<!-- tasks ↔ spec requirements 覆盖 + 粒度 + 占位符 -->
+**Verdict:** PASS / WARNING / FAIL
+**证据:**
+
+### Pass 5: 风险闭环 (Risk Closure)
+<!-- risks ↔ mitigations + BREAKING migration + 未识别风险 -->
+**Verdict:** PASS / WARNING / FAIL
+**证据:**
+
+### Pass 6: 代码落地性 (Code Grounding)
+<!-- 读取锚点文件(只读文件本身),验证存在性 + 结构兼容性 + 技术栈一致性 -->
+**Verdict:** PASS / WARNING / FAIL / SKIPPED (greenfield — no existing code)
+**证据:**
+
+| 锚点文件 | 存在? | 计划动作 | 结构兼容性 |
+|---------|------|---------|-----------|
+| <path> | ✅/❌ | extend/create/modify | <!-- 具体发现:函数名/模块模式/导出形态 --> |
+
+**技术栈一致性:** <!-- 一行结论 + 理由 -->
+
+### Pass 7: 基线对照 (Baseline Cross-Check)
+<!-- delta specs ↔ specflow/specs/ 主基线:冲突/重复/MODIFIED 名称匹配 -->
+**Verdict:** PASS / WARNING / FAIL / SKIPPED (no baseline — greenfield or no archived changes yet)
+**证据:**
+
+| Capability | Requirement | 操作 | 基线状态 | 结论 |
+|-----------|-------------|------|---------|------|
+| <name> | <name> | ADDED/MODIFIED/REMOVED/RENAMED | exists/duplicate/not-found | ✅/⚠️/❌ |
+
+### 闭环性总评
+
+| 维度 | 结论 |
+|------|------|
+| Pass 1 需求闭环 | ✅/⚠️/❌/⊘(skipped) |
+| Pass 2 方案闭环 | |
+| Pass 3 规格闭环 | |
+| Pass 4 实施闭环 | |
+| Pass 5 风险闭环 | |
+| Pass 6 代码落地性 | |
+| Pass 7 基线对照 | |
+
+**整体闭环性:** PASS / PASS WITH WARNINGS / FAIL
+
+---
+
+## 10. 可实施性评估 (Implementability Assessment)
+
+| 评估维度 | 结论 | 说明 |
+|---------|------|------|
+| 完整性 | READY / NEEDS REFINEMENT / BLOCKED | <!-- 无 TODO/占位符 --> |
+| 规格对齐 | | <!-- tasks 覆盖所有 spec 需求 --> |
+| 任务可执行性 | | <!-- 工程师可无歧义执行 --> |
+| 技术可行性 | | <!-- 当前技术栈可实现 --> |
+| 依赖明确性 | | <!-- 任务依赖、外部依赖清晰 --> |
+| 架构一致性 | | <!-- 基于 Pass 6 代码读取:技术栈/目录结构/错误模式/测试框架 --> |
+| 实施风险 | | <!-- 核心模块/数据迁移/并发/外部接口/团队技术栈匹配 --> |
+
+**可实施性总评:** READY / NEEDS REFINEMENT / BLOCKED
+
+---
+
+## 11. 审批意见 (Approval Decision)
+
+### 7.1 AI 预审建议
+
+**建议:** 建议批准 / 有条件批准 / 退回 refine / 拒绝
+**理由:** <!-- 1-2 句话,引用闭环性/设计质量/可实施性三重 verdict -->
+
+### 7.2 人工审批签字栏
+
+<!-- 签字栏留空,由审批人填写。 -->
+
+| 角色 | 姓名 | 审批结论 | 日期 | 意见 |
+|------|------|---------|------|------|
+| 技术负责人 | | □ 批准 □ 退回 □ 拒绝 | | |
+| 产品负责人 | | □ 批准 □ 退回 □ 拒绝 | | |
+| 架构师 | | □ 批准 □ 退回 □ 拒绝 | | |
+
+> 审批结论填写说明:批准 → 可执行 `/specflow:apply`;退回 → 执行 `/specflow:refine` 修复后重新审批;拒绝 → 废弃本次 change。
+
+---
+
+## 附录 A: 产物溯源
+
+| 章节 | 数据来源 | 处理方式 |
+|------|---------|---------|
+| 变更概览 | .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 预审 + 人工签字栏 |