junhong_cmp_fiber/openspec/changes/archive/2026-01-29-add-one-time-commission/tasks.md

## 1. ShopSeriesAllocation 模型更新（一次性佣金配置）

- [x] 1.1 修改 `internal/model/shop_series_allocation.go`，新增一次性佣金配置字段
- [x] 1.2 新增 enable_one_time_commission 字段（bool，是否启用）
- [x] 1.3 新增 one_time_commission_type 字段（varchar: fixed-固定, tiered-梯度）
- [x] 1.4 新增 one_time_commission_trigger 字段（varchar: single_recharge-首充, accumulated_recharge-累计充值）
- [x] 1.5 新增 one_time_commission_threshold 字段（bigint，触发阈值分）
- [x] 1.6 新增 one_time_commission_mode 字段（varchar: fixed-固定金额, percent-百分比）
- [x] 1.7 新增 one_time_commission_value 字段（bigint，返佣值分或千分比）

## 2. 新增 ShopSeriesOneTimeCommissionTier 模型

- [x] 2.1 创建 `internal/model/shop_series_one_time_commission_tier.go`
- [x] 2.2 定义 ShopSeriesOneTimeCommissionTier 模型（allocation_id, tier_type, threshold_value, commission_mode, commission_value, status）
- [x] 2.3 实现 TableName() 方法返回 "tb_shop_series_one_time_commission_tier"
- [x] 2.4 定义梯度类型常量（与 ShopSeriesCommissionTier 保持一致）

## 3. CommissionRecord 模型简化

- [x] 3.1 修改 `internal/model/commission.go`，简化 CommissionRecord 结构
- [x] 3.2 删除冻结相关字段（unfrozen_at 等）
- [x] 3.3 删除 rule_id、agent_id 字段
- [x] 3.4 新增 commission_source 字段（varchar: cost_diff, one_time, tier_bonus）
- [x] 3.5 新增 iot_card_id、device_id 字段
- [x] 3.6 新增 remark 字段

## 4. 数据库迁移

- [x] 4.1 创建迁移文件，为 tb_shop_series_allocation 添加一次性佣金字段
- [x] 4.2 创建 tb_shop_series_one_time_commission_tier 表
- [x] 4.3 添加索引（allocation_id, tier_type, threshold_value）
- [x] 4.4 修改 tb_commission_record 表结构
- [x] 4.5 删除冻结相关字段
- [x] 4.6 添加新字段（commission_source, iot_card_id, device_id, remark）
- [x] 4.7 添加索引（shop_id, order_id, commission_source, iot_card_id, device_id）
- [x] 4.8 本地执行迁移验证

## 5. DTO 更新

- [x] 5.1 更新 `internal/model/dto/shop_series_allocation.go`，新增一次性佣金配置 DTO
- [x] 5.2 定义 OneTimeCommissionConfig（type, trigger, threshold, mode, value）
- [x] 5.3 定义 OneTimeCommissionTierEntry（tier_type, threshold, mode, value）
- [x] 5.4 更新 CreateShopSeriesAllocationRequest，支持一次性佣金配置
- [x] 5.5 更新 ShopSeriesAllocationResponse，包含一次性佣金配置信息
- [x] 5.6 更新 `internal/model/dto/commission.go`，调整 CommissionRecordResponse
- [x] 5.7 定义 CommissionRecordListRequest（shop_id, commission_source, start_time, end_time, status）
- [x] 5.8 定义 CommissionStatsResponse（total_amount, cost_diff_amount, one_time_amount, tier_bonus_amount）
- [x] 5.9 定义 DailyCommissionStatsResponse

## 6. ShopSeriesOneTimeCommissionTier Store 创建

- [x] 6.1 创建 `internal/store/postgres/shop_series_one_time_commission_tier_store.go`
- [x] 6.2 实现 Create 方法
- [x] 6.3 实现 BatchCreate 方法（批量创建梯度档位）
- [x] 6.4 实现 ListByAllocationID 方法（查询某个分配的所有梯度）
- [x] 6.5 实现 DeleteByAllocationID 方法（删除某个分配的所有梯度）
- [x] 6.6 实现 Update 方法

## 7. CommissionRecord Store 更新

- [x] 7.1 更新 `internal/store/postgres/commission_record_store.go`，适配新模型
- [x] 7.2 更新 Create 方法
- [x] 7.3 更新 List 方法支持新筛选条件
- [x] 7.4 实现 GetStats 方法（统计总收入和各来源占比）
- [x] 7.5 实现 GetDailyStats 方法（每日统计）

