junhong_cmp_fiber/openspec/changes/archive/2026-01-31-add-force-recharge-system/tasks.md

1. 数据库迁移

• 1.1 创建迁移文件：tb_order 表新增 is_purchase_on_behalf 字段
• 1.2 创建迁移文件：tb_shop_series_allocation 表新增强充配置字段（enable_force_recharge, force_recharge_amount）
• 1.3 在测试环境执行迁移并验证字段添加成功
• 1.4 验证迁移：检查字段默认值和数据类型是否正确

2. 常量定义

• 2.1 在 pkg/constants/ 定义充值订单状态常量（待支付、已支付、已完成、已关闭）
• 2.2 在 pkg/constants/ 定义充值订单号前缀常量（RCH）
• 2.3 在 pkg/constants/ 定义线下支付方式常量（offline）
• 2.4 在 pkg/constants/ 定义强充相关 Redis Key 生成函数（可选，如缓存系列配置）
• 2.5 在 pkg/constants/ 定义充值金额限制常量（最小1元，最大100000元）

3. 错误码定义

• 3.1 在 pkg/errors/ 定义充值相关错误码（充值金额不符、充值订单不存在等）
• 3.2 在 pkg/errors/ 定义代购相关错误码（只有平台可使用线下支付、只能为下级代理代购等）
• 3.3 在 pkg/errors/ 定义强充验证错误码（必须充值X元等）

4. Model 层修改

• 4.1 修改 internal/model/order.go：新增 IsPurchaseOnBehalf 字段（bool, default false）
• 4.2 修改 internal/model/shop_series_allocation.go：新增 EnableForceRecharge 字段（bool, default false）
• 4.3 修改 internal/model/shop_series_allocation.go：新增 ForceRechargeAmount 字段（int64, default 0）
• 4.4 验证 Model 修改：运行 lsp_diagnostics 检查类型错误

5. RechargeStore 数据访问层

• 5.1 创建 internal/store/postgres/recharge_store.go
• 5.2 实现 Create 方法：创建充值订单
• 5.3 实现 GetByRechargeNo 方法：根据充值单号查询
• 5.4 实现 GetByID 方法：根据ID查询充值订单详情
• 5.5 实现 List 方法：分页查询充值订单列表，支持状态筛选、时间范围筛选
• 5.6 实现 UpdateStatus 方法：更新充值订单状态（支付成功回调时使用）
• 5.7 实现 UpdatePaymentInfo 方法：更新支付方式和支付时间
• 5.8 编写单元测试：测试覆盖率 ≥ 90%
• 5.9 验证测试：运行测试并确保全部通过

6. RechargeService 业务逻辑层

• 6.1 创建 internal/service/recharge/service.go
• 6.2 实现 Create 方法：创建充值订单
  • 验证资源存在（卡/设备）
  • 验证充值金额范围（1元~100000元）
  • 检查强充要求并验证金额
  • 生成充值单号（RCH + 时间戳 + 随机数）
  • 创建充值订单记录
• 6.3 实现 GetRechargeCheck 方法：充值预检
  • 查询资源（卡/设备）
  • 查询系列分配配置
  • 判断是否需要强充
  • 返回强充要求、允许金额范围、提示信息
• 6.4 实现 GetByID 方法：查询充值订单详情（数据权限过滤）
• 6.5 实现 List 方法：查询充值订单列表（分页、筛选、数据权限过滤）
• 6.6 实现 HandlePaymentCallback 方法：处理支付回调
  • 幂等性检查（检查订单状态）
  • 使用数据库事务：更新订单状态 → 增加钱包余额 → 更新累计充值 → 触发佣金判断
  • 钱包余额更新使用原子操作
• 6.7 实现 updateAccumulatedRecharge 私有方法：更新卡/设备的累计充值金额
• 6.8 实现 triggerOneTimeCommissionIfNeeded 私有方法：检查并触发一次性佣金
• 6.9 实现 checkForceRechargeRequirement 私有方法：检查强充要求（供创建订单时使用）
• 6.10 编写单元测试：测试覆盖率 ≥ 90%（包含各种充值场景、强充验证、支付回调幂等性）
• 6.11 验证测试：运行测试并确保全部通过

