# 共识文档

**Change**: refactor-one-time-commission-allocation
**确认时间**: 2026-02-04T11:50:00+08:00
**确认人**: 用户（通过 Question_tool 逐条确认）

---

## 1. 要做什么

- [x] 创建 `tb_shop_series_allocation` 新表，专门管理系列分配和一次性佣金（已确认）
- [x] 将 `one_time_commission_amount` 从 `ShopPackageAllocation` 移到新表（已确认）
- [x] `ShopPackageAllocation` 精简为只管成本价，添加 `series_allocation_id` 关联（已确认）
- [x] `PackageSeries` 添加 `enable_one_time_commission` 布尔字段（提升到顶层）（已确认）
- [x] 梯度模式下也实现链式分配（代理能拿的金额 = min(梯度匹配金额, 上级给的上限)）（已确认）
- [x] 删除未使用的 `ShopSeriesOneTimeCommissionTier` 表和相关代码（已确认）
- [x] 新增系列分配 API（CRUD）（已确认）
- [x] 业务流程改造：必须先分配系列，再分配套餐（已确认）
- [x] 佣金计算逻辑改为从系列分配获取佣金配置（已确认）

## 2. 不做什么

- [x] 不保留旧接口的兼容性（直接切换）（已确认）
- [x] 不支持代理自定义梯度规则（所有代理使用平台统一规则）（已确认）
- [x] 不在此次改造中修改前端交互流程（后续单独处理）（已确认）

## 3. 关键约束

- [x] 遵循项目技术栈规范（Handler → Service → Store → Model）（已确认）
- [x] 删除代码前必须确认无调用（`ShopSeriesOneTimeCommissionTier` 相关）（已确认）
- [x] `ShopSeriesCommissionStats` 的 `allocation_id` 需要重新关联到系列分配（已确认）

## 4. 验收标准

- [x] 同一 shop + series 只存在一条系列分配记录（唯一约束）（已确认）
- [x] 触发佣金时直接查询系列分配，不再有"取第一个"的 hack（已确认）
- [x] `enable_one_time_commission` 可通过 SQL WHERE 直接查询（已确认）
- [x] 分配套餐前必须先分配系列，否则报错（已确认）
- [x] 使用新工作流生成的验收测试和流程测试全部通过（已确认）

---

## 讨论背景

用户发现一次性佣金架构存在设计问题：

1. **概念与存储错位**：一次性佣金是"系列级"概念，但 `one_time_commission_amount` 存储在"套餐分配"（`ShopPackageAllocation`）中
2. **数据冗余**：同一系列的多个套餐分配时，佣金配置需要重复设置
3. **隐性假设**：代码靠"取第一个"（`GetByShopAndSeries` + `LIMIT 1`）来获取佣金，假设同系列配置相同但没有约束保证
4. **`enable` 藏在 JSON 里**：判断是否启用一次性佣金需要解析 JSON，无法高效查询
5. **废弃代码**：`ShopSeriesOneTimeCommissionTier` 表定义了但完全没有被使用

## 关键决策记录

| 决策点 | 选择 | 原因 |
|--------|------|------|
| 佣金存储位置 | 新建 `ShopSeriesAllocation` 表 | 职责分离：系列分配管佣金，套餐分配只管成本价 |
| 梯度模式下的分配 | 链式分配（min(梯度匹配, 上级上限)） | 保持与固定模式一致的业务逻辑 |
| 数据迁移 | 不做（开发阶段） | 现阶段无需迁移生产数据 |
| 旧接口兼容 | 不保留 | 简化实现，直接切换 |
| 代理自定义梯度 | 不支持 | 所有代理使用平台统一规则，简化配置 |
| 测试策略 | 使用新工作流验收测试 | 替代原有意义不大的测试 |

---

**签字确认**: 用户已通过 Question_tool 逐条确认以上内容