huang
b18ecfeb55
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 6m29s
主要变更: - 新增 tb_shop_series_allocation 表，存储系列级别的一次性佣金配置 - ShopPackageAllocation 移除 one_time_commission_amount 字段 - PackageSeries 新增 enable_one_time_commission 字段控制是否启用一次性佣金 - 新增 /api/admin/shop-series-allocations CRUD 接口 - 佣金计算逻辑改为从 ShopSeriesAllocation 获取一次性佣金金额 - 删除废弃的 ShopSeriesOneTimeCommissionTier 模型 - OpenAPI Tag '系列分配' 和 '单套餐分配' 合并为 '套餐分配' 迁移脚本: - 000042: 重构佣金套餐模型 - 000043: 简化佣金分配 - 000044: 一次性佣金分配重构 - 000045: PackageSeries 添加 enable_one_time_commission 字段 测试: - 新增验收测试 (shop_series_allocation, commission_calculation) - 新增流程测试 (one_time_commission_chain) - 删除过时的单元测试（已被验收测试覆盖）
3.4 KiB
3.4 KiB
共识文档
Change: refactor-one-time-commission-allocation 确认时间: 2026-02-04T11:50:00+08:00 确认人: 用户（通过 Question_tool 逐条确认）
1. 要做什么
- 创建
tb_shop_series_allocation新表，专门管理系列分配和一次性佣金（已确认） - 将
one_time_commission_amount从ShopPackageAllocation移到新表（已确认） ShopPackageAllocation精简为只管成本价，添加series_allocation_id关联（已确认）PackageSeries添加enable_one_time_commission布尔字段（提升到顶层）（已确认）- 梯度模式下也实现链式分配（代理能拿的金额 = min(梯度匹配金额, 上级给的上限)）（已确认）
- 删除未使用的
ShopSeriesOneTimeCommissionTier表和相关代码（已确认） - 新增系列分配 API（CRUD）（已确认）
- 业务流程改造：必须先分配系列，再分配套餐（已确认）
- 佣金计算逻辑改为从系列分配获取佣金配置（已确认）
2. 不做什么
- 不保留旧接口的兼容性（直接切换）（已确认）
- 不支持代理自定义梯度规则（所有代理使用平台统一规则）（已确认）
- 不在此次改造中修改前端交互流程（后续单独处理）（已确认）
3. 关键约束
- 遵循项目技术栈规范（Handler → Service → Store → Model）（已确认）
- 删除代码前必须确认无调用（
ShopSeriesOneTimeCommissionTier相关）（已确认） ShopSeriesCommissionStats的allocation_id需要重新关联到系列分配（已确认）
4. 验收标准
- 同一 shop + series 只存在一条系列分配记录（唯一约束）（已确认）
- 触发佣金时直接查询系列分配，不再有"取第一个"的 hack（已确认）
enable_one_time_commission可通过 SQL WHERE 直接查询（已确认）- 分配套餐前必须先分配系列，否则报错（已确认）
- 使用新工作流生成的验收测试和流程测试全部通过（已确认）
讨论背景
用户发现一次性佣金架构存在设计问题：
- 概念与存储错位：一次性佣金是"系列级"概念，但
one_time_commission_amount存储在"套餐分配"（ShopPackageAllocation）中 - 数据冗余：同一系列的多个套餐分配时，佣金配置需要重复设置
- 隐性假设：代码靠"取第一个"（
GetByShopAndSeries+LIMIT 1）来获取佣金，假设同系列配置相同但没有约束保证 enable藏在 JSON 里：判断是否启用一次性佣金需要解析 JSON，无法高效查询- 废弃代码：
ShopSeriesOneTimeCommissionTier表定义了但完全没有被使用
关键决策记录
| 决策点 | 选择 | 原因 |
|---|---|---|
| 佣金存储位置 | 新建 ShopSeriesAllocation 表 |
职责分离：系列分配管佣金，套餐分配只管成本价 |
| 梯度模式下的分配 | 链式分配（min(梯度匹配, 上级上限)） | 保持与固定模式一致的业务逻辑 |
| 数据迁移 | 不做（开发阶段） | 现阶段无需迁移生产数据 |
| 旧接口兼容 | 不保留 | 简化实现，直接切换 |
| 代理自定义梯度 | 不支持 | 所有代理使用平台统一规则，简化配置 |
| 测试策略 | 使用新工作流验收测试 | 替代原有意义不大的测试 |
签字确认: 用户已通过 Question_tool 逐条确认以上内容