137 lines
5.2 KiB
Markdown
137 lines
5.2 KiB
Markdown
# 佣金冻结功能实现完成总结
|
||
|
||
## ✅ 已完成的工作
|
||
|
||
### 1. 数据库表
|
||
- ✅ 创建了 `agent_freeze_task` 表（`deploy/sql/agent_freeze_task_migration.sql`）
|
||
- ✅ 表结构包含：代理ID、订单ID、佣金ID、冻结金额、订单单价、冻结比例、状态、冻结时间、解冻时间等
|
||
|
||
### 2. 核心业务逻辑
|
||
- ✅ 修改了 `giveAgentCommission` 函数（`agentService.go`）
|
||
- 增加订单单价参数
|
||
- 实现冻结逻辑：订单单价 >= 100元时，冻结订单单价的10%（可配置）
|
||
- 创建冻结任务记录
|
||
- 更新钱包余额和冻结余额
|
||
|
||
### 3. 异步任务系统
|
||
- ✅ 创建了解冻任务处理器（`queue/unfreezeCommission.go`）
|
||
- ✅ 添加了 `SendUnfreezeTask` 方法到 `AsynqService`
|
||
- ✅ 在 `agentProcess.go` 中，代理处理成功后自动发送解冻任务
|
||
- ✅ 注册了解冻任务路由
|
||
|
||
### 4. 配置支持
|
||
- ✅ 冻结比例从配置表 `agent_config` 读取，配置键为 `commission_freeze_ratio`
|
||
|
||
### 5. ServiceContext 更新
|
||
- ✅ 添加了 `AgentFreezeTaskModel` 字段
|
||
- ✅ 初始化了 `agentFreezeTaskModel`
|
||
- ✅ 传递给 `AgentService`
|
||
- ✅ 添加到返回的 `ServiceContext`
|
||
|
||
## 📋 功能说明
|
||
|
||
### 触发条件
|
||
- 订单单价 >= 配置阈值（默认100元，可通过 `commission_freeze_threshold` 配置）
|
||
|
||
### 冻结规则
|
||
- 冻结阈值：从配置表读取（配置键：`commission_freeze_threshold`，默认100元）
|
||
- 冻结比例：从配置表读取（配置键：`commission_freeze_ratio`，默认10%）
|
||
- 冻结金额 = 订单单价 × 冻结比例
|
||
- 冻结金额不能超过佣金金额
|
||
- 例如：订单单价140元，佣金134元，冻结14元（140 × 10%），实际到账120元（134 - 14）
|
||
|
||
### 冻结时长
|
||
- 从配置表读取（配置键：`commission_freeze_days`，默认30天）
|
||
- 注意：配置只在创建任务时读取，已创建的任务不受后续配置修改影响
|
||
|
||
### 解冻机制
|
||
- 通过异步任务延迟执行
|
||
- 1个月后自动解冻
|
||
- 解冻时：`FrozenBalance -= 冻结金额`，`Balance += 冻结金额`
|
||
|
||
### 数据持久化
|
||
- 冻结任务记录在 `agent_freeze_task` 表中
|
||
- 保证任务的一致性和持久化
|
||
- 支持任务重试和状态追踪
|
||
|
||
## 🔧 还需要完成的工作
|
||
|
||
### 1. 添加配置项
|
||
在 `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天后解冻）');
|
||
```
|
||
|
||
### 2. 运行SQL创建表（如果还没运行）
|
||
```bash
|
||
mysql -u用户名 -p数据库名 < deploy/sql/agent_freeze_task_migration.sql
|
||
```
|
||
|
||
## 📝 代码文件清单
|
||
|
||
### 新增文件
|
||
1. `deploy/sql/agent_freeze_task_migration.sql` - 冻结任务表SQL
|
||
2. `app/main/api/internal/queue/unfreezeCommission.go` - 解冻任务处理器
|
||
3. `佣金冻结功能实现说明.md` - 实现说明文档
|
||
|
||
### 修改文件
|
||
1. `app/main/api/internal/service/agentService.go` - 修改佣金发放逻辑
|
||
2. `app/main/api/internal/service/asynqService.go` - 添加发送解冻任务方法
|
||
3. `app/main/api/internal/queue/agentProcess.go` - 添加发送解冻任务逻辑
|
||
4. `app/main/api/internal/queue/routes.go` - 注册解冻任务路由
|
||
5. `app/main/api/internal/types/taskname.go` - 添加解冻任务类型
|
||
6. `app/main/api/internal/types/payload.go` - 添加解冻任务负载类型
|
||
7. `app/main/api/internal/svc/servicecontext.go` - 添加 AgentFreezeTaskModel
|
||
|
||
## 🎯 功能流程
|
||
|
||
```
|
||
订单支付成功
|
||
↓
|
||
代理处理（AgentProcess）
|
||
↓
|
||
发放佣金（giveAgentCommission）
|
||
↓
|
||
判断：订单单价 >= 100元？
|
||
├─ 是 → 计算冻结金额（订单单价 × 10%）
|
||
│ 创建冻结任务记录
|
||
│ 更新钱包：Balance += (佣金-冻结金额), FrozenBalance += 冻结金额
|
||
│ 发送解冻异步任务（延迟配置天数）
|
||
│
|
||
└─ 否 → 正常发放佣金，不冻结
|
||
↓
|
||
配置天数后
|
||
↓
|
||
解冻任务执行（UnfreezeCommissionHandler）
|
||
↓
|
||
更新冻结任务状态为已解冻
|
||
↓
|
||
更新钱包：FrozenBalance -= 冻结金额, Balance += 冻结金额
|
||
```
|
||
|
||
## ✅ 代码检查
|
||
- ✅ 所有文件已通过编译检查
|
||
- ✅ 没有 lint 错误
|
||
- ✅ ServiceContext 已正确更新
|
||
- ✅ 异步任务路由已注册
|
||
|
||
## 🚀 下一步
|
||
1. 运行SQL创建表（如果还没运行）
|
||
2. 添加配置项到 `agent_config` 表
|
||
3. 测试功能：
|
||
- 测试订单单价 < 100元：不应冻结
|
||
- 测试订单单价 >= 100元：应冻结订单单价的10%
|
||
- 测试冻结金额超过佣金：应冻结全部佣金
|
||
- 测试解冻任务：在配置的天数后应自动解冻
|
||
|