huang
e87513541b
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 5m41s
- 新增佣金计算服务，支持一次性佣金和返佣计算 - 新增 ShopSeriesOneTimeCommissionTier 模型和存储层 - 新增两个数据库迁移：一次性佣金表和订单佣金字段 - 更新 Commission 模型，新增佣金来源和关联字段 - 更新 CommissionRecord 存储层，支持一次性佣金查询 - 更新 MyCommission 服务，集成一次性佣金计算逻辑 - 更新 ShopCommission 服务，支持一次性佣金统计 - 新增佣金计算异步任务处理器 - 更新 API 路由，新增一次性佣金相关端点 - 归档 OpenSpec 变更文档，同步规范到主规范库
3.0 KiB
3.0 KiB
Why
Phase 4 完成了订单与支付流程，现在需要实现一次性佣金计算。当终端用户购买套餐时，各级代理根据成本价差获得收入，并根据配置的触发条件（一次性充值阈值/累计充值阈值）发放一次性佣金。
What Changes
CommissionRecord 模型简化：
- 移除冻结/解冻相关字段（unfreeze_days, unfrozen_at 等）
- 移除 rule_id（不再关联复杂规则）
- 移除 agent_id（改用 shop_id，佣金归属店铺而非个人账号）
- 保留：shop_id, order_id, amount, status, released_at, balance_after
- 新增：commission_source（成本价差/一次性佣金/梯度佣金）
- 新增：iot_card_id/device_id（关联的卡/设备）
- 新增：remark（备注）
佣金计算逻辑：
-
成本价差收入（每笔订单必触发）
- 终端销售代理：售价 - 自己的成本价 = 收入
- 中间层级代理：下级的成本价 - 自己的成本价 = 收入
- 各级代理按自己的成本价差计算，确保每级都有利润
-
一次性佣金（满足条件触发一次）
- 触发类型 A：一次性充值 ≥ 阈值
- 触发类型 B：累计充值 ≥ 阈值
- 每张卡/设备只触发一次
- 佣金金额从 ShopSeriesCommissionTier 获取（支持梯度）
-
多级分佣
- 订单支付成功后，遍历代理层级
- 每级代理计算成本价差收入
- 检查一次性佣金触发条件
新增 API：
- 佣金记录列表查询（按店铺/时间/来源筛选）
- 佣金统计（总收入、各来源占比）
- 手动触发佣金计算（补偿机制）
业务规则：
- 佣金直接入账到店铺钱包，无冻结期
- 一次性佣金只发放一次，通过 card.first_commission_paid 标记
- 累计充值记录在 card.accumulated_recharge
- 梯度佣金根据配置的时间范围统计销量/销售额
Capabilities
New Capabilities
commission-calculation: 佣金计算 - 订单支付后自动计算各级代理的成本价差收入one-time-commission-trigger: 一次性佣金触发 - 根据充值阈值触发一次性佣金发放commission-record-query: 佣金记录查询 - 查询佣金明细和统计数据
Modified Capabilities
Impact
代码影响：
internal/model/commission.go- 简化 CommissionRecord 模型migrations/- 修改 tb_commission_record 表结构internal/handler/admin/- 新增/修改佣金查询 Handlerinternal/service/- 新增佣金计算 Serviceinternal/store/postgres/- 修改 CommissionRecordStoreinternal/task/- 佣金计算异步任务
API 影响：
- 修改
/api/admin/commission-records/*佣金记录查询 - 新增
/api/admin/commission-stats佣金统计
数据库影响：
- 修改表：
tb_commission_record（简化字段、新增字段）
依赖关系：
- 依赖 Phase 4（add-order-payment）完成
- 依赖 Phase 2 的 ShopSeriesCommissionTier 梯度配置
- 依赖 Phase 3 的卡/设备佣金状态字段