## 8. 佣金计算 Service

- [x] 8.1 创建 `internal/service/commission_calculation/service.go`
- [x] 8.2 实现 CalculateCommission 主方法（协调整体计算流程）- 需修复编译错误
- [x] 8.3 实现 CalculateCostDiffCommission 方法（遍历代理层级计算成本价差）- 需修复编译错误
- [x] 8.4 实现 TriggerOneTimeCommissionForCard 方法（单卡购买场景）- 需修复编译错误
- [x] 8.5 实现 TriggerOneTimeCommissionForDevice 方法（设备购买场景）- 需修复编译错误
- [x] 8.6 实现 calculateOneTimeCommission 辅助方法（固定或梯度佣金计算）- 需修复编译错误
- [x] 8.7 实现 calculateFixedCommission 方法（固定佣金计算）- 需修复编译错误
- [x] 8.8 实现 calculateTieredCommission 方法（梯度佣金计算，查询 ShopSeriesCommissionStats）- 需修复编译错误
- [x] 8.9 实现 CreditCommission 方法（佣金入账到钱包）- 需修复编译错误

## 9. 异步任务

- [x] 9.1 创建 `internal/task/commission_calculation.go`，定义佣金计算任务类型
- [x] 9.2 实现任务处理函数 HandleCommissionCalculation
- [x] 9.3 在 OrderService.WalletPay 中添加任务发送逻辑
- [x] 9.4 在支付回调处理中添加任务发送逻辑
- [x] 9.5 在 Worker 中注册任务处理器

## 10. 佣金查询 Service

- [x] 10.1 更新 `internal/service/my_commission/service.go`，适配新模型
- [x] 10.2 实现 List 方法
- [x] 10.3 实现 Get 方法
- [x] 10.4 实现 GetStats 方法
- [x] 10.5 实现 GetDailyStats 方法

## 11. Handler 更新

- [x] 11.1 更新 `internal/handler/admin/my_commission.go`，适配新接口
- [x] 11.2 实现 List 接口
- [x] 11.3 实现 Get 接口
- [x] 11.4 实现 GetStats 接口
- [x] 11.5 实现 GetDailyStats 接口

## 12. Bootstrap 注册

- [x] 12.1 在 stores.go 中注册 ShopSeriesOneTimeCommissionTierStore
- [x] 12.2 在 services.go 中注册 CommissionCalculationService
- [x] 12.3 确认 MyCommissionService 注册正确

## 13. 路由更新

- [x] 13.1 确认 `/api/admin/my-commission/records` 路由
- [x] 13.2 添加 `/api/admin/my-commission/stats` 路由
- [x] 13.3 添加 `/api/admin/my-commission/daily-stats` 路由

## 14. 文档生成器更新

- [x] 14.1 更新 docs.go 和 gendocs/main.go
- [x] 14.2 执行文档生成验证

## 15. 测试

- [x] 15.1 ShopSeriesOneTimeCommissionTierStore 单元测试
- [x] 15.2 CommissionRecordStore 单元测试
- [x] 15.3 CommissionCalculationService 单元测试（覆盖成本价差计算）
- [x] 15.4 固定一次性佣金触发测试（单卡和设备场景）
- [x] 15.5 梯度一次性佣金触发测试（基于销售业绩选择档位）
- [x] 15.6 首充和累计充值触发条件测试
- [x] 15.7 佣金入账事务测试
- [x] 15.8 异步任务测试
- [x] 15.9 佣金统计 API 集成测试
- [x] 15.10 执行 `go test ./...` 确认通过

## 16. 最终验证

- [x] 16.1 执行 `go build ./...` 确认编译通过
- [x] 16.2 启动服务，配置固定一次性佣金并测试
- [x] 16.3 配置梯度一次性佣金并测试
- [x] 16.4 验证单卡购买场景的一次性佣金
- [x] 16.5 验证设备购买场景的一次性佣金（不按卡数倍增）
- [x] 16.6 验证梯度匹配逻辑（基于销售业绩统计）
- [x] 16.7 验证首充和累计充值触发条件
- [x] 16.8 验证 first_commission_paid 标记（防止重复发放）
- [x] 16.9 验证钱包余额正确增加
- [x] 16.10 验证佣金统计数据正确