7. OrderService 修改（代购订单和强充验证）

• 7.1 修改 internal/service/order/service.go：Create 方法增加强充验证
  • 调用预检逻辑获取强充要求
  • 验证支付金额是否符合强充要求
  • 不符合则返回错误
• 7.2 新增 CreatePurchaseOnBehalf 方法：创建代购订单
  • 验证权限（只有平台可以使用线下支付）
  • 查询资源归属代理（buyer_id）
  • 查询买家的成本价
  • 创建订单（is_purchase_on_behalf = true, payment_method = offline, payment_status = 2）
  • 自动激活套餐（创建 PackageUsage）
  • 触发佣金计算任务
• 7.3 新增 GetPurchaseCheck 方法：套餐购买预检
  • 查询套餐总价
  • 检查强充要求
  • 计算实际支付金额和钱包到账金额
  • 返回预检信息（含提示消息）
• 7.4 修改支付成功后的处理逻辑：增加 is_purchase_on_behalf 判断
  • 如果是代购订单，跳过钱包扣款
  • 如果是普通订单，正常扣款
• 7.5 编写单元测试：测试代购订单创建、强充验证、预检逻辑
• 7.6 验证测试：运行测试并确保全部通过

8. CommissionCalculationService 修改

• 8.1 修改 internal/service/commission_calculation/service.go：CalculateCommission 方法增加代购订单判断
  • 差价佣金：所有订单都计算（包括代购）
  • 累计充值更新：仅非代购订单更新（is_purchase_on_behalf = false）
  • 一次性佣金：仅非代购订单触发（is_purchase_on_behalf = false）
• 8.2 修改 updateAccumulatedRecharge 方法：增加代购订单检查
  • 如果 is_purchase_on_behalf = true，直接返回，不更新累计充值
  • 如果 is_purchase_on_behalf = false，正常更新累计充值
• 8.3 修改 triggerOneTimeCommission 方法：增加代购订单检查
  • 如果 is_purchase_on_behalf = true，直接返回，不触发一次性佣金
  • 如果 is_purchase_on_behalf = false，正常检查阈值并触发佣金
• 8.4 编写单元测试：使用 table-driven tests 测试各种场景（普通订单、代购订单、充值订单）
• 8.5 验证测试：运行测试并确保全部通过

9. RechargeHandler HTTP 接口层

• 9.1 创建 internal/handler/h5/recharge.go
• 9.2 实现 POST /api/h5/wallets/recharge：创建充值订单
  • 参数验证（resource_type, resource_id, amount）
  • 调用 Service 创建充值订单
  • 返回充值订单信息
• 9.3 实现 GET /api/h5/wallets/recharge-check：充值预检
  • 参数验证（resource_type, resource_id）
  • 调用 Service 获取强充要求
  • 返回预检信息
• 9.4 实现 GET /api/h5/wallets/recharges：查询充值订单列表
  • 支持分页参数（page, page_size）
  • 支持状态筛选（status）
  • 支持时间范围筛选（start_time, end_time）
• 9.5 实现 GET /api/h5/wallets/recharges/:id：查询充值订单详情
• 9.6 为所有接口添加中文注释（路由路径、参数说明、响应说明）
• 9.7 验证接口：运行 lsp_diagnostics 检查类型错误

10. OrderHandler 修改（代购订单接口）

• 10.1 修改 internal/handler/admin/order.go：Create 方法增加代购订单支持
  • 检查 payment_method = offline 时，验证用户类型为 Platform
  • 如果是平台账号且线下支付，调用 CreatePurchaseOnBehalf
  • 否则调用正常的 Create 方法
• 10.2 新增 POST /api/admin/orders/purchase-check：套餐购买预检
  • 参数验证（order_type, resource_id, package_ids）
  • 调用 Service 获取预检信息
  • 返回预检结果
• 10.3 为新增接口添加中文注释
• 10.4 验证接口：运行 lsp_diagnostics 检查类型错误

11. PaymentCallback 修改（充值订单回调）

