csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

refactor: 一次性佣金配置从套餐级别提升到系列级别
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 6m29s
Details

Browse Source 
主要变更:
- 新增 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)
- 删除过时的单元测试（已被验收测试覆盖）
This commit is contained in:
huang
2026-02-04 14:28:44 +08:00
parent fba8e9e76b
commit b18ecfeb55
106 changed files with 9899 additions and 6608 deletions
Download Patch File Download Diff File Expand all files Collapse all files

386
docs/workflow-optimization/方案总览.md Normal file
View File

@@ -0,0 +1,386 @@
# 工作流优化方案
## 一、背景与问题
### 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#测试要求)