# 工作流优化方案 ## 一、背景与问题 ### 1.1 当前痛点 | 痛点 | 根因 | 影响 | |------|------|------| | 讨论 → 提案不一致 | 共识没有被"锁定" | AI 理解偏差，提案与讨论方案不同 | | 提案 → 实现不一致 | 约束没有被"强制执行" | 实现细节偏离设计 | | 后置测试浪费时间 | 测试从实现反推 | 测试乱写、调试时间长 | | 单测意义不大 | 测试实现细节而非行为 | 重构就挂，维护成本高 | | 频繁重构 | 问题发现太晚 | 大量返工（17次/100提交） | ### 1.2 数据支撑 - **重构提交**: 17 次（近期约 100 次提交中） - **典型完成率**: 75%（Shop Package Allocation: 91/121 tasks） - **未完成原因**: 测试（"低优先级，需要运行环境"） - **TODO 残留**: 10+ 个（代码中待完成的功能） --- ## 二、解决方案概览 ### 2.1 核心理念变化 ``` 旧工作流: discuss → proposal → design → tasks → implement → test → verify ↑ 测试后置 问题发现太晚 新工作流: discuss → 锁定共识 → proposal → 验证 → design → 验证 → 生成验收测试 → 实现（测试驱动）→ 验证 → 归档 ↑ ↑ 测试从 spec 生成 实现时对照测试 ``` ### 2.2 新增机制 | 机制 | 解决的问题 | 实现方式 | |------|-----------|---------| | **共识锁定** | 讨论→提案不一致 | `consensus.md` + 用户确认 | | **验收测试先行** | 测试后置浪费时间 | 从 Spec 生成测试，实现前运行 | | **业务流程测试** | 跨 API 场景验证 | 从 Business Flow 生成测试 | | **中间验证** | 问题发现太晚 | 每个 artifact 后自动验证 | | **约束检查** | 实现偏离设计 | 实现时对照约束清单 | --- ## 三、新工作流详解 ### 3.1 完整流程图 ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ Step 1: 探索 & 锁定共识 │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────┐ ┌──────────────────────┐ ┌─────────────────┐ │ │ │ /opsx:explore │ ──▶ │ 讨论并确认共识 │ ──▶ │ consensus.md │ │ │ └──────────────┘ │ AI 输出共识摘要 │ │ 用户确认后锁定 │ │ │ │ 用户逐条确认 ✓ │ └─────────────────┘ │ │ └──────────────────────┘ │ │ │ │ 输出: openspec/changes//consensus.md (用户签字确认版) │ └─────────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ Step 2: 生成提案 & 验证 │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────┐ ┌──────────────────────┐ ┌─────────────────┐ │ │ │ 读取 consensus │ ──▶ │ 生成 proposal.md │ ──▶ │ 自动验证 │ │ │ └──────────────┘ │ 必须覆盖共识要点 │ │ proposal 与 │ │ │ └──────────────────────┘ │ consensus 对齐 │ │ │ └─────────────────┘ │ │ │ │ 验证: 共识中的每个"要做什么"都在 proposal 的 Capabilities 中出现 │ └─────────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ Step 3: 生成 Spec │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────┐ ┌──────────────────────┐ │ │ │ 生成 spec.md │ ──▶ │ 包含两部分: │ │ │ │ │ │ 1. Scenarios │ │ │ │ │ │ 2. Business Flows │ │ │ └──────────────┘ └──────────────────────┘ │ │ │ │ Scenario: 单 API 的输入输出契约 │ │ Business Flow: 多 API 组合的业务场景 │ └─────────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ Step 4: 生成测试（关键变化！） │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────┐ ┌──────────────────────┐ ┌─────────────────┐ │ │ │ /opsx:gen-tests │ ──▶ │ 生成两类测试: │ ──▶ │ 运行测试 │ │ │ └──────────────┘ │ 1. 验收测试 │ │ 预期全部 FAIL │ │ │ │ 2. 流程测试 │ │ ← 证明测试有效 │ │ │ └──────────────────────┘ └─────────────────┘ │ │ │ │ 输出: │ │ - tests/acceptance/{capability}_acceptance_test.go │ │ - tests/flows/{capability}_{flow}_flow_test.go │ └─────────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ Step 5: 设计 & 实现（测试驱动） │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────┐ ┌──────────────────────┐ ┌─────────────────┐ │ │ │ 生成 design │ ──▶ │ 生成 tasks.md │ ──▶ │ 实现每个 task │ │ │ │ + 约束清单 │ │ 每个 task 关联测试 │ │ 运行对应测试 │ │ │ └──────────────┘ └──────────────────────┘ │ 测试通过才继续 │ │ │ └─────────────────┘ │ │ │ │ 实现循环: │ │ for each task: │ │ 1. 运行关联的测试 (预期 FAIL) │ │ 2. 实现代码 │ │ 3. 运行测试 (预期 PASS) │ │ 4. 测试通过 → 标记 task 完成 │ │ 5. 测试失败 → 修复代码，重复步骤 3 │ └─────────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ Step 6: 最终验证 & 归档 │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────┐ ┌──────────────────────┐ ┌─────────────────┐ │ │ │ 运行全部测试 │ ──▶ │ 生成完成报告 │ ──▶ │ 归档 change │ │ │ │ 必须 100% PASS │ │ 包含测试覆盖证据 │ └─────────────────┘ │ │ └──────────────┘ └──────────────────────┘ │ │ │ │ 完成报告必须包含: │ │ - 验收测试通过截图/日志 │ │ - 流程测试通过截图/日志 │ │ - 每个 Scenario/Flow 的测试对应关系 │ └─────────────────────────────────────────────────────────────────────────────┘ ``` ### 3.2 命令对照表 | 步骤 | 命令 | 说明 | |------|------|------| | 1 | `/opsx:explore` | 探索讨论 | | 2 | `/opsx:lock ` | **新** 锁定共识 | | 3 | `/opsx:new ` | 创建 change（自动读取 consensus） | | 4 | `/opsx:continue` | 生成 proposal | | 5 | `/opsx:continue` | 生成 spec | | 6 | `/opsx:gen-tests` | **新** 生成验收测试和流程测试 | | 7 | `/opsx:continue` | 生成 design | | 8 | `/opsx:continue` | 生成 tasks | | 9 | `/opsx:apply` | 测试驱动实现 | | 10 | `/opsx:verify` | 验证 | | 11 | `/opsx:archive` | 归档 | --- ## 四、测试体系重设计 ### 4.1 新测试金字塔 ``` ┌─────────────┐ │ E2E 测试 │ ← 手动/自动化 UI（很少） │ │ ─┴─────────────┴─ ┌─────────────────┐ │ 业务流程测试 │ ← 新增！多 API 组合 │ tests/flows/ │ 验证业务场景完整性 ─┴─────────────────┴─ ┌─────────────────────┐ │ 验收测试 │ ← 新增！从 Spec Scenario 生成 │ tests/acceptance/ │ 单 API 契约验证 ─┴─────────────────────┴─ ┌───────────────────────────┐ │ 集成冒烟测试 │ ← 保留 │ tests/integration/ │ ─┴───────────────────────────┴─ ┌─────────────────────────────────┐ │ 单元测试 (精简!) │ ← 大幅减少 │ tests/unit/ │ 仅复杂逻辑 └─────────────────────────────────┘ ``` ### 4.2 三层测试体系 | 层级 | 测试类型 | 来源 | 验证什么 | 位置 | |------|---------|------|---------|------| | **L1** | 验收测试 | Spec Scenario | 单 API 契约 | `tests/acceptance/` | | **L2** | 流程测试 | Spec Business Flow | 业务场景完整性 | `tests/flows/` | | **L3** | 单元测试 | 复杂逻辑 | 算法/规则正确性 | `tests/unit/` | ### 4.3 测试比例调整 | 测试类型 | 旧占比 | 新占比 | 变化 | |---------|-------|-------|------| | 验收测试 | 0% | **30%** | 新增 | | 流程测试 | 0% | **15%** | 新增 | | 集成测试 | 28% | 25% | 略减 | | 单元测试 | 72% | **30%** | 大幅减少 | ### 4.4 单元测试精简规则 **保留**: - ✅ 纯函数（计费计算、分佣算法） - ✅ 状态机（订单状态流转） - ✅ 复杂业务规则（层级校验、权限计算） - ✅ 边界条件（时间、金额、精度） **删除/不再写**: - ❌ 简单 CRUD（已被验收测试覆盖） - ❌ DTO 转换 - ❌ 配置读取 - ❌ 重复测试同一逻辑 --- ## 五、Spec 模板更新 ### 5.1 新 Spec 结构 ```markdown # {capability} Specification ## Purpose {简要描述这个能力的目的} ## Requirements ### Requirement: {requirement-name} {详细描述} #### Scenario: {scenario-name} - **GIVEN** {前置条件} - **WHEN** {触发动作} - **THEN** {预期结果} - **AND** {额外验证} --- ## Business Flows（新增必填部分） ### Flow: {flow-name} **参与者**: {角色1}, {角色2}, ... **前置条件**: - {条件1} - {条件2} **流程步骤**: 1. **{步骤名称}** - 角色: {执行角色} - 调用: {HTTP Method} {Path} - 输入: {关键参数} - 预期: {预期结果} - 验证: {数据库/缓存状态变化} 2. **{下一步骤}** ... **流程图**: ``` [角色A] ──创建──▶ [资源] ──分配──▶ [角色B可见] ──使用──▶ [状态变更] ``` **验证点**: - [ ] {验证点1} - [ ] {验证点2} - [ ] 数据一致性: {描述} **异常流程**: - 如果 {条件}: 预期 {结果} ``` --- ## 六、文件结构 ### 6.1 测试目录 ``` tests/ ├── acceptance/ # 验收测试（单 API） │ ├── account_acceptance_test.go │ ├── package_acceptance_test.go │ ├── iot_card_acceptance_test.go │ └── README.md ├── flows/ # 业务流程测试（多 API） │ ├── package_lifecycle_flow_test.go │ ├── order_purchase_flow_test.go │ ├── commission_settlement_flow_test.go │ └── README.md ├── integration/ # 集成测试（保留） │ └── ... ├── unit/ # 单元测试（精简） │ └── ... └── testutils/ └── integ/ └── integration.go ``` ### 6.2 OpenSpec 目录 ``` openspec/ ├── config.yaml # 更新：增加测试规则 ├── changes/ │ └── / │ ├── consensus.md # 新增：共识确认单 │ ├── proposal.md │ ├── design.md │ ├── tasks.md │ └── specs/ │ └── / │ └── spec.md # 更新：包含 Business Flows └── specs/ └── ... ``` --- ## 七、实施计划 ### Phase 1: 基础设施（2-3 天） 1. 创建目录结构 2. 更新 `openspec/config.yaml` 3. 创建 `openspec-lock-consensus` skill 4. 创建 `openspec-generate-acceptance-tests` skill 5. 更新 `AGENTS.md` 测试规范 6. 创建 `tests/acceptance/README.md` 7. 创建 `tests/flows/README.md` ### Phase 2: 试点（1 周） 选择一个新 feature 完整走一遍新流程： 1. 验证共识锁定机制 2. 验证测试生成 3. 验证测试驱动实现 4. 收集反馈，调整流程 ### Phase 3: 推广（持续） 1. 新 feature 强制使用新流程 2. 现有高价值测试迁移为验收测试 3. 清理低价值单元测试 4. 建立测试覆盖率追踪 --- ## 八、预期收益 | 指标 | 当前 | 预期 | |------|------|------| | 讨论→提案一致率 | ~60% | >95% | | 提案→实现一致率 | ~70% | >95% | | 测试编写时间 | 实现后补，耗时长 | 实现前生成，自动化 | | 测试有效性 | 很多无效测试 | 每个测试有破坏点 | | 重构频率 | 高（17次/100提交） | 低（问题早发现） | | 单测维护成本 | 高（重构就挂） | 低（只测行为） | | 业务流程正确性 | 无保证 | 流程测试覆盖 | --- ## 九、相关文档 - [验收测试说明](../../tests/acceptance/README.md) - [流程测试说明](../../tests/flows/README.md) - [共识锁定 Skill](.opencode/skills/openspec-lock-consensus/SKILL.md) - [测试生成 Skill](.opencode/skills/openspec-generate-acceptance-tests/SKILL.md) - [AGENTS.md 测试规范](../../AGENTS.md#测试要求)