This commit is contained in:
@@ -0,0 +1,82 @@
|
||||
## 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（异步处理佣金计算）
|
||||
Reference in New Issue
Block a user