feat: 实现套餐管理模块,包含套餐系列、双状态管理、废弃模型清理
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 5m24s

- 新增套餐系列管理 (CRUD + 状态切换)
- 新增套餐管理 (CRUD + 启用/禁用 + 上架/下架双状态)
- 清理 8 个废弃分佣模型及对应数据库表
- Package 模型新增建议成本价、建议售价、上架状态字段
- 完整的 Store/Service/Handler 三层实现
- 包含单元测试和集成测试
- 归档 add-package-module change
- 新增多个 OpenSpec changes (订单支付、店铺套餐分配、一次性分佣、卡设备系列绑定)
This commit is contained in:
2026-01-27 19:55:47 +08:00
parent 30a0717316
commit 79c061b6fa
70 changed files with 7554 additions and 244 deletions

View File

@@ -0,0 +1,77 @@
## 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 4add-order-payment完成
- 依赖 Phase 2 的 ShopSeriesCommissionTier 梯度配置
- 依赖 Phase 3 的卡/设备佣金状态字段