# 强充系统和代购订单功能 - 并行执行计划

## 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%