huang
e87513541b
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 5m41s
- 新增佣金计算服务，支持一次性佣金和返佣计算 - 新增 ShopSeriesOneTimeCommissionTier 模型和存储层 - 新增两个数据库迁移：一次性佣金表和订单佣金字段 - 更新 Commission 模型，新增佣金来源和关联字段 - 更新 CommissionRecord 存储层，支持一次性佣金查询 - 更新 MyCommission 服务，集成一次性佣金计算逻辑 - 更新 ShopCommission 服务，支持一次性佣金统计 - 新增佣金计算异步任务处理器 - 更新 API 路由，新增一次性佣金相关端点 - 归档 OpenSpec 变更文档，同步规范到主规范库
78 lines
3.0 KiB
Markdown
78 lines
3.0 KiB
Markdown
## 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（备注）
|
||
|
||
**佣金计算逻辑：**
|
||
|
||
1. **成本价差收入**（每笔订单必触发）
|
||
- 终端销售代理：售价 - 自己的成本价 = 收入
|
||
- 中间层级代理：下级的成本价 - 自己的成本价 = 收入
|
||
- 各级代理按自己的成本价差计算，确保每级都有利润
|
||
|
||
2. **一次性佣金**（满足条件触发一次）
|
||
- 触发类型 A：一次性充值 ≥ 阈值
|
||
- 触发类型 B：累计充值 ≥ 阈值
|
||
- 每张卡/设备只触发一次
|
||
- 佣金金额从 ShopSeriesCommissionTier 获取（支持梯度）
|
||
|
||
3. **多级分佣**
|
||
- 订单支付成功后，遍历代理层级
|
||
- 每级代理计算成本价差收入
|
||
- 检查一次性佣金触发条件
|
||
|
||
**新增 API：**
|
||
- 佣金记录列表查询（按店铺/时间/来源筛选）
|
||
- 佣金统计（总收入、各来源占比）
|
||
- 手动触发佣金计算（补偿机制）
|
||
|
||
**业务规则：**
|
||
- 佣金直接入账到店铺钱包，无冻结期
|
||
- 一次性佣金只发放一次，通过 card.first_commission_paid 标记
|
||
- 累计充值记录在 card.accumulated_recharge
|
||
- 梯度佣金根据配置的时间范围统计销量/销售额
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
|
||
- `commission-calculation`: 佣金计算 - 订单支付后自动计算各级代理的成本价差收入
|
||
- `one-time-commission-trigger`: 一次性佣金触发 - 根据充值阈值触发一次性佣金发放
|
||
- `commission-record-query`: 佣金记录查询 - 查询佣金明细和统计数据
|
||
|
||
### Modified Capabilities
|
||
|
||
<!-- 无，CommissionRecord 的修改在 proposal 中说明，不需要单独 spec -->
|
||
|
||
## Impact
|
||
|
||
**代码影响：**
|
||
- `internal/model/commission.go` - 简化 CommissionRecord 模型
|
||
- `migrations/` - 修改 tb_commission_record 表结构
|
||
- `internal/handler/admin/` - 新增/修改佣金查询 Handler
|
||
- `internal/service/` - 新增佣金计算 Service
|
||
- `internal/store/postgres/` - 修改 CommissionRecordStore
|
||
- `internal/task/` - 佣金计算异步任务
|
||
|
||
**API 影响：**
|
||
- 修改 `/api/admin/commission-records/*` 佣金记录查询
|
||
- 新增 `/api/admin/commission-stats` 佣金统计
|
||
|
||
**数据库影响：**
|
||
- 修改表：`tb_commission_record`（简化字段、新增字段）
|
||
|
||
**依赖关系：**
|
||
- 依赖 Phase 4（add-order-payment）完成
|
||
- 依赖 Phase 2 的 ShopSeriesCommissionTier 梯度配置
|
||
- 依赖 Phase 3 的卡/设备佣金状态字段
|