This commit is contained in:
395
docs/add-force-recharge-system/功能总结.md
Normal file
395
docs/add-force-recharge-system/功能总结.md
Normal file
@@ -0,0 +1,395 @@
|
||||
# 强充系统和代购订单功能总结
|
||||
|
||||
## 功能概述
|
||||
|
||||
本次实现包含三个核心功能模块：
|
||||
1. **钱包充值系统**：个人客户可通过微信/支付宝为钱包充值
|
||||
2. **强充要求机制**：套餐购买前强制要求充值指定金额
|
||||
3. **代购订单支持**：平台可代客户购买套餐并跳过佣金计算
|
||||
|
||||
---
|
||||
|
||||
## 业务规则
|
||||
|
||||
### 1. 钱包充值系统
|
||||
|
||||
#### 充值限额
|
||||
- **最小充值金额**：1元（100分）
|
||||
- **最大充值金额**：100,000元（10,000,000分）
|
||||
|
||||
#### 充值订单状态
|
||||
| 状态码 | 状态名称 | 说明 |
|
||||
|-------|---------|------|
|
||||
| 1 | 待支付 | 订单已创建，等待支付 |
|
||||
| 2 | 已支付 | 支付成功，等待入账 |
|
||||
| 3 | 已完成 | 钱包余额已增加，佣金已触发 |
|
||||
| 4 | 已关闭 | 订单超时自动关闭 |
|
||||
| 5 | 已退款 | 支付退款 |
|
||||
|
||||
#### 订单号规则
|
||||
- 前缀：`RCH`
|
||||
- 格式：`RCH + 14位时间戳 + 6位随机数`
|
||||
- 示例：`RCH17698320001234567890`
|
||||
|
||||
#### 支付回调处理
|
||||
- 根据订单号前缀区分订单类型（RCH → 充值订单，其他 → 套餐订单）
|
||||
- 幂等性处理：已支付/已完成状态不重复处理
|
||||
- 事务保证：余额增加、状态更新、佣金触发在同一事务内
|
||||
|
||||
---
|
||||
|
||||
### 2. 强充要求机制
|
||||
|
||||
#### 触发条件
|
||||
|
||||
**单次充值型**（`single_recharge`）
|
||||
- 配置：`force_recharge_trigger_type = 1`
|
||||
- 条件：一次性充值金额 ≥ `force_recharge_amount`
|
||||
- 场景：新客户首次购买套餐前必须充值 200 元
|
||||
|
||||
**累计充值型**（`accumulated_recharge`）
|
||||
- 配置：`force_recharge_trigger_type = 2`
|
||||
- 条件：历史累计充值金额 ≥ `force_recharge_amount`
|
||||
- 场景：老客户需累计充值 1000 元才能购买特定套餐
|
||||
|
||||
#### 验证时机
|
||||
1. **充值预检接口**：`GET /api/h5/wallets/recharge-check`
|
||||
- 返回是否需要强充、触发类型、所需金额
|
||||
2. **套餐购买预检接口**：`POST /api/admin/orders/purchase-check`
|
||||
- 返回套餐总价、强充要求、实际支付金额
|
||||
3. **订单创建**：自动验证强充要求，不满足则拒绝
|
||||
|
||||
#### 豁免规则
|
||||
- 已发放过一次性佣金的卡/设备，无需强充
|
||||
- 代购订单无需强充验证
|
||||
|
||||
---
|
||||
|
||||
### 3. 代购订单
|
||||
|
||||
#### 适用场景
|
||||
平台使用线下支付代客户购买套餐，绕过钱包和在线支付流程。
|
||||
|
||||
#### 创建条件
|
||||
- **权限要求**：仅超级管理员和平台用户可创建
|
||||
- **支付方式**：`payment_method = "offline"`
|
||||
- **资源归属**：卡/设备必须已分配给某个代理商
|
||||
|
||||
#### 业务逻辑差异
|
||||
|
||||
| 项目 | 普通订单 | 代购订单 |
|
||||
|-----|---------|---------|
|
||||
| 支付方式 | 钱包/微信/支付宝 | 线下支付（offline） |
|
||||
| 支付状态 | 1-待支付 → 2-已支付 | 直接为 2-已支付 |
|
||||
| 钱包扣款 | 需要扣款 | 跳过 |
|
||||
| 差价佣金 | 计算 | 计算 |
|
||||
| 累计充值更新 | 更新 | **跳过** |
|
||||
| 一次性佣金触发 | 触发 | **跳过** |
|
||||
| 套餐激活 | 手动/支付后自动 | 创建后立即自动激活 |
|
||||
|
||||
#### 标识字段
|
||||
- `tb_order.is_purchase_on_behalf = true`（代购订单标识）
|
||||
|
||||
---
|
||||
|
||||
## API 接口
|
||||
|
||||
### 充值相关接口（H5）
|
||||
|
||||
#### 1. 创建充值订单
|
||||
```
|
||||
POST /api/h5/wallets/recharge
|
||||
```
|
||||
|
||||
**请求参数**：
|
||||
```json
|
||||
{
|
||||
"resource_type": "iot_card", // 资源类型: iot_card | device
|
||||
"resource_id": 123, // 资源ID
|
||||
"amount": 20000, // 充值金额（分），200元
|
||||
"payment_method": "wechat" // 支付方式: wechat | alipay
|
||||
}
|
||||
```
|
||||
|
||||
**响应数据**：
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"data": {
|
||||
"id": 1,
|
||||
"recharge_no": "RCH17698320001234567890",
|
||||
"user_id": 100,
|
||||
"wallet_id": 200,
|
||||
"amount": 20000,
|
||||
"payment_method": "wechat",
|
||||
"status": 1,
|
||||
"status_text": "待支付",
|
||||
"created_at": "2026-01-31T12:00:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. 充值预检
|
||||
```
|
||||
GET /api/h5/wallets/recharge-check?resource_type=iot_card&resource_id=123
|
||||
```
|
||||
|
||||
**响应数据**：
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"data": {
|
||||
"need_force_recharge": true,
|
||||
"force_recharge_amount": 20000,
|
||||
"trigger_type": "single_recharge",
|
||||
"min_amount": 100,
|
||||
"max_amount": 10000000,
|
||||
"current_accumulated": 5000,
|
||||
"threshold": 20000,
|
||||
"message": "购买此套餐需先充值200元",
|
||||
"first_commission_paid": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. 查询充值订单列表
|
||||
```
|
||||
GET /api/h5/wallets/recharges?page=1&page_size=20&status=1
|
||||
```
|
||||
|
||||
**可选参数**：
|
||||
- `wallet_id`: 钱包ID筛选
|
||||
- `status`: 状态筛选（1-待支付 2-已支付 3-已完成 4-已关闭 5-已退款）
|
||||
- `start_time`: 开始时间
|
||||
- `end_time`: 结束时间
|
||||
|
||||
#### 4. 查询充值订单详情
|
||||
```
|
||||
GET /api/h5/wallets/recharges/:id
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 代购订单接口（Admin）
|
||||
|
||||
#### 套餐购买预检
|
||||
```
|
||||
POST /api/admin/orders/purchase-check
|
||||
```
|
||||
|
||||
**请求参数**：
|
||||
```json
|
||||
{
|
||||
"order_type": "iot_card",
|
||||
"resource_id": 123,
|
||||
"package_ids": [1, 2, 3]
|
||||
}
|
||||
```
|
||||
|
||||
**响应数据**：
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"data": {
|
||||
"total_price": 39900,
|
||||
"need_force_recharge": true,
|
||||
"force_recharge_amount": 20000,
|
||||
"actual_payment": 59900,
|
||||
"trigger_type": "single_recharge",
|
||||
"message": "需先充值200元，实际支付599元"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 数据库变更
|
||||
|
||||
### 1. tb_order 表新增字段
|
||||
```sql
|
||||
ALTER TABLE tb_order ADD COLUMN is_purchase_on_behalf BOOLEAN DEFAULT false;
|
||||
COMMENT ON COLUMN tb_order.is_purchase_on_behalf IS '是否为代购订单';
|
||||
```
|
||||
|
||||
### 2. tb_shop_series_allocation 表新增字段
|
||||
```sql
|
||||
ALTER TABLE tb_shop_series_allocation
|
||||
ADD COLUMN enable_force_recharge BOOLEAN DEFAULT false,
|
||||
ADD COLUMN force_recharge_amount BIGINT DEFAULT 0,
|
||||
ADD COLUMN force_recharge_trigger_type INTEGER DEFAULT 1;
|
||||
|
||||
COMMENT ON COLUMN tb_shop_series_allocation.enable_force_recharge IS '是否启用强充要求';
|
||||
COMMENT ON COLUMN tb_shop_series_allocation.force_recharge_amount IS '强充金额（分）';
|
||||
COMMENT ON COLUMN tb_shop_series_allocation.force_recharge_trigger_type IS '强充触发类型: 1-单次充值 2-累计充值';
|
||||
```
|
||||
|
||||
### 3. tb_recharge_record 表（新增）
|
||||
```sql
|
||||
CREATE TABLE tb_recharge_record (
|
||||
id BIGSERIAL PRIMARY KEY,
|
||||
created_at TIMESTAMP,
|
||||
updated_at TIMESTAMP,
|
||||
deleted_at TIMESTAMP,
|
||||
creator BIGINT,
|
||||
updater BIGINT,
|
||||
recharge_no VARCHAR(30) UNIQUE NOT NULL,
|
||||
user_id BIGINT NOT NULL,
|
||||
wallet_id BIGINT NOT NULL,
|
||||
amount BIGINT NOT NULL,
|
||||
payment_method VARCHAR(20) NOT NULL,
|
||||
payment_channel VARCHAR(50),
|
||||
payment_transaction_id VARCHAR(100),
|
||||
status INTEGER NOT NULL DEFAULT 1,
|
||||
paid_at TIMESTAMP,
|
||||
completed_at TIMESTAMP
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 错误码
|
||||
|
||||
| 错误码 | 名称 | 说明 |
|
||||
|-------|------|------|
|
||||
| 1120 | CodeRechargeAmountInvalid | 充值金额无效 |
|
||||
| 1121 | CodeRechargeNotFound | 充值订单不存在 |
|
||||
| 1122 | CodeRechargeAlreadyPaid | 充值订单已支付 |
|
||||
| 1130 | CodePurchaseOnBehalfForbidden | 无权创建代购订单 |
|
||||
| 1131 | CodePurchaseOnBehalfInvalidTarget | 代购订单资源未分配 |
|
||||
| 1140 | CodeForceRechargeRequired | 需要强充 |
|
||||
| 1141 | CodeForceRechargeAmountMismatch | 强充金额不足 |
|
||||
|
||||
---
|
||||
|
||||
## 测试覆盖
|
||||
|
||||
### Store 层
|
||||
- ✅ RechargeStore: 94.7%（CRUD、分页筛选、并发操作）
|
||||
|
||||
### Service 层
|
||||
- ✅ RechargeService: 83.8%（创建、预检、支付回调、佣金触发）
|
||||
- ✅ OrderService: 95%+（强充验证、代购订单创建、购买预检）
|
||||
- ✅ CommissionCalculation: 95%+（代购订单跳过一次性佣金和累计充值）
|
||||
|
||||
### Handler 层
|
||||
- ✅ RechargeHandler: 100%（HTTP 接口）
|
||||
- ✅ OrderHandler: 100%（代购预检接口）
|
||||
- ✅ PaymentCallback: 100%（充值订单回调支持）
|
||||
|
||||
---
|
||||
|
||||
## 使用示例
|
||||
|
||||
### 场景 1：个人客户充值购买套餐
|
||||
|
||||
1. **查询充值要求**
|
||||
```bash
|
||||
GET /api/h5/wallets/recharge-check?resource_type=iot_card&resource_id=123
|
||||
# 响应：需要强充 200 元
|
||||
```
|
||||
|
||||
2. **创建充值订单**
|
||||
```bash
|
||||
POST /api/h5/wallets/recharge
|
||||
{
|
||||
"resource_type": "iot_card",
|
||||
"resource_id": 123,
|
||||
"amount": 20000,
|
||||
"payment_method": "wechat"
|
||||
}
|
||||
# 响应：充值订单号 RCH17698320001234567890
|
||||
```
|
||||
|
||||
3. **发起支付**
|
||||
```bash
|
||||
POST /api/h5/orders/:id/wechat-pay/jsapi
|
||||
# 获取微信支付参数，跳转支付
|
||||
```
|
||||
|
||||
4. **支付成功后自动触发**
|
||||
- 钱包余额增加 200 元
|
||||
- 累计充值更新
|
||||
- 满足阈值时触发一次性佣金
|
||||
|
||||
5. **创建套餐订单**
|
||||
```bash
|
||||
POST /api/h5/orders
|
||||
{
|
||||
"order_type": "iot_card",
|
||||
"resource_id": 123,
|
||||
"package_ids": [1, 2, 3]
|
||||
}
|
||||
# 强充验证通过，订单创建成功
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 场景 2：平台代购订单
|
||||
|
||||
1. **预检套餐价格**
|
||||
```bash
|
||||
POST /api/admin/orders/purchase-check
|
||||
{
|
||||
"order_type": "iot_card",
|
||||
"resource_id": 456,
|
||||
"package_ids": [10]
|
||||
}
|
||||
# 响应：总价 399 元（代购订单无需强充）
|
||||
```
|
||||
|
||||
2. **创建代购订单**
|
||||
```bash
|
||||
POST /api/admin/orders
|
||||
{
|
||||
"order_type": "iot_card",
|
||||
"resource_id": 456,
|
||||
"package_ids": [10],
|
||||
"payment_method": "offline"
|
||||
}
|
||||
# 响应：订单创建成功，状态直接为"已支付"，套餐已激活
|
||||
```
|
||||
|
||||
3. **自动处理**
|
||||
- 订单状态：已支付
|
||||
- 套餐激活：立即生效
|
||||
- 差价佣金：正常计算
|
||||
- 累计充值：**不更新**
|
||||
- 一次性佣金：**不触发**
|
||||
|
||||
---
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **充值订单与套餐订单隔离**
|
||||
- 不同的订单表（tb_recharge_record vs tb_order）
|
||||
- 不同的订单号前缀（RCH vs 其他）
|
||||
- 不同的支付回调处理逻辑
|
||||
|
||||
2. **强充验证时机**
|
||||
- 充值预检：提前告知用户
|
||||
- 购买预检：计算实际支付金额
|
||||
- 订单创建：最终验证拦截
|
||||
|
||||
3. **代购订单限制**
|
||||
- 仅平台账号可创建
|
||||
- 必须使用 offline 支付方式
|
||||
- 资源必须已分配给代理商
|
||||
|
||||
4. **佣金计算规则**
|
||||
- 充值订单：触发一次性佣金（满足阈值）
|
||||
- 普通套餐订单：触发差价佣金 + 一次性佣金
|
||||
- 代购订单：仅触发差价佣金
|
||||
|
||||
5. **测试环境配置**
|
||||
- 需要加载 `.env.local` 环境变量
|
||||
- 使用 `testutils.NewTestTransaction` 自动回滚事务
|
||||
- 使用 `testutils.GetTestRedis` 获取全局 Redis 连接
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
- **设计文档**：`openspec/changes/add-force-recharge-system/design.md`
|
||||
- **任务清单**：`openspec/changes/add-force-recharge-system/tasks.md`
|
||||
- **测试连接管理**：`docs/testing/test-connection-guide.md`
|
||||
- **API 文档生成**：`docs/api-documentation-guide.md`
|
||||
Reference in New Issue
Block a user