107 lines
4.5 KiB
Markdown
107 lines
4.5 KiB
Markdown
# 佣金冻结功能实现说明
|
||
|
||
## 功能需求
|
||
当订单单价 >= 配置阈值（默认100元）时，抽取订单单价的配置比例（默认10%）放到冻结余额，冻结配置天数（默认30天）后自动解冻。所有配置项都可在配置表中修改，但配置只在创建任务时读取，已创建的任务不受后续配置修改影响。
|
||
|
||
## 实现步骤
|
||
|
||
### 1. 运行SQL创建冻结任务表
|
||
```bash
|
||
# 执行SQL文件
|
||
mysql -u用户名 -p数据库名 < deploy/sql/agent_freeze_task_migration.sql
|
||
```
|
||
|
||
### 2. 生成Model
|
||
运行代码生成工具生成 `AgentFreezeTaskModel`：
|
||
```bash
|
||
# 在 ycc-proxy-server 目录下运行
|
||
goctl model mysql datasource -url="数据库连接字符串" -table="agent_freeze_task" -dir="./app/main/model" -cache
|
||
```
|
||
|
||
### 3. 更新ServiceContext
|
||
在 `app/main/api/internal/svc/servicecontext.go` 中：
|
||
|
||
#### 3.1 添加字段
|
||
```go
|
||
AgentFreezeTaskModel model.AgentFreezeTaskModel
|
||
```
|
||
|
||
#### 3.2 初始化Model
|
||
在 `NewServiceContext` 函数中添加：
|
||
```go
|
||
agentFreezeTaskModel := model.NewAgentFreezeTaskModel(db, cacheConf)
|
||
```
|
||
|
||
#### 3.3 传递给AgentService
|
||
修改 `NewAgentService` 调用，添加参数：
|
||
```go
|
||
agentService := service.NewAgentService(c, orderModel, agentModel, agentWalletModel,
|
||
agentRelationModel, agentLinkModel, agentOrderModel, agentCommissionModel, agentRebateModel,
|
||
agentUpgradeModel, agentWithdrawalModel, agentConfigModel, agentProductConfigModel,
|
||
agentRealNameModel, agentWithdrawalTaxModel, agentFreezeTaskModel) // 添加这个参数
|
||
```
|
||
|
||
#### 3.4 添加到ServiceContext返回
|
||
在返回的 `ServiceContext` 结构体中添加：
|
||
```go
|
||
AgentFreezeTaskModel: agentFreezeTaskModel,
|
||
```
|
||
|
||
### 4. 添加配置项
|
||
在 `agent_config` 表中添加配置：
|
||
```sql
|
||
-- 冻结阈值（订单单价达到此金额才触发冻结，默认100元）
|
||
INSERT INTO `agent_config` (`config_key`, `config_value`, `config_type`, `description`)
|
||
VALUES ('commission_freeze_threshold', '100', 'rebate', '佣金冻结阈值（订单单价达到此金额才触发冻结，单位：元）');
|
||
|
||
-- 冻结比例（默认10%）
|
||
INSERT INTO `agent_config` (`config_key`, `config_value`, `config_type`, `description`)
|
||
VALUES ('commission_freeze_ratio', '0.1', 'rebate', '佣金冻结比例（例如：0.1表示10%）');
|
||
|
||
-- 解冻天数（默认30天，即1个月）
|
||
INSERT INTO `agent_config` (`config_key`, `config_value`, `config_type`, `description`)
|
||
VALUES ('commission_freeze_days', '30', 'rebate', '佣金冻结解冻天数（单位：天，例如：30表示30天后解冻）');
|
||
```
|
||
|
||
### 5. 代码已完成的修改
|
||
|
||
#### 5.1 已修改的文件
|
||
- ✅ `deploy/sql/agent_freeze_task_migration.sql` - 创建冻结任务表
|
||
- ✅ `app/main/api/internal/service/agentService.go` - 修改 `giveAgentCommission` 函数，增加冻结逻辑
|
||
- ✅ `app/main/api/internal/service/asynqService.go` - 添加 `SendUnfreezeTask` 方法
|
||
- ✅ `app/main/api/internal/queue/unfreezeCommission.go` - 创建解冻任务处理器
|
||
- ✅ `app/main/api/internal/queue/routes.go` - 注册解冻任务路由
|
||
- ✅ `app/main/api/internal/queue/agentProcess.go` - 在代理处理成功后发送解冻任务
|
||
- ✅ `app/main/api/internal/types/taskname.go` - 添加解冻任务类型
|
||
- ✅ `app/main/api/internal/types/payload.go` - 添加解冻任务负载类型
|
||
|
||
#### 5.2 核心逻辑说明
|
||
|
||
**冻结逻辑**（在 `giveAgentCommission` 中）：
|
||
1. 判断订单单价是否 >= 100元
|
||
2. 如果是，从配置表读取冻结比例（默认10%）
|
||
3. 计算冻结金额 = 订单单价 × 冻结比例（不超过佣金金额）
|
||
4. 创建冻结任务记录（状态=待解冻，解冻时间=从配置读取的天数后）
|
||
5. 更新钱包：`Balance += (佣金金额 - 冻结金额)`，`FrozenBalance += 冻结金额`
|
||
|
||
**解冻逻辑**（在 `unfreezeCommission.go` 中）：
|
||
1. 查询冻结任务
|
||
2. 检查解冻时间是否已到
|
||
3. 更新冻结任务状态为已解冻
|
||
4. 更新钱包：`FrozenBalance -= 冻结金额`，`Balance += 冻结金额`
|
||
|
||
### 6. 注意事项
|
||
|
||
1. **Model生成**：必须先运行SQL并生成Model，否则代码无法编译
|
||
2. **配置项**：需要在 `agent_config` 表中添加 `commission_freeze_ratio` 配置项
|
||
3. **异步任务**：解冻任务通过 asynq 延迟执行，确保在配置的天数后自动解冻
|
||
4. **数据一致性**：所有操作都在事务中执行，保证数据一致性
|
||
|
||
### 7. 测试建议
|
||
|
||
1. 测试订单单价 < 100元：不应冻结
|
||
2. 测试订单单价 >= 100元：应冻结订单单价的10%
|
||
3. 测试冻结金额超过佣金：应冻结全部佣金
|
||
4. 测试解冻任务：在配置的天数后应自动解冻
|
||
|