huang
b18ecfeb55
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 6m29s
主要变更: - 新增 tb_shop_series_allocation 表，存储系列级别的一次性佣金配置 - ShopPackageAllocation 移除 one_time_commission_amount 字段 - PackageSeries 新增 enable_one_time_commission 字段控制是否启用一次性佣金 - 新增 /api/admin/shop-series-allocations CRUD 接口 - 佣金计算逻辑改为从 ShopSeriesAllocation 获取一次性佣金金额 - 删除废弃的 ShopSeriesOneTimeCommissionTier 模型 - OpenAPI Tag '系列分配' 和 '单套餐分配' 合并为 '套餐分配' 迁移脚本: - 000042: 重构佣金套餐模型 - 000043: 简化佣金分配 - 000044: 一次性佣金分配重构 - 000045: PackageSeries 添加 enable_one_time_commission 字段 测试: - 新增验收测试 (shop_series_allocation, commission_calculation) - 新增流程测试 (one_time_commission_chain) - 删除过时的单元测试（已被验收测试覆盖）
21 KiB
21 KiB
工作流优化方案
一、背景与问题
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/<name>/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 <name> |
新 锁定共识 |
| 3 | /opsx:new <name> |
创建 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 结构
# {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/
│ └── <change-name>/
│ ├── consensus.md # 新增：共识确认单
│ ├── proposal.md
│ ├── design.md
│ ├── tasks.md
│ └── specs/
│ └── <capability>/
│ └── spec.md # 更新：包含 Business Flows
└── specs/
└── ...
七、实施计划
Phase 1: 基础设施（2-3 天）
- 创建目录结构
- 更新
openspec/config.yaml - 创建
openspec-lock-consensusskill - 创建
openspec-generate-acceptance-testsskill - 更新
AGENTS.md测试规范 - 创建
tests/acceptance/README.md - 创建
tests/flows/README.md
Phase 2: 试点（1 周）
选择一个新 feature 完整走一遍新流程：
- 验证共识锁定机制
- 验证测试生成
- 验证测试驱动实现
- 收集反馈，调整流程
Phase 3: 推广（持续）
- 新 feature 强制使用新流程
- 现有高价值测试迁移为验收测试
- 清理低价值单元测试
- 建立测试覆盖率追踪
八、预期收益
| 指标 | 当前 | 预期 |
|---|---|---|
| 讨论→提案一致率 | ~60% | >95% |
| 提案→实现一致率 | ~70% | >95% |
| 测试编写时间 | 实现后补，耗时长 | 实现前生成，自动化 |
| 测试有效性 | 很多无效测试 | 每个测试有破坏点 |
| 重构频率 | 高（17次/100提交） | 低（问题早发现） |
| 单测维护成本 | 高（重构就挂） | 低（只测行为） |
| 业务流程正确性 | 无保证 | 流程测试覆盖 |