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

Why

当前系统缺少完整的强充（强制充值）机制和代购订单支持，导致以下问题：(1) 个人客户无法直接给钱包充值，必须通过购买套餐间接充值；(2) 平台和代理无法为其他代理代购套餐（线下已收款场景）；(3) 一次性佣金触发机制不完善，代购订单错误触发佣金且累加充值金额；(4) 缺少强充预检接口，前端无法提前告知用户充值限制。这些限制影响了业务灵活性和用户体验，需要立即完善。

What Changes

• 新增钱包充值系统：实现个人客户直接充值钱包功能，包含充值订单（RechargeRecord）的创建、支付、回调处理，充值成功触发佣金计算
• 新增强充预检接口：提供钱包充值预检和套餐购买预检接口，返回强充要求、金额限制、实际支付金额等信息
• 新增代购订单功能：支持平台/代理给其他代理代购套餐，使用线下支付方式，订单标记为代购类型
• 扩展强充配置：ShopSeriesAllocation 模型新增 enable_force_recharge 和 force_recharge_amount 字段，支持累计充值强充配置（可选）
• 修复佣金计算逻辑：代购订单不触发一次性佣金，不累加 AccumulatedRecharge，确保佣金计算准确性
• 扩展订单模型：Order 模型新增 is_purchase_on_behalf 字段和 offline 支付方式，区分代购订单和普通订单
• 完善充值验证：创建充值订单和购买订单时强制验证强充要求，防止前端绕过限制

Capabilities

New Capabilities

• wallet-recharge: 钱包充值系统，包含充值订单创建、支付集成（微信/支付宝）、回调处理、充值成功后触发佣金计算
• force-recharge-check: 强充预检接口，包含钱包充值预检、套餐购买预检，返回强充要求和金额限制
• purchase-on-behalf: 代购订单功能，支持平台/代理为其他代理代购套餐，使用线下支付，区分代购和普通订单

Modified Capabilities

• commission-calculation: 修改佣金计算逻辑，代购订单不触发一次性佣金，不累加 AccumulatedRecharge
• order-management: 订单模型增加 is_purchase_on_behalf 字段，支持代购订单类型
• order-payment: 支付方式增加 offline 线下支付，代购订单创建后直接标记为已支付
• shop-series-allocation: 增加强充配置字段（enable_force_recharge、force_recharge_amount），支持累计充值强充设置

Impact

数据库变更

• tb_order 表：新增 is_purchase_on_behalf 字段（BOOLEAN），payment_method 增加 offline 枚举值
• tb_shop_series_allocation 表：新增 enable_force_recharge 字段（BOOLEAN）、force_recharge_amount 字段（BIGINT）
• tb_recharge_record 表：已存在但未使用，需要创建对应的 Store/Service/Handler
• 数据库迁移：需要创建迁移文件添加新字段

新增代码模块

• Store 层：RechargeStore（充值订单数据访问）
• Service 层：RechargeService（充值业务逻辑）、强充预检逻辑（在现有 Service 中）
• Handler 层：RechargeHandler（充值 HTTP 接口）、充值预检接口（在现有 Handler 中）
• Task 层：充值支付回调处理（在现有 callback handler 中扩展）

修改现有代码

• CommissionCalculationService：增加代购订单判断逻辑
• OrderService：增加代购订单创建逻辑、强充验证逻辑
• OrderHandler（admin）：增加平台创建代购订单接口
• ShopSeriesAllocationService：支持强充配置的创建和更新

API 变更

• 新增接口：
  • GET /api/h5/wallets/recharge-check - 钱包充值预检
  • POST /api/h5/recharge-records - 创建充值订单
  • GET /api/h5/recharge-records - 查询充值订单列表
  • GET /api/h5/recharge-records/:id - 查询充值订单详情
  • POST /api/h5/orders/purchase-check - 套餐购买预检
  • POST /api/admin/orders - 修改以支持代购订单创建
• 修改接口：
  • POST /api/admin/shop-series-allocations - 支持强充配置参数
  • PUT /api/admin/shop-series-allocations/:id - 支持强充配置更新

支付回调处理

• 微信支付回调：扩展支持充值订单的回调处理
• 支付宝回调：扩展支持充值订单的回调处理

业务逻辑影响

• 佣金计算：代购订单不触发一次性佣金，但仍计算差价佣金
• 累计充值：只有真实充值（个人客户充值或购买套餐）才累加 AccumulatedRecharge
• 强充触发：
  • 首次充值：必须充值阈值金额（OneTimeCommissionThreshold）
  • 累计充值：如果启用强充，必须充值固定金额（ForceRechargeAmount）
• 订单支付：代购订单创建后直接标记为已支付，跳过钱包扣款

测试影响

• 单元测试：需要为所有新增 Service 方法编写测试
• 集成测试：需要测试完整的充值流程、强充预检、代购订单流程
• 测试覆盖率：核心业务逻辑测试覆盖率需保持 ≥ 90%

性能考虑

• 预检接口响应时间 < 100ms（涉及数据库查询）
• 充值订单创建响应时间 < 200ms
• 支付回调处理时间 < 500ms（异步处理佣金计算）