• 11.1 修改 internal/handler/callback/payment.go：WechatPayCallback 方法增加充值订单判断
  • 根据订单号前缀判断类型（RCH 开头 → 充值订单）
  • 如果是充值订单，调用 RechargeService.HandlePaymentCallback
  • 如果是套餐订单，调用 OrderService.HandlePaymentCallback
• 11.2 修改 AlipayCallback 方法：增加充值订单判断（同上）
• 11.3 验证修改：运行 lsp_diagnostics 检查类型错误

12. Bootstrap 依赖注入

• 12.1 修改 internal/bootstrap/stores.go：注册 RechargeStore
• 12.2 修改 internal/bootstrap/services.go：注册 RechargeService
• 12.3 修改 internal/bootstrap/handlers.go：注册 RechargeHandler（H5）
• 12.4 验证依赖注入：确保所有依赖正确传递

13. 路由注册

• 13.1 修改 internal/router/h5.go：注册充值相关路由
  • POST /api/h5/wallets/recharge
  • GET /api/h5/wallets/recharge-check
  • GET /api/h5/wallets/recharges
  • GET /api/h5/wallets/recharges/:id
• 13.2 修改 internal/router/admin.go：注册代购预检路由
  • POST /api/admin/orders/purchase-check
• 13.3 验证路由：确保所有路由正确绑定到 Handler 方法

14. API 文档生成器更新

• 14.1 修改 cmd/api/docs.go：在 Handlers 初始化中添加 RechargeHandler
• 14.2 修改 cmd/gendocs/main.go：在 Handlers 初始化中添加 RechargeHandler
• 14.3 运行文档生成命令：go run cmd/gendocs/main.go
• 14.4 验证生成的 OpenAPI 文档：检查充值和代购相关接口是否出现

15. 集成测试

• 15.1 编写充值完整流程集成测试
  • 创建充值订单（无强充）
  • 创建充值订单（首次强充验证）
  • 创建充值订单（累计强充验证）
  • 模拟支付回调
  • 验证钱包余额增加
  • 验证累计充值更新
  • 验证一次性佣金触发
• 15.2 编写代购订单完整流程集成测试
  • 平台创建代购订单
  • 验证订单自动完成
  • 验证套餐激活
  • 验证差价佣金计算
  • 验证一次性佣金不触发
  • 验证累计充值不更新
• 15.3 编写强充预检集成测试
  • 充值预检（各种强充场景）
  • 套餐购买预检（各种强充场景）
• 15.4 验证测试：运行所有集成测试并确保通过

16. 功能手动验证（开发环境）

• 16.1 验证充值预检接口：调用接口确认返回正确的强充要求
• 16.2 验证购买预检接口：调用接口确认实际支付金额计算正确
• 16.3 验证充值订单创建：创建订单并确认数据库记录正确
• 16.4 验证代购订单创建：创建代购订单并确认套餐自动激活

17. 数据库验证（使用 PostgreSQL MCP）

• 17.1 验证 tb_order 表字段：检查 is_purchase_on_behalf 字段及默认值
• 17.2 验证 tb_shop_series_allocation 表字段：检查 enable_force_recharge 和 force_recharge_amount 字段
• 17.3 验证充值订单创建：执行创建后查询数据库确认记录正确
• 17.4 验证代购订单创建：执行创建后查询订单表和套餐使用表
• 17.5 验证累计充值更新：执行充值/购买后查询卡/设备的 accumulated_recharge 字段
• 17.6 验证佣金计算：执行订单后查询佣金记录表，确认代购订单不触发一次性佣金

18. 文档更新

• 18.1 在 docs/ 目录创建功能总结文档（中文，简要说明业务规则和 API 接口）
• 18.2 更新 README.md：添加强充系统和代购订单功能说明（可选）

19. 代码规范检查

• 19.1 运行 lsp_diagnostics 检查所有修改的文件
• 19.2 运行代码规范检查脚本（如有）
• 19.3 确保所有注释使用中文
• 19.4 确保所有常量定义在 pkg/constants/
• 19.5 确保所有错误码定义在 pkg/errors/

20. 开发完成验证

• 20.1 执行数据库迁移（开发环境）
• 20.2 运行完整测试套件并确保全部通过
• 20.3 本地启动服务验证功能可用性