huang
62708892ec
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 6m2s
1716 lines
43 KiB
Markdown
1716 lines
43 KiB
Markdown
# 强充系统和代购订单功能 - 并行执行计划
|
||
|
||
## TL;DR
|
||
|
||
> **Quick Summary**: 实现钱包充值系统、强充预检、代购订单和佣金计算修复功能。通过6个并行执行波次，将96个任务从8-10小时压缩到4-5小时完成。
|
||
>
|
||
> **Deliverables**:
|
||
> - RechargeStore/Service/Handler 完整实现
|
||
> - 强充预检接口 (充值预检 + 购买预检)
|
||
> - 代购订单功能 (CreatePurchaseOnBehalf)
|
||
> - 佣金计算修复 (代购订单跳过一次性佣金和累计充值)
|
||
> - 数据库迁移 (Order.is_purchase_on_behalf, ShopSeriesAllocation 强充配置)
|
||
>
|
||
> **Estimated Effort**: Large (96 tasks, 4-5 hours with parallelization)
|
||
> **Parallel Execution**: YES - 6 waves
|
||
> **Critical Path**: Wave1 → Wave2 → Wave3(RechargeService) → Wave4(RechargeHandler) → Wave5 → Wave6
|
||
|
||
---
|
||
|
||
## Context
|
||
|
||
### Original Request
|
||
实施 OpenSpec change: **add-force-recharge-system**，包含96个任务，涉及：
|
||
1. 钱包充值系统：个人客户直接充值钱包
|
||
2. 强充预检机制：提供预检接口告知用户强充要求
|
||
3. 代购订单功能：平台为代理代购套餐（线下支付）
|
||
4. 佣金计算修复：代购订单不触发一次性佣金
|
||
|
||
### 当前系统状态
|
||
|
||
**已有组件**：
|
||
- `RechargeRecord` 模型已定义 (`internal/model/wallet.go:79-99`)，但完全未使用
|
||
- `WalletStore`、`WalletTransactionStore` 已完整实现
|
||
- `OrderService` 已有 Create、HandlePaymentCallback、WalletPay 方法
|
||
- `CommissionCalculationService` 已实现差价佣金和一次性佣金
|
||
|
||
**缺失组件**：
|
||
- `RechargeStore`：充值订单数据访问层
|
||
- `RechargeService`：充值业务逻辑层
|
||
- `RechargeHandler`：充值 HTTP 接口
|
||
- 强充预检接口
|
||
- `Order.is_purchase_on_behalf` 字段
|
||
- `ShopSeriesAllocation.enable_force_recharge`/`force_recharge_amount` 字段
|
||
|
||
### 项目约束
|
||
- **技术栈**：Fiber + GORM + Viper + Zap + Asynq (禁止外键)
|
||
- **架构分层**：Handler → Service → Store → Model
|
||
- **错误处理**：Service 层禁止 `fmt.Errorf`，必须用 `errors.New/Wrap`
|
||
- **测试覆盖率**：核心业务逻辑 ≥ 90%
|
||
- **性能要求**：预检接口 < 100ms，充值创建 < 200ms
|
||
|
||
---
|
||
|
||
## Task Dependency Graph
|
||
|
||
| Task Group | Tasks | Depends On | Reason |
|
||
|------------|-------|------------|--------|
|
||
| 1.x 数据库迁移 | 1.1-1.4 | None | 基础设施，首先执行 |
|
||
| 2.x 常量定义 | 2.1-2.5 | None | 纯代码添加 |
|
||
| 3.x 错误码定义 | 3.1-3.3 | None | 纯代码添加 |
|
||
| 4.x Model 修改 | 4.1-4.4 | None | 模型字段添加 |
|
||
| 5.x RechargeStore | 5.1-5.9 | 1.x, 2.x, 3.x, 4.x | 需要 Model、常量、错误码 |
|
||
| 6.x RechargeService | 6.1-6.11 | 5.x | 需要 RechargeStore |
|
||
| 7.x OrderService 修改 | 7.1-7.6 | 4.x, 5.x | 需要 Model 修改和 Store |
|
||
| 8.x CommissionCalculation | 8.1-8.5 | 4.x | 需要 Order.IsPurchaseOnBehalf |
|
||
| 9.x RechargeHandler | 9.1-9.7 | 6.x | 需要 RechargeService |
|
||
| 10.x OrderHandler 修改 | 10.1-10.4 | 7.x | 需要 OrderService 修改 |
|
||
| 11.x PaymentCallback | 11.1-11.3 | 6.x | 需要 RechargeService |
|
||
| 12.x Bootstrap | 12.1-12.4 | 5.x, 6.x, 9.x | 需要 Store/Service/Handler |
|
||
| 13.x 路由注册 | 13.1-13.3 | 12.x | 需要 Bootstrap 完成 |
|
||
| 14.x API 文档 | 14.1-14.4 | 12.x, 13.x | 需要 Handler 注册 |
|
||
| 15.x 集成测试 | 15.1-15.4 | 14.x | 需要完整集成 |
|
||
| 16.x 手动验证 | 16.1-16.4 | 15.x | 需要测试通过 |
|
||
| 17.x 数据库验证 | 17.1-17.6 | 15.x | 需要完整流程 |
|
||
| 18.x 文档更新 | 18.1-18.2 | 15.x | 功能完成后编写 |
|
||
| 19.x 代码规范 | 19.1-19.5 | 15.x | 所有代码完成后检查 |
|
||
| 20.x 完成验证 | 20.1-20.3 | 19.x | 最终验证 |
|
||
|
||
---
|
||
|
||
## Parallel Execution Graph
|
||
|
||
```
|
||
Wave 1 (Start immediately - 4 parallel groups):
|
||
├── Group A: 1.1-1.4 数据库迁移 (no dependencies)
|
||
├── Group B: 2.1-2.5 常量定义 (no dependencies)
|
||
├── Group C: 3.1-3.3 错误码定义 (no dependencies)
|
||
└── Group D: 4.1-4.4 Model 修改 (no dependencies)
|
||
|
||
Wave 2 (After Wave 1):
|
||
└── Group E: 5.1-5.9 RechargeStore (depends: 1.x, 2.x, 3.x, 4.x)
|
||
|
||
Wave 3 (After Wave 2 - 3 parallel groups):
|
||
├── Group F: 6.1-6.11 RechargeService (depends: 5.x)
|
||
├── Group G: 7.1-7.6 OrderService 修改 (depends: 4.x, 5.x)
|
||
└── Group H: 8.1-8.5 CommissionCalculation (depends: 4.x)
|
||
|
||
Wave 4 (After Wave 3 - 3 parallel groups):
|
||
├── Group I: 9.1-9.7 RechargeHandler (depends: 6.x)
|
||
├── Group J: 10.1-10.4 OrderHandler 修改 (depends: 7.x)
|
||
└── Group K: 11.1-11.3 PaymentCallback (depends: 6.x)
|
||
|
||
Wave 5 (After Wave 4 - sequential):
|
||
└── 12.x Bootstrap → 13.x 路由注册 → 14.x API 文档
|
||
|
||
Wave 6 (After Wave 5 - mixed):
|
||
├── 15.x 集成测试 (first, must complete before others)
|
||
│
|
||
├── 并行执行组 A (after 15.x):
|
||
│ ├── 16.x 功能手动验证
|
||
│ └── 17.x 数据库验证
|
||
│
|
||
├── 并行执行组 B (after 15.x, can run parallel with A):
|
||
│ ├── 18.x 文档更新
|
||
│ └── 19.x 代码规范检查
|
||
│
|
||
└── 20.x 完成验证 (last, after A and B)
|
||
|
||
Critical Path: 1.x → 5.x → 6.x → 9.x → 12.x → 13.x → 14.x → 15.x → 20.x
|
||
Estimated Parallel Speedup: ~50% (8-10h → 4-5h)
|
||
```
|
||
|
||
---
|
||
|
||
## Execution Strategy
|
||
|
||
### Agent Dispatch Summary
|
||
|
||
| Wave | Tasks | Parallel Agents | Estimated Time |
|
||
|------|-------|-----------------|----------------|
|
||
| 1 | 1.x, 2.x, 3.x, 4.x | 4 agents | 30 min |
|
||
| 2 | 5.x | 1 agent | 45 min |
|
||
| 3 | 6.x, 7.x, 8.x | 3 agents | 2 hours |
|
||
| 4 | 9.x, 10.x, 11.x | 3 agents | 1 hour |
|
||
| 5 | 12.x, 13.x, 14.x | 1 agent (sequential) | 30 min |
|
||
| 6 | 15.x-20.x | 2-3 agents | 2 hours |
|
||
| **Total** | 96 tasks | Max 4 concurrent | **~4-5 hours** |
|
||
|
||
---
|
||
|
||
## TODOs
|
||
|
||
### Wave 1: 基础设施 (无依赖，可并行)
|
||
|
||
#### Group A: 数据库迁移 (1.1-1.4)
|
||
|
||
- [ ] 1.1. 创建迁移文件：tb_order 表新增 is_purchase_on_behalf 字段
|
||
|
||
**What to do**:
|
||
- 在 migrations/ 目录创建迁移文件 `XXXXXX_add_order_is_purchase_on_behalf.up.sql`
|
||
- SQL: `ALTER TABLE tb_order ADD COLUMN is_purchase_on_behalf BOOLEAN DEFAULT false;`
|
||
- 创建对应的 down 迁移文件
|
||
|
||
**Must NOT do**:
|
||
- 不要修改现有字段
|
||
- 不要添加外键约束
|
||
|
||
**Recommended Agent Profile**:
|
||
- **Category**: `quick`
|
||
- Reason: 简单 SQL DDL 语句
|
||
- **Skills**: [`db-migration`]
|
||
- `db-migration`: 迁移文件命名规范和执行流程
|
||
|
||
**Parallelization**:
|
||
- **Can Run In Parallel**: YES
|
||
- **Parallel Group**: Wave 1 (with 2.x, 3.x, 4.x)
|
||
- **Blocks**: 5.x, 7.x
|
||
- **Blocked By**: None
|
||
|
||
**References**:
|
||
- `migrations/` - 现有迁移文件格式参考
|
||
- `internal/model/order.go` - Order 模型定义
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 迁移文件创建成功
|
||
- [ ] `source .env.local && migrate -path migrations -database "$JUNHONG_DATABASE_URL" up` 执行成功
|
||
- [ ] `SELECT column_name FROM information_schema.columns WHERE table_name='tb_order' AND column_name='is_purchase_on_behalf'` 返回 1 行
|
||
|
||
**Commit**: YES
|
||
- Message: `feat(order): 添加代购订单标识字段迁移`
|
||
- Files: `migrations/XXXXXX_add_order_is_purchase_on_behalf.up.sql`, `migrations/XXXXXX_add_order_is_purchase_on_behalf.down.sql`
|
||
|
||
---
|
||
|
||
- [ ] 1.2. 创建迁移文件：tb_shop_series_allocation 表新增强充配置字段
|
||
|
||
**What to do**:
|
||
- 创建迁移文件添加 `enable_force_recharge BOOLEAN DEFAULT false`
|
||
- 创建迁移文件添加 `force_recharge_amount BIGINT DEFAULT 0`
|
||
|
||
**Recommended Agent Profile**:
|
||
- **Category**: `quick`
|
||
- **Skills**: [`db-migration`]
|
||
|
||
**Parallelization**:
|
||
- **Can Run In Parallel**: YES
|
||
- **Parallel Group**: Wave 1
|
||
- **Blocks**: 5.x
|
||
- **Blocked By**: None
|
||
|
||
**References**:
|
||
- `internal/model/shop_series_allocation.go` - 现有模型字段
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 迁移文件创建成功
|
||
- [ ] 迁移执行成功，字段存在
|
||
|
||
**Commit**: YES (groups with 1.1)
|
||
|
||
---
|
||
|
||
- [ ] 1.3. 在测试环境执行迁移并验证字段添加成功
|
||
|
||
**What to do**:
|
||
- 执行迁移命令
|
||
- 验证字段存在
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] `migrate up` 无错误
|
||
- [ ] 两个新字段都存在于数据库
|
||
|
||
**Commit**: NO (grouped with 1.1)
|
||
|
||
---
|
||
|
||
- [ ] 1.4. 验证迁移：检查字段默认值和数据类型是否正确
|
||
|
||
**What to do**:
|
||
- 查询 information_schema 验证字段类型
|
||
- 验证默认值正确
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] `is_purchase_on_behalf` 类型为 boolean，默认 false
|
||
- [ ] `enable_force_recharge` 类型为 boolean，默认 false
|
||
- [ ] `force_recharge_amount` 类型为 bigint，默认 0
|
||
|
||
**Commit**: NO
|
||
|
||
---
|
||
|
||
#### Group B: 常量定义 (2.1-2.5)
|
||
|
||
- [ ] 2.1. 在 pkg/constants/ 定义充值订单状态常量
|
||
|
||
**What to do**:
|
||
- 在 `pkg/constants/recharge.go` 创建新文件
|
||
- 定义: RechargeStatusPending(1), RechargeStatusPaid(2), RechargeStatusCompleted(3), RechargeStatusClosed(4)
|
||
- 添加中文注释
|
||
|
||
**Recommended Agent Profile**:
|
||
- **Category**: `quick`
|
||
- **Skills**: []
|
||
|
||
**Parallelization**:
|
||
- **Can Run In Parallel**: YES
|
||
- **Parallel Group**: Wave 1
|
||
- **Blocks**: 5.x, 6.x
|
||
- **Blocked By**: None
|
||
|
||
**References**:
|
||
- `pkg/constants/constants.go` - 现有常量格式
|
||
- `internal/model/wallet.go:91` - RechargeRecord.Status 字段注释
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 常量文件创建成功
|
||
- [ ] `go build ./...` 无错误
|
||
|
||
**Commit**: YES
|
||
- Message: `feat(constants): 添加充值订单状态和配置常量`
|
||
|
||
---
|
||
|
||
- [ ] 2.2. 定义充值订单号前缀常量（RCH）
|
||
|
||
**What to do**:
|
||
- 添加 `RechargeOrderPrefix = "RCH"` 常量
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 常量定义成功
|
||
|
||
**Commit**: YES (groups with 2.1)
|
||
|
||
---
|
||
|
||
- [ ] 2.3. 定义线下支付方式常量（offline）
|
||
|
||
**What to do**:
|
||
- 添加 `PaymentMethodOffline = "offline"` 到支付方式常量
|
||
|
||
**References**:
|
||
- `internal/model/order.go:62-66` - 现有支付方式常量
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 常量添加成功
|
||
|
||
**Commit**: YES (groups with 2.1)
|
||
|
||
---
|
||
|
||
- [ ] 2.4. 定义强充相关 Redis Key 生成函数（可选）
|
||
|
||
**What to do**:
|
||
- 如果需要缓存系列配置，添加 Redis Key 函数
|
||
- 函数格式: `RedisForceRechargeConfigKey(seriesID uint) string`
|
||
|
||
**References**:
|
||
- `pkg/constants/redis.go` - 现有 Redis Key 函数
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 如需缓存，函数创建成功；否则跳过
|
||
|
||
**Commit**: YES (groups with 2.1)
|
||
|
||
---
|
||
|
||
- [ ] 2.5. 定义充值金额限制常量（最小1元，最大100000元）
|
||
|
||
**What to do**:
|
||
- 添加 `RechargeMinAmount = 100` (分)
|
||
- 添加 `RechargeMaxAmount = 10000000` (分)
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 常量定义成功
|
||
|
||
**Commit**: YES (groups with 2.1)
|
||
|
||
---
|
||
|
||
#### Group C: 错误码定义 (3.1-3.3)
|
||
|
||
- [ ] 3.1. 定义充值相关错误码
|
||
|
||
**What to do**:
|
||
- 在 `pkg/errors/codes.go` 添加:
|
||
- `CodeRechargeAmountInvalid = 4401` // 充值金额不符合要求
|
||
- `CodeRechargeNotFound = 4402` // 充值订单不存在
|
||
- `CodeRechargeAlreadyPaid = 4403` // 充值订单已支付
|
||
|
||
**Recommended Agent Profile**:
|
||
- **Category**: `quick`
|
||
- **Skills**: []
|
||
|
||
**Parallelization**:
|
||
- **Can Run In Parallel**: YES
|
||
- **Parallel Group**: Wave 1
|
||
- **Blocks**: 5.x, 6.x
|
||
- **Blocked By**: None
|
||
|
||
**References**:
|
||
- `pkg/errors/codes.go` - 现有错误码格式和编号范围
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 错误码添加成功
|
||
- [ ] 错误码编号不与现有冲突
|
||
|
||
**Commit**: YES
|
||
- Message: `feat(errors): 添加充值和代购相关错误码`
|
||
|
||
---
|
||
|
||
- [ ] 3.2. 定义代购相关错误码
|
||
|
||
**What to do**:
|
||
- `CodePurchaseOnBehalfForbidden = 4404` // 无权使用线下支付
|
||
- `CodePurchaseOnBehalfInvalidTarget = 4405` // 代购目标无效
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 错误码添加成功
|
||
|
||
**Commit**: YES (groups with 3.1)
|
||
|
||
---
|
||
|
||
- [ ] 3.3. 定义强充验证错误码
|
||
|
||
**What to do**:
|
||
- `CodeForceRechargeRequired = 4406` // 必须充值指定金额
|
||
- `CodeForceRechargeAmountMismatch = 4407` // 强充金额不匹配
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 错误码添加成功
|
||
|
||
**Commit**: YES (groups with 3.1)
|
||
|
||
---
|
||
|
||
#### Group D: Model 层修改 (4.1-4.4)
|
||
|
||
- [ ] 4.1. 修改 Order 模型：新增 IsPurchaseOnBehalf 字段
|
||
|
||
**What to do**:
|
||
- 在 `internal/model/order.go` Order struct 添加:
|
||
```go
|
||
IsPurchaseOnBehalf bool `gorm:"column:is_purchase_on_behalf;type:boolean;default:false;comment:是否为代购订单" json:"is_purchase_on_behalf"`
|
||
```
|
||
|
||
**Recommended Agent Profile**:
|
||
- **Category**: `quick`
|
||
- **Skills**: [`model-standards`]
|
||
|
||
**Parallelization**:
|
||
- **Can Run In Parallel**: YES
|
||
- **Parallel Group**: Wave 1
|
||
- **Blocks**: 5.x, 7.x, 8.x
|
||
- **Blocked By**: None
|
||
|
||
**References**:
|
||
- `internal/model/order.go` - Order 模型
|
||
- `openspec/changes/add-force-recharge-system/design.md:97-98` - 字段设计
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 字段添加成功
|
||
- [ ] `go build ./...` 无错误
|
||
- [ ] GORM tag 包含 column, type, default, comment
|
||
|
||
**Commit**: YES
|
||
- Message: `feat(model): Order 新增代购订单标识字段`
|
||
|
||
---
|
||
|
||
- [ ] 4.2. 修改 ShopSeriesAllocation：新增 EnableForceRecharge 字段
|
||
|
||
**What to do**:
|
||
- 在 `internal/model/shop_series_allocation.go` 添加:
|
||
```go
|
||
EnableForceRecharge bool `gorm:"column:enable_force_recharge;type:boolean;default:false;comment:是否启用强充(累计充值时可选)" json:"enable_force_recharge"`
|
||
```
|
||
|
||
**Recommended Agent Profile**:
|
||
- **Category**: `quick`
|
||
- **Skills**: [`model-standards`]
|
||
|
||
**References**:
|
||
- `internal/model/shop_series_allocation.go` - 现有模型
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 字段添加成功
|
||
- [ ] `go build ./...` 无错误
|
||
|
||
**Commit**: YES
|
||
- Message: `feat(model): ShopSeriesAllocation 新增强充配置字段`
|
||
|
||
---
|
||
|
||
- [ ] 4.3. 修改 ShopSeriesAllocation：新增 ForceRechargeAmount 字段
|
||
|
||
**What to do**:
|
||
- 添加:
|
||
```go
|
||
ForceRechargeAmount int64 `gorm:"column:force_recharge_amount;type:bigint;default:0;comment:强充金额(分,0表示使用阈值金额)" json:"force_recharge_amount"`
|
||
```
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 字段添加成功
|
||
|
||
**Commit**: YES (groups with 4.2)
|
||
|
||
---
|
||
|
||
- [ ] 4.4. 验证 Model 修改：运行 lsp_diagnostics 检查类型错误
|
||
|
||
**What to do**:
|
||
- 运行 `go build ./...` 验证编译
|
||
- 检查 LSP 诊断无错误
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 编译成功
|
||
- [ ] 无类型错误
|
||
|
||
**Commit**: NO
|
||
|
||
---
|
||
|
||
### Wave 2: 数据访问层 (依赖 Wave 1)
|
||
|
||
#### Group E: RechargeStore (5.1-5.9)
|
||
|
||
- [ ] 5.1. 创建 internal/store/postgres/recharge_store.go
|
||
|
||
**What to do**:
|
||
- 创建 `RechargeStore` struct
|
||
- 包含 `*gorm.DB` 和 `*redis.Client` 字段
|
||
- 实现 `NewRechargeStore` 构造函数
|
||
|
||
**Recommended Agent Profile**:
|
||
- **Category**: `unspecified-low`
|
||
- Reason: 标准 Store 层实现，遵循现有模式
|
||
- **Skills**: []
|
||
|
||
**Parallelization**:
|
||
- **Can Run In Parallel**: NO (Wave 2 单独执行)
|
||
- **Parallel Group**: Wave 2
|
||
- **Blocks**: 6.x, 12.x
|
||
- **Blocked By**: 1.x, 2.x, 3.x, 4.x (Wave 1)
|
||
|
||
**References**:
|
||
- `internal/store/postgres/order_store.go` - Store 模式参考
|
||
- `internal/store/postgres/wallet_store.go` - 钱包相关 Store 参考
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 文件创建成功
|
||
- [ ] 结构体定义正确
|
||
- [ ] 编译成功
|
||
|
||
**Commit**: YES
|
||
- Message: `feat(store): 新增 RechargeStore 充值订单数据访问层`
|
||
|
||
---
|
||
|
||
- [ ] 5.2. 实现 Create 方法：创建充值订单
|
||
|
||
**What to do**:
|
||
- 方法签名: `Create(ctx context.Context, record *model.RechargeRecord) error`
|
||
- 使用 GORM Create
|
||
|
||
**References**:
|
||
- `internal/store/postgres/order_store.go:Create` - Create 方法参考
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 方法实现成功
|
||
- [ ] 自动填充 created_at, updated_at
|
||
|
||
**Commit**: YES (groups with 5.1)
|
||
|
||
---
|
||
|
||
- [ ] 5.3. 实现 GetByRechargeNo 方法
|
||
|
||
**What to do**:
|
||
- 方法签名: `GetByRechargeNo(ctx context.Context, rechargeNo string) (*model.RechargeRecord, error)`
|
||
- 根据充值单号查询，不存在返回 nil 和 nil
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 方法实现成功
|
||
- [ ] 不存在时返回 nil, nil（非 error）
|
||
|
||
**Commit**: YES (groups with 5.1)
|
||
|
||
---
|
||
|
||
- [ ] 5.4. 实现 GetByID 方法
|
||
|
||
**What to do**:
|
||
- 方法签名: `GetByID(ctx context.Context, id uint) (*model.RechargeRecord, error)`
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 方法实现成功
|
||
|
||
**Commit**: YES (groups with 5.1)
|
||
|
||
---
|
||
|
||
- [ ] 5.5. 实现 List 方法
|
||
|
||
**What to do**:
|
||
- 方法签名: `List(ctx context.Context, params *ListRechargeParams) ([]*model.RechargeRecord, int64, error)`
|
||
- 支持分页、状态筛选、时间范围筛选
|
||
- 定义 `ListRechargeParams` struct
|
||
|
||
**References**:
|
||
- `internal/store/postgres/order_store.go:List` - List 方法参考
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 方法实现成功
|
||
- [ ] 支持分页和筛选
|
||
|
||
**Commit**: YES (groups with 5.1)
|
||
|
||
---
|
||
|
||
- [ ] 5.6. 实现 UpdateStatus 方法
|
||
|
||
**What to do**:
|
||
- 方法签名: `UpdateStatus(ctx context.Context, id uint, status int) error`
|
||
- 支持乐观锁检查（原状态 → 新状态）
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 方法实现成功
|
||
- [ ] 支持状态流转检查
|
||
|
||
**Commit**: YES (groups with 5.1)
|
||
|
||
---
|
||
|
||
- [ ] 5.7. 实现 UpdatePaymentInfo 方法
|
||
|
||
**What to do**:
|
||
- 方法签名: `UpdatePaymentInfo(ctx context.Context, id uint, method string, transactionID string) error`
|
||
- 更新支付方式、支付时间、第三方交易号
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 方法实现成功
|
||
|
||
**Commit**: YES (groups with 5.1)
|
||
|
||
---
|
||
|
||
- [ ] 5.8. 编写单元测试
|
||
|
||
**What to do**:
|
||
- 创建 `internal/store/postgres/recharge_store_test.go`
|
||
- 使用 testutils.NewTestTransaction
|
||
- 测试覆盖率 ≥ 90%
|
||
|
||
**References**:
|
||
- `internal/store/postgres/order_store_test.go` - 测试模式参考
|
||
- `docs/testing/test-connection-guide.md` - 测试连接管理
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 测试文件创建
|
||
- [ ] `source .env.local && go test -v ./internal/store/postgres/... -run TestRecharge` 通过
|
||
- [ ] 覆盖率 ≥ 90%
|
||
|
||
**Commit**: YES (groups with 5.1)
|
||
|
||
---
|
||
|
||
- [ ] 5.9. 验证测试
|
||
|
||
**What to do**:
|
||
- 运行所有 RechargeStore 测试
|
||
- 确保全部通过
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 所有测试通过
|
||
|
||
**Commit**: NO
|
||
|
||
---
|
||
|
||
### Wave 3: 业务逻辑层 (依赖 Wave 2，3 个并行组)
|
||
|
||
#### Group F: RechargeService (6.1-6.11)
|
||
|
||
- [ ] 6.1. 创建 internal/service/recharge/service.go
|
||
|
||
**What to do**:
|
||
- 创建 Service struct
|
||
- 依赖: DB, RechargeStore, WalletStore, IotCardStore, DeviceStore, ShopSeriesAllocationStore
|
||
- 实现 New 构造函数
|
||
|
||
**Recommended Agent Profile**:
|
||
- **Category**: `unspecified-high`
|
||
- Reason: 复杂业务逻辑，涉及多个模块交互
|
||
- **Skills**: [`db-validation`]
|
||
- `db-validation`: 涉及复杂数据库操作和业务逻辑验证
|
||
|
||
**Parallelization**:
|
||
- **Can Run In Parallel**: YES
|
||
- **Parallel Group**: Wave 3 (with 7.x, 8.x)
|
||
- **Blocks**: 9.x, 11.x, 12.x
|
||
- **Blocked By**: 5.x (Wave 2)
|
||
|
||
**References**:
|
||
- `internal/service/order/service.go` - Service 模式参考
|
||
- `internal/bootstrap/services.go` - 依赖注入模式
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 文件创建成功
|
||
- [ ] 依赖定义正确
|
||
- [ ] 编译成功
|
||
|
||
**Commit**: YES
|
||
- Message: `feat(service): 新增 RechargeService 充值业务逻辑层`
|
||
|
||
---
|
||
|
||
- [ ] 6.2. 实现 Create 方法：创建充值订单
|
||
|
||
**What to do**:
|
||
- 验证资源存在（卡/设备）
|
||
- 验证充值金额范围（1元~100000元）
|
||
- 检查强充要求并验证金额
|
||
- 生成充值单号（RCH + 时间戳 + 随机数）
|
||
- 创建充值订单记录
|
||
|
||
**References**:
|
||
- `openspec/changes/add-force-recharge-system/design.md:171-206` - 强充验证逻辑
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 方法实现成功
|
||
- [ ] 支持强充验证
|
||
- [ ] 生成正确的订单号格式
|
||
|
||
**Commit**: YES (groups with 6.1)
|
||
|
||
---
|
||
|
||
- [ ] 6.3. 实现 GetRechargeCheck 方法：充值预检
|
||
|
||
**What to do**:
|
||
- 查询资源（卡/设备）
|
||
- 查询系列分配配置
|
||
- 判断是否需要强充
|
||
- 返回: NeedForceRecharge, ForceRechargeAmount, TriggerType, MinAmount, MaxAmount, CurrentAccumulated, Threshold, Message
|
||
|
||
**References**:
|
||
- `openspec/changes/add-force-recharge-system/design.md:137-149` - 响应结构
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 方法实现成功
|
||
- [ ] 返回完整的预检信息
|
||
|
||
**Commit**: YES (groups with 6.1)
|
||
|
||
---
|
||
|
||
- [ ] 6.4. 实现 GetByID 方法
|
||
|
||
**What to do**:
|
||
- 查询充值订单详情
|
||
- 应用数据权限过滤
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 方法实现成功
|
||
- [ ] 数据权限正确过滤
|
||
|
||
**Commit**: YES (groups with 6.1)
|
||
|
||
---
|
||
|
||
- [ ] 6.5. 实现 List 方法
|
||
|
||
**What to do**:
|
||
- 查询充值订单列表
|
||
- 支持分页、筛选
|
||
- 应用数据权限过滤
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 方法实现成功
|
||
|
||
**Commit**: YES (groups with 6.1)
|
||
|
||
---
|
||
|
||
- [ ] 6.6. 实现 HandlePaymentCallback 方法
|
||
|
||
**What to do**:
|
||
- 幂等性检查（检查订单状态）
|
||
- 使用数据库事务:
|
||
1. 更新订单状态
|
||
2. 增加钱包余额
|
||
3. 更新累计充值
|
||
4. 触发佣金判断
|
||
- 钱包余额更新使用乐观锁
|
||
|
||
**References**:
|
||
- `openspec/changes/add-force-recharge-system/design.md:360-378` - 回调处理流程
|
||
- `internal/service/order/service.go:HandlePaymentCallback` - 参考实现
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 方法实现成功
|
||
- [ ] 幂等性保证
|
||
- [ ] 事务正确
|
||
|
||
**Commit**: YES (groups with 6.1)
|
||
|
||
---
|
||
|
||
- [ ] 6.7. 实现 updateAccumulatedRecharge 私有方法
|
||
|
||
**What to do**:
|
||
- 根据资源类型（卡/设备）更新对应的 accumulated_recharge 字段
|
||
- 使用原子操作 `gorm.Expr("accumulated_recharge + ?", amount)`
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 方法实现成功
|
||
- [ ] 使用原子更新
|
||
|
||
**Commit**: YES (groups with 6.1)
|
||
|
||
---
|
||
|
||
- [ ] 6.8. 实现 triggerOneTimeCommissionIfNeeded 私有方法
|
||
|
||
**What to do**:
|
||
- 检查是否达到一次性佣金触发条件
|
||
- 如果达到，调用佣金计算服务
|
||
|
||
**References**:
|
||
- `internal/service/commission_calculation/service.go:TriggerOneTimeCommissionForCard` - 参考
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 方法实现成功
|
||
- [ ] 正确触发佣金计算
|
||
|
||
**Commit**: YES (groups with 6.1)
|
||
|
||
---
|
||
|
||
- [ ] 6.9. 实现 checkForceRechargeRequirement 私有方法
|
||
|
||
**What to do**:
|
||
- 供创建订单时使用的强充验证
|
||
- 返回强充要求或 nil
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 方法实现成功
|
||
|
||
**Commit**: YES (groups with 6.1)
|
||
|
||
---
|
||
|
||
- [ ] 6.10. 编写单元测试
|
||
|
||
**What to do**:
|
||
- 创建 `internal/service/recharge/service_test.go`
|
||
- 测试覆盖各种充值场景、强充验证、支付回调幂等性
|
||
- 测试覆盖率 ≥ 90%
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 测试文件创建
|
||
- [ ] 测试通过
|
||
- [ ] 覆盖率 ≥ 90%
|
||
|
||
**Commit**: YES (groups with 6.1)
|
||
|
||
---
|
||
|
||
- [ ] 6.11. 验证测试
|
||
|
||
**What to do**:
|
||
- 运行所有 RechargeService 测试
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 所有测试通过
|
||
|
||
**Commit**: NO
|
||
|
||
---
|
||
|
||
#### Group G: OrderService 修改 (7.1-7.6)
|
||
|
||
- [ ] 7.1. 修改 Create 方法增加强充验证
|
||
|
||
**What to do**:
|
||
- 在创建订单前调用预检逻辑
|
||
- 验证支付金额是否符合强充要求
|
||
- 不符合则返回错误
|
||
|
||
**Recommended Agent Profile**:
|
||
- **Category**: `unspecified-high`
|
||
- **Skills**: [`db-validation`]
|
||
- `db-validation`: 涉及复杂订单逻辑和数据库事务操作
|
||
|
||
**Parallelization**:
|
||
- **Can Run In Parallel**: YES
|
||
- **Parallel Group**: Wave 3 (with 6.x, 8.x)
|
||
- **Blocks**: 10.x
|
||
- **Blocked By**: 4.x, 5.x
|
||
|
||
**References**:
|
||
- `internal/service/order/service.go` - 现有 OrderService
|
||
- `openspec/changes/add-force-recharge-system/design.md:286-309` - 代购订单逻辑
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 强充验证逻辑添加成功
|
||
- [ ] 不符合要求时返回正确错误
|
||
|
||
**Commit**: YES
|
||
- Message: `feat(order): 订单创建增加强充验证和代购支持`
|
||
|
||
---
|
||
|
||
- [ ] 7.2. 新增 CreatePurchaseOnBehalf 方法
|
||
|
||
**What to do**:
|
||
- 验证权限（只有平台可以使用线下支付）
|
||
- 查询资源归属代理（buyer_id）
|
||
- 查询买家的成本价
|
||
- 创建订单（is_purchase_on_behalf = true, payment_method = offline, payment_status = 2）
|
||
- 自动激活套餐
|
||
- 触发佣金计算任务
|
||
|
||
**References**:
|
||
- `openspec/changes/add-force-recharge-system/design.md:265-284` - 代购流程
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 方法实现成功
|
||
- [ ] 订单自动标记为已支付
|
||
- [ ] 套餐自动激活
|
||
|
||
**Commit**: YES (groups with 7.1)
|
||
|
||
---
|
||
|
||
- [ ] 7.3. 新增 GetPurchaseCheck 方法
|
||
|
||
**What to do**:
|
||
- 查询套餐总价
|
||
- 检查强充要求
|
||
- 计算实际支付金额和钱包到账金额
|
||
- 返回预检信息
|
||
|
||
**References**:
|
||
- `openspec/changes/add-force-recharge-system/design.md:151-167` - 预检响应结构
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 方法实现成功
|
||
- [ ] 返回完整预检信息
|
||
|
||
**Commit**: YES (groups with 7.1)
|
||
|
||
---
|
||
|
||
- [ ] 7.4. 修改支付成功后的处理逻辑
|
||
|
||
**What to do**:
|
||
- 增加 is_purchase_on_behalf 判断
|
||
- 如果是代购订单，跳过钱包扣款
|
||
- 如果是普通订单，正常扣款
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 逻辑修改成功
|
||
- [ ] 代购订单不扣款
|
||
|
||
**Commit**: YES (groups with 7.1)
|
||
|
||
---
|
||
|
||
- [ ] 7.5. 编写单元测试
|
||
|
||
**What to do**:
|
||
- 测试代购订单创建
|
||
- 测试强充验证
|
||
- 测试预检逻辑
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 测试通过
|
||
|
||
**Commit**: YES (groups with 7.1)
|
||
|
||
---
|
||
|
||
- [ ] 7.6. 验证测试
|
||
|
||
**What to do**:
|
||
- 运行所有 OrderService 测试
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 所有测试通过
|
||
|
||
**Commit**: NO
|
||
|
||
---
|
||
|
||
#### Group H: CommissionCalculationService 修改 (8.1-8.5)
|
||
|
||
- [ ] 8.1. 修改 CalculateCommission 方法增加代购订单判断
|
||
|
||
**What to do**:
|
||
- 差价佣金：所有订单都计算（包括代购）
|
||
- 累计充值更新：仅非代购订单更新
|
||
- 一次性佣金：仅非代购订单触发
|
||
|
||
**Recommended Agent Profile**:
|
||
- **Category**: `unspecified-low`
|
||
- **Skills**: []
|
||
|
||
**Parallelization**:
|
||
- **Can Run In Parallel**: YES
|
||
- **Parallel Group**: Wave 3 (with 6.x, 7.x)
|
||
- **Blocks**: 15.x
|
||
- **Blocked By**: 4.x
|
||
|
||
**References**:
|
||
- `internal/service/commission_calculation/service.go` - 现有实现
|
||
- `openspec/changes/add-force-recharge-system/design.md:322-358` - 佣金修复逻辑
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 逻辑修改成功
|
||
- [ ] 代购订单不更新累计充值
|
||
- [ ] 代购订单不触发一次性佣金
|
||
|
||
**Commit**: YES
|
||
- Message: `fix(commission): 代购订单跳过一次性佣金和累计充值更新`
|
||
|
||
---
|
||
|
||
- [ ] 8.2. 修改 updateAccumulatedRecharge 方法
|
||
|
||
**What to do**:
|
||
- 增加代购订单检查
|
||
- 如果 is_purchase_on_behalf = true，直接返回
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 逻辑修改成功
|
||
|
||
**Commit**: YES (groups with 8.1)
|
||
|
||
---
|
||
|
||
- [ ] 8.3. 修改 triggerOneTimeCommission 方法
|
||
|
||
**What to do**:
|
||
- 增加代购订单检查
|
||
- 如果 is_purchase_on_behalf = true，直接返回
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 逻辑修改成功
|
||
|
||
**Commit**: YES (groups with 8.1)
|
||
|
||
---
|
||
|
||
- [ ] 8.4. 编写单元测试
|
||
|
||
**What to do**:
|
||
- 使用 table-driven tests
|
||
- 测试场景：普通订单、代购订单、充值订单
|
||
|
||
**References**:
|
||
- `openspec/changes/add-force-recharge-system/design.md:531-549` - 测试场景
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 测试通过
|
||
- [ ] 覆盖所有场景
|
||
|
||
**Commit**: YES (groups with 8.1)
|
||
|
||
---
|
||
|
||
- [ ] 8.5. 验证测试
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 所有测试通过
|
||
|
||
**Commit**: NO
|
||
|
||
---
|
||
|
||
### Wave 4: HTTP 接口层 (依赖 Wave 3，3 个并行组)
|
||
|
||
#### Group I: RechargeHandler (9.1-9.7)
|
||
|
||
- [ ] 9.1. 创建 internal/handler/h5/recharge.go
|
||
|
||
**What to do**:
|
||
- 创建 RechargeHandler struct
|
||
- 依赖 RechargeService
|
||
- 实现 NewRechargeHandler 构造函数
|
||
|
||
**Recommended Agent Profile**:
|
||
- **Category**: `unspecified-low`
|
||
- **Skills**: [`api-routing`, `dto-standards`]
|
||
- `api-routing`: 路由注册规范
|
||
- `dto-standards`: DTO 数据传输对象规范
|
||
|
||
**Parallelization**:
|
||
- **Can Run In Parallel**: YES
|
||
- **Parallel Group**: Wave 4 (with 10.x, 11.x)
|
||
- **Blocks**: 12.x, 13.x
|
||
- **Blocked By**: 6.x
|
||
|
||
**References**:
|
||
- `internal/handler/h5/order.go` - H5 Handler 参考
|
||
- `internal/handler/admin/order.go` - Handler 模式参考
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 文件创建成功
|
||
- [ ] 编译成功
|
||
|
||
**Commit**: YES
|
||
- Message: `feat(handler): 新增 RechargeHandler 充值 HTTP 接口`
|
||
|
||
---
|
||
|
||
- [ ] 9.2. 实现 POST /api/h5/wallets/recharge：创建充值订单
|
||
|
||
**What to do**:
|
||
- 参数验证（resource_type, resource_id, amount）
|
||
- 调用 Service 创建充值订单
|
||
- 返回充值订单信息
|
||
|
||
**References**:
|
||
- 创建对应 DTO: `internal/model/dto/recharge_dto.go`
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 接口实现成功
|
||
- [ ] DTO 创建成功
|
||
- [ ] 参数验证正确
|
||
|
||
**Commit**: YES (groups with 9.1)
|
||
|
||
---
|
||
|
||
- [ ] 9.3. 实现 GET /api/h5/wallets/recharge-check：充值预检
|
||
|
||
**What to do**:
|
||
- 参数验证（resource_type, resource_id）
|
||
- 调用 Service 获取强充要求
|
||
- 返回预检信息
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 接口实现成功
|
||
|
||
**Commit**: YES (groups with 9.1)
|
||
|
||
---
|
||
|
||
- [ ] 9.4. 实现 GET /api/h5/wallets/recharges：查询列表
|
||
|
||
**What to do**:
|
||
- 支持分页参数（page, page_size）
|
||
- 支持状态筛选（status）
|
||
- 支持时间范围筛选
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 接口实现成功
|
||
- [ ] 支持所有筛选参数
|
||
|
||
**Commit**: YES (groups with 9.1)
|
||
|
||
---
|
||
|
||
- [ ] 9.5. 实现 GET /api/h5/wallets/recharges/:id：查询详情
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 接口实现成功
|
||
|
||
**Commit**: YES (groups with 9.1)
|
||
|
||
---
|
||
|
||
- [ ] 9.6. 为所有接口添加中文注释
|
||
|
||
**What to do**:
|
||
- 路由路径注释
|
||
- 参数说明注释
|
||
- 响应说明注释
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 所有接口有完整中文注释
|
||
|
||
**Commit**: YES (groups with 9.1)
|
||
|
||
---
|
||
|
||
- [ ] 9.7. 验证接口
|
||
|
||
**What to do**:
|
||
- 运行 `go build ./...`
|
||
- 检查 LSP 诊断
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 编译成功
|
||
- [ ] 无类型错误
|
||
|
||
**Commit**: NO
|
||
|
||
---
|
||
|
||
#### Group J: OrderHandler 修改 (10.1-10.4)
|
||
|
||
- [ ] 10.1. 修改 Create 方法增加代购订单支持
|
||
|
||
**What to do**:
|
||
- 检查 payment_method = offline 时，验证用户类型为 Platform
|
||
- 如果是平台账号且线下支付，调用 CreatePurchaseOnBehalf
|
||
- 否则调用正常的 Create 方法
|
||
|
||
**Recommended Agent Profile**:
|
||
- **Category**: `quick`
|
||
- **Skills**: [`api-routing`]
|
||
|
||
**Parallelization**:
|
||
- **Can Run In Parallel**: YES
|
||
- **Parallel Group**: Wave 4
|
||
- **Blocks**: 12.x
|
||
- **Blocked By**: 7.x
|
||
|
||
**References**:
|
||
- `internal/handler/admin/order.go` - 现有 Handler
|
||
- `openspec/changes/add-force-recharge-system/design.md:286-309` - 权限控制
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 逻辑修改成功
|
||
- [ ] 权限验证正确
|
||
|
||
**Commit**: YES
|
||
- Message: `feat(handler): OrderHandler 支持代购订单创建`
|
||
|
||
---
|
||
|
||
- [ ] 10.2. 新增 POST /api/admin/orders/purchase-check 接口
|
||
|
||
**What to do**:
|
||
- 参数验证（order_type, resource_id, package_ids）
|
||
- 调用 Service 获取预检信息
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 接口实现成功
|
||
|
||
**Commit**: YES (groups with 10.1)
|
||
|
||
---
|
||
|
||
- [ ] 10.3. 为新增接口添加中文注释
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 注释添加完整
|
||
|
||
**Commit**: YES (groups with 10.1)
|
||
|
||
---
|
||
|
||
- [ ] 10.4. 验证接口
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 编译成功
|
||
- [ ] 无错误
|
||
|
||
**Commit**: NO
|
||
|
||
---
|
||
|
||
#### Group K: PaymentCallback 修改 (11.1-11.3)
|
||
|
||
- [ ] 11.1. 修改 WechatPayCallback 增加充值订单判断
|
||
|
||
**What to do**:
|
||
- 根据订单号前缀判断类型（RCH 开头 → 充值订单）
|
||
- 如果是充值订单，调用 RechargeService.HandlePaymentCallback
|
||
- 如果是套餐订单，调用 OrderService.HandlePaymentCallback
|
||
|
||
**Recommended Agent Profile**:
|
||
- **Category**: `quick`
|
||
- **Skills**: []
|
||
|
||
**Parallelization**:
|
||
- **Can Run In Parallel**: YES
|
||
- **Parallel Group**: Wave 4
|
||
- **Blocks**: 12.x
|
||
- **Blocked By**: 6.x
|
||
|
||
**References**:
|
||
- `internal/handler/callback/payment.go` - 现有回调 Handler
|
||
- `openspec/changes/add-force-recharge-system/design.md:239-253` - 回调路由逻辑
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 逻辑修改成功
|
||
- [ ] 正确区分充值和套餐订单
|
||
|
||
**Commit**: YES
|
||
- Message: `feat(callback): 支付回调支持充值订单处理`
|
||
|
||
---
|
||
|
||
- [ ] 11.2. 修改 AlipayCallback 方法
|
||
|
||
**What to do**:
|
||
- 同 11.1 的逻辑
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 逻辑修改成功
|
||
|
||
**Commit**: YES (groups with 11.1)
|
||
|
||
---
|
||
|
||
- [ ] 11.3. 验证修改
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 编译成功
|
||
|
||
**Commit**: NO
|
||
|
||
---
|
||
|
||
### Wave 5: 集成层 (顺序执行)
|
||
|
||
#### Group L: Bootstrap 和路由 (12.x, 13.x, 14.x)
|
||
|
||
- [ ] 12.1. 修改 internal/bootstrap/stores.go：注册 RechargeStore
|
||
|
||
**What to do**:
|
||
- 在 stores struct 添加 `Recharge *postgres.RechargeStore`
|
||
- 在 initStores 中初始化
|
||
|
||
**Recommended Agent Profile**:
|
||
- **Category**: `quick`
|
||
- **Skills**: []
|
||
|
||
**Parallelization**:
|
||
- **Can Run In Parallel**: NO (顺序执行)
|
||
- **Blocks**: 13.x
|
||
- **Blocked By**: 5.x, 6.x, 9.x, 10.x, 11.x (Wave 4)
|
||
|
||
**References**:
|
||
- `internal/bootstrap/stores.go` - 现有 stores 注册
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] Store 注册成功
|
||
|
||
**Commit**: YES
|
||
- Message: `feat(bootstrap): 注册充值相关 Store/Service/Handler`
|
||
|
||
---
|
||
|
||
- [ ] 12.2. 修改 internal/bootstrap/services.go：注册 RechargeService
|
||
|
||
**What to do**:
|
||
- 在 services struct 添加 `Recharge *rechargeService.Service`
|
||
- 在 initServices 中初始化，传递正确的依赖
|
||
|
||
**References**:
|
||
- `internal/bootstrap/services.go` - 现有 services 注册
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] Service 注册成功
|
||
- [ ] 依赖注入正确
|
||
|
||
**Commit**: YES (groups with 12.1)
|
||
|
||
---
|
||
|
||
- [ ] 12.3. 修改 internal/bootstrap/handlers.go：注册 RechargeHandler
|
||
|
||
**What to do**:
|
||
- 在 Handlers struct 添加 `H5Recharge *h5.RechargeHandler`
|
||
- 在 initHandlers 中初始化
|
||
|
||
**References**:
|
||
- `internal/bootstrap/handlers.go` - 现有 handlers 注册
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] Handler 注册成功
|
||
|
||
**Commit**: YES (groups with 12.1)
|
||
|
||
---
|
||
|
||
- [ ] 12.4. 验证依赖注入
|
||
|
||
**What to do**:
|
||
- `go build ./...` 验证编译
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 编译成功
|
||
- [ ] 无依赖循环
|
||
|
||
**Commit**: NO
|
||
|
||
---
|
||
|
||
- [ ] 13.1. 修改 internal/router/h5.go：注册充值相关路由
|
||
|
||
**What to do**:
|
||
- POST /api/h5/wallets/recharge
|
||
- GET /api/h5/wallets/recharge-check
|
||
- GET /api/h5/wallets/recharges
|
||
- GET /api/h5/wallets/recharges/:id
|
||
|
||
**Recommended Agent Profile**:
|
||
- **Category**: `quick`
|
||
- **Skills**: [`api-routing`]
|
||
|
||
**Parallelization**:
|
||
- **Blocks**: 14.x
|
||
- **Blocked By**: 12.x
|
||
|
||
**References**:
|
||
- `internal/router/h5.go` - 现有 H5 路由
|
||
- `docs/api-documentation-guide.md` - 路由注册规范
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 路由注册成功
|
||
|
||
**Commit**: YES
|
||
- Message: `feat(router): 注册充值和代购预检路由`
|
||
|
||
---
|
||
|
||
- [ ] 13.2. 修改 internal/router/admin.go：注册代购预检路由
|
||
|
||
**What to do**:
|
||
- POST /api/admin/orders/purchase-check
|
||
|
||
**References**:
|
||
- `internal/router/admin.go` - 现有 Admin 路由
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 路由注册成功
|
||
|
||
**Commit**: YES (groups with 13.1)
|
||
|
||
---
|
||
|
||
- [ ] 13.3. 验证路由绑定
|
||
|
||
**What to do**:
|
||
- 确保所有路由正确绑定到 Handler 方法
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 编译成功
|
||
- [ ] 路由绑定正确
|
||
|
||
**Commit**: NO
|
||
|
||
---
|
||
|
||
- [ ] 14.1. 修改 cmd/api/docs.go：添加 RechargeHandler
|
||
|
||
**What to do**:
|
||
- 在 Handlers 初始化中添加 `H5Recharge: h5.NewRechargeHandler(nil)`
|
||
|
||
**Recommended Agent Profile**:
|
||
- **Category**: `quick`
|
||
- **Skills**: []
|
||
|
||
**Parallelization**:
|
||
- **Blocks**: 15.x
|
||
- **Blocked By**: 13.x
|
||
|
||
**References**:
|
||
- `cmd/api/docs.go` - 文档生成器
|
||
- `docs/api-documentation-guide.md` - 新增 Handler 检查清单
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] Handler 添加成功
|
||
|
||
**Commit**: YES
|
||
- Message: `docs(api): 更新文档生成器支持充值接口`
|
||
|
||
---
|
||
|
||
- [ ] 14.2. 修改 cmd/gendocs/main.go：添加 RechargeHandler
|
||
|
||
**What to do**:
|
||
- 同 14.1
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] Handler 添加成功
|
||
|
||
**Commit**: YES (groups with 14.1)
|
||
|
||
---
|
||
|
||
- [ ] 14.3. 运行文档生成命令
|
||
|
||
**What to do**:
|
||
- `go run cmd/gendocs/main.go`
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 命令执行成功
|
||
- [ ] 生成新的 OpenAPI 文档
|
||
|
||
**Commit**: YES (groups with 14.1)
|
||
|
||
---
|
||
|
||
- [ ] 14.4. 验证生成的 OpenAPI 文档
|
||
|
||
**What to do**:
|
||
- 检查充值和代购相关接口是否出现在文档中
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 所有新接口出现在文档中
|
||
|
||
**Commit**: NO
|
||
|
||
---
|
||
|
||
### Wave 6: 测试和验证
|
||
|
||
#### Group M: 集成测试 (15.1-15.4)
|
||
|
||
- [ ] 15.1. 编写充值完整流程集成测试
|
||
|
||
**What to do**:
|
||
- 创建充值订单（无强充）
|
||
- 创建充值订单（首次强充验证）
|
||
- 创建充值订单（累计强充验证）
|
||
- 模拟支付回调
|
||
- 验证钱包余额增加
|
||
- 验证累计充值更新
|
||
- 验证一次性佣金触发
|
||
|
||
**Recommended Agent Profile**:
|
||
- **Category**: `unspecified-high`
|
||
- **Skills**: [`db-validation`]
|
||
|
||
**Parallelization**:
|
||
- **Can Run In Parallel**: NO (需要顺序验证)
|
||
- **Blocks**: 16.x, 17.x, 20.x
|
||
- **Blocked By**: 14.x
|
||
|
||
**References**:
|
||
- `tests/integration/` - 现有集成测试
|
||
- `docs/testing/test-connection-guide.md` - 测试规范
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 测试文件创建
|
||
- [ ] 所有测试场景通过
|
||
|
||
**Commit**: YES
|
||
- Message: `test(integration): 添加充值和代购订单集成测试`
|
||
|
||
---
|
||
|
||
- [ ] 15.2. 编写代购订单完整流程集成测试
|
||
|
||
**What to do**:
|
||
- 平台创建代购订单
|
||
- 验证订单自动完成
|
||
- 验证套餐激活
|
||
- 验证差价佣金计算
|
||
- 验证一次性佣金不触发
|
||
- 验证累计充值不更新
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 测试通过
|
||
|
||
**Commit**: YES (groups with 15.1)
|
||
|
||
---
|
||
|
||
- [ ] 15.3. 编写强充预检集成测试
|
||
|
||
**What to do**:
|
||
- 充值预检（各种强充场景）
|
||
- 套餐购买预检（各种强充场景）
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 测试通过
|
||
|
||
**Commit**: YES (groups with 15.1)
|
||
|
||
---
|
||
|
||
- [ ] 15.4. 验证测试
|
||
|
||
**What to do**:
|
||
- 运行所有集成测试
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 所有测试通过
|
||
|
||
**Commit**: NO
|
||
|
||
---
|
||
|
||
#### Group N: 验证和文档 (16.x-20.x)
|
||
|
||
- [ ] 16.1-16.4 功能手动验证
|
||
|
||
**What to do**:
|
||
- 验证充值预检接口
|
||
- 验证购买预检接口
|
||
- 验证充值订单创建
|
||
- 验证代购订单创建
|
||
|
||
**Recommended Agent Profile**:
|
||
- **Category**: `quick`
|
||
- **Skills**: [`db-validation`]
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 所有功能验证通过
|
||
|
||
**Commit**: NO
|
||
|
||
---
|
||
|
||
- [ ] 17.1-17.6 数据库验证
|
||
|
||
**What to do**:
|
||
- 使用 PostgreSQL MCP 验证数据库字段
|
||
- 验证数据正确性
|
||
|
||
**Recommended Agent Profile**:
|
||
- **Category**: `quick`
|
||
- **Skills**: [`db-validation`]
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 所有数据验证通过
|
||
|
||
**Commit**: NO
|
||
|
||
---
|
||
|
||
- [ ] 18.1-18.2 文档更新
|
||
|
||
**What to do**:
|
||
- 在 docs/ 创建功能总结文档
|
||
- 更新 README.md（可选）
|
||
|
||
**Recommended Agent Profile**:
|
||
- **Category**: `writing`
|
||
- **Skills**: []
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 文档创建成功
|
||
|
||
**Commit**: YES
|
||
- Message: `docs: 添加强充系统和代购订单功能文档`
|
||
|
||
---
|
||
|
||
- [ ] 19.1-19.5 代码规范检查
|
||
|
||
**What to do**:
|
||
- 运行 lsp_diagnostics 检查所有修改的文件
|
||
- 运行代码规范检查脚本
|
||
- 确保所有注释使用中文
|
||
- 确保所有常量定义在 pkg/constants/
|
||
- 确保所有错误码定义在 pkg/errors/
|
||
|
||
**Recommended Agent Profile**:
|
||
- **Category**: `quick`
|
||
- **Skills**: []
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 所有检查通过
|
||
|
||
**Commit**: NO
|
||
|
||
---
|
||
|
||
- [ ] 20.1-20.3 开发完成验证
|
||
|
||
**What to do**:
|
||
- 执行数据库迁移（开发环境）
|
||
- 运行完整测试套件
|
||
- 本地启动服务验证功能可用性
|
||
|
||
**Recommended Agent Profile**:
|
||
- **Category**: `quick`
|
||
- **Skills**: []
|
||
|
||
**Parallelization**:
|
||
- **Blocked By**: 19.x
|
||
|
||
**Acceptance Criteria**:
|
||
- [ ] 迁移成功
|
||
- [ ] 所有测试通过
|
||
- [ ] 服务正常启动
|
||
|
||
**Commit**: NO
|
||
|
||
---
|
||
|
||
## Commit Strategy
|
||
|
||
| After Task | Message | Files | Verification |
|
||
|------------|---------|-------|--------------|
|
||
| 1.1-1.4 | `feat(migration): 添加代购和强充配置字段迁移` | migrations/*.sql | migrate up |
|
||
| 2.1-2.5 | `feat(constants): 添加充值订单状态和配置常量` | pkg/constants/recharge.go | go build |
|
||
| 3.1-3.3 | `feat(errors): 添加充值和代购相关错误码` | pkg/errors/codes.go | go build |
|
||
| 4.1-4.4 | `feat(model): 添加代购和强充配置字段` | internal/model/*.go | go build |
|
||
| 5.1-5.9 | `feat(store): 新增 RechargeStore` | internal/store/postgres/recharge_store*.go | go test |
|
||
| 6.1-6.11 | `feat(service): 新增 RechargeService` | internal/service/recharge/*.go | go test |
|
||
| 7.1-7.6 | `feat(order): 支持代购订单和强充验证` | internal/service/order/*.go | go test |
|
||
| 8.1-8.5 | `fix(commission): 代购订单跳过一次性佣金` | internal/service/commission_calculation/*.go | go test |
|
||
| 9.1-9.7 | `feat(handler): 新增 RechargeHandler` | internal/handler/h5/recharge.go, internal/model/dto/recharge_dto.go | go build |
|
||
| 10.1-10.4 | `feat(handler): OrderHandler 支持代购` | internal/handler/admin/order.go | go build |
|
||
| 11.1-11.3 | `feat(callback): 支付回调支持充值订单` | internal/handler/callback/payment.go | go build |
|
||
| 12.1-12.4 | `feat(bootstrap): 注册充值相关依赖` | internal/bootstrap/*.go | go build |
|
||
| 13.1-13.3 | `feat(router): 注册充值和预检路由` | internal/router/*.go | go build |
|
||
| 14.1-14.4 | `docs(api): 更新文档生成器` | cmd/api/docs.go, cmd/gendocs/main.go | go run cmd/gendocs/main.go |
|
||
| 15.1-15.4 | `test(integration): 添加集成测试` | tests/integration/*.go | go test |
|
||
| 18.1-18.2 | `docs: 添加功能文档` | docs/*.md | - |
|
||
|
||
---
|
||
|
||
## Success Criteria
|
||
|
||
### Verification Commands
|
||
```bash
|
||
# 1. 编译验证
|
||
go build ./...
|
||
|
||
# 2. 单元测试
|
||
source .env.local && go test -v ./internal/store/postgres/... -run TestRecharge
|
||
source .env.local && go test -v ./internal/service/recharge/...
|
||
source .env.local && go test -v ./internal/service/order/... -run TestPurchaseOnBehalf
|
||
source .env.local && go test -v ./internal/service/commission_calculation/... -run TestPurchaseOnBehalf
|
||
|
||
# 3. 集成测试
|
||
source .env.local && go test -v ./tests/integration/... -run TestRecharge
|
||
source .env.local && go test -v ./tests/integration/... -run TestPurchaseOnBehalf
|
||
|
||
# 4. 文档生成
|
||
go run cmd/gendocs/main.go
|
||
|
||
# 5. 服务启动
|
||
source .env.local && go run cmd/api/main.go
|
||
```
|
||
|
||
### Final Checklist
|
||
- [ ] 所有数据库迁移执行成功
|
||
- [ ] 所有单元测试通过（覆盖率 ≥ 90%）
|
||
- [ ] 所有集成测试通过
|
||
- [ ] OpenAPI 文档包含新接口
|
||
- [ ] 服务正常启动
|
||
- [ ] 充值预检接口返回正确的强充要求
|
||
- [ ] 代购订单创建成功且不触发一次性佣金
|
||
- [ ] 所有注释使用中文
|
||
- [ ] 所有常量在 pkg/constants/
|
||
- [ ] 所有错误码在 pkg/errors/
|
||
|
||
---
|
||
|
||
## Risk Mitigation
|
||
|
||
1. **数据库迁移**: 先在测试环境验证，再执行生产
|
||
2. **支付回调幂等性**: 使用状态检查和事务保证
|
||
3. **强充验证绕过**: 后端强制验证，不依赖前端
|
||
4. **佣金计算复杂度**: 使用 table-driven tests 覆盖所有场景
|
||
|
||
---
|
||
|
||
**Plan Created**: 2026-01-31
|
||
**Estimated Duration**: 4-5 hours (with parallelization)
|
||
**Original Estimate**: 8-10 hours (sequential)
|
||
**Speedup**: ~50%
|