## 1. 数据库迁移

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

## 2. 常量定义

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

## 3. 错误码定义

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

## 4. Model 层修改

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

## 5. RechargeStore 数据访问层

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

## 6. RechargeService 业务逻辑层

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

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

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

## 8. CommissionCalculationService 修改

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

## 9. RechargeHandler HTTP 接口层

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

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

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

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

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

## 12. Bootstrap 依赖注入

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

## 13. 路由注册

- [x] 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
- [x] 13.2 修改 internal/router/admin.go：注册代购预检路由
  - POST /api/admin/orders/purchase-check
- [x] 13.3 验证路由：确保所有路由正确绑定到 Handler 方法

## 14. API 文档生成器更新

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

## 15. 集成测试

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

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

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

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

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

## 18. 文档更新

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

## 19. 代码规范检查

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

## 20. 开发完成验证

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