csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
Files
main
junhong_cmp_fiber/.sisyphus/plans/add-force-recharge-system.md
huang 62708892ec
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 6m2s
Details
文档
2026-01-31 13:06:30 +08:00

43 KiB
Raw Permalink Blame History

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

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 添加:
    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 添加:
    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:

    • 添加:
    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

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

Reference in New Issue View Git Blame Copy Permalink