team/ycc-proxy-server

Fork 0

Files

liangzai 08ff223ff8 v1.0

2025-12-02 19:57:10 +08:00

4.5 KiB

Raw Blame History

佣金冻结功能实现说明

功能需求

当订单单价 >= 配置阈值（默认100元）时，抽取订单单价的配置比例（默认10%）放到冻结余额，冻结配置天数（默认30天）后自动解冻。所有配置项都可在配置表中修改，但配置只在创建任务时读取，已创建的任务不受后续配置修改影响。

实现步骤

1. 运行SQL创建冻结任务表

# 执行SQL文件
mysql -u用户名 -p数据库名 < deploy/sql/agent_freeze_task_migration.sql

2. 生成Model

运行代码生成工具生成 AgentFreezeTaskModel：

# 在 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 添加字段

AgentFreezeTaskModel model.AgentFreezeTaskModel

3.2 初始化Model

在 NewServiceContext 函数中添加：

agentFreezeTaskModel := model.NewAgentFreezeTaskModel(db, cacheConf)

3.3 传递给AgentService

修改 NewAgentService 调用，添加参数：

agentService := service.NewAgentService(c, orderModel, agentModel, agentWalletModel,
    agentRelationModel, agentLinkModel, agentOrderModel, agentCommissionModel, agentRebateModel,
    agentUpgradeModel, agentWithdrawalModel, agentConfigModel, agentProductConfigModel,
    agentRealNameModel, agentWithdrawalTaxModel, agentFreezeTaskModel) // 添加这个参数

3.4 添加到ServiceContext返回

在返回的 ServiceContext 结构体中添加：

AgentFreezeTaskModel: agentFreezeTaskModel,

4. 添加配置项

在 agent_config 表中添加配置：

-- 冻结阈值（订单单价达到此金额才触发冻结，默认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 中）：

判断订单单价是否 >= 100元
如果是，从配置表读取冻结比例（默认10%）
计算冻结金额 = 订单单价 × 冻结比例（不超过佣金金额）
创建冻结任务记录（状态=待解冻，解冻时间=从配置读取的天数后）
更新钱包：Balance += (佣金金额 - 冻结金额)，FrozenBalance += 冻结金额

解冻逻辑（在 unfreezeCommission.go 中）：

查询冻结任务
检查解冻时间是否已到
更新冻结任务状态为已解冻
更新钱包：FrozenBalance -= 冻结金额，Balance += 冻结金额

6. 注意事项

Model生成：必须先运行SQL并生成Model，否则代码无法编译
配置项：需要在 agent_config 表中添加 commission_freeze_ratio 配置项
异步任务：解冻任务通过 asynq 延迟执行，确保在配置的天数后自动解冻
数据一致性：所有操作都在事务中执行，保证数据一致性

7. 测试建议

测试订单单价 < 100元：不应冻结
测试订单单价 >= 100元：应冻结订单单价的10%
测试冻结金额超过佣金：应冻结全部佣金
测试解冻任务：在配置的天数后应自动解冻

4.5 KiB Raw Blame History Unescape Escape