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) - 删除过时的单元测试（已被验收测试覆盖）
387 lines
21 KiB
Markdown
387 lines
21 KiB
Markdown
# 工作流优化方案
|
||
|
||
## 一、背景与问题
|
||
|
||
### 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 结构
|
||
|
||
```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/
|
||
│ └── <change-name>/
|
||
│ ├── consensus.md # 新增：共识确认单
|
||
│ ├── proposal.md
|
||
│ ├── design.md
|
||
│ ├── tasks.md
|
||
│ └── specs/
|
||
│ └── <capability>/
|
||
│ └── 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#测试要求)
|