# Delta Spec: shop-series-allocation

## MODIFIED Requirements

### Requirement: 为下级店铺分配套餐系列

系统 SHALL 允许代理为其直属下级店铺分配套餐系列。分配时 MUST 指定**一次性佣金金额上限**（代替原来的基础返佣配置），MAY 启用一次性佣金和强充配置。分配者只能分配自己已被分配的套餐系列。

**关键变更**：
- 移除 `commission_mode` 和 `commission_value` 字段（基础返佣配置）
- 新增 `one_time_commission_amount` 字段：代理能拿的一次性佣金金额上限（分）
- 一次性佣金计算采用**链式分配**：代理实际获得金额 = min(系列配置的梯度/固定金额, 上级给的上限)

**API 接口变更**：
- 移除请求/响应中的 `commission_mode`、`commission_value` 字段
- 新增 `one_time_commission_amount` 字段（分，必填）

#### Scenario: 成功分配套餐系列
- **WHEN** 代理为直属下级店铺分配一个自己拥有的套餐系列，设置 one_time_commission_amount = 5000（50元）
- **THEN** 系统创建分配记录，下级代理能拿的一次性佣金上限为 50 元

#### Scenario: 链式分配金额计算
- **WHEN** 平台给一级代理分配系列，one_time_commission_amount = 10000（100元）
- **AND** 一级代理给二级代理分配，one_time_commission_amount = 8000（80元）
- **AND** 二级代理给三级代理分配，one_time_commission_amount = 5000（50元）
- **THEN** 三级代理能拿的一次性佣金上限为 50 元
- **AND** 二级代理差价 = 80 - 50 = 30 元
- **AND** 一级代理差价 = 100 - 80 = 20 元

#### Scenario: 下级金额不能超过上级
- **WHEN** 代理尝试为下级分配，设置的 one_time_commission_amount 超过自己被分配的金额
- **THEN** 系统返回错误 "一次性佣金金额不能超过您的分配上限"

#### Scenario: 分配时启用一次性佣金和强充
- **WHEN** 代理为下级分配系列，one_time_commission_amount = 5000，启用一次性佣金，触发类型为累计充值，阈值 100000（1000元），启用强充，强充金额 10000（100元）
- **THEN** 系统保存配置：one_time_commission_amount = 5000，enable_one_time_commission = true，trigger = "accumulated_recharge"，threshold = 100000，enable_force_recharge = true，force_recharge_amount = 10000

#### Scenario: 尝试分配未拥有的系列
- **WHEN** 代理尝试分配自己未被分配的套餐系列
- **THEN** 系统返回错误 "您没有该套餐系列的分配权限"

#### Scenario: 尝试分配给非直属下级
- **WHEN** 代理尝试分配给非直属下级店铺
- **THEN** 系统返回错误 "只能为直属下级分配套餐"

#### Scenario: 重复分配同一系列
- **WHEN** 代理尝试为同一下级店铺重复分配同一套餐系列
- **THEN** 系统返回错误 "该店铺已分配此套餐系列"

---

### Requirement: 查询套餐系列分配列表

系统 SHALL 提供分配列表查询，支持按下级店铺筛选、按套餐系列筛选、按状态筛选。**响应 MUST 包含 one_time_commission_amount 字段**。

#### Scenario: 查询所有分配
- **WHEN** 代理查询分配列表，不带筛选条件
- **THEN** 系统返回该代理创建的所有分配记录，每条记录包含 one_time_commission_amount 字段

#### Scenario: 按店铺筛选
- **WHEN** 代理指定下级店铺 ID 筛选
- **THEN** 系统只返回该店铺的分配记录，记录包含 one_time_commission_amount 字段

#### Scenario: 响应包含一次性佣金金额
- **WHEN** 查询分配列表或详情
- **THEN** 每条记录包含 one_time_commission_amount 字段（分）

---

### Requirement: 更新套餐系列分配

系统 SHALL 允许代理更新分配的一次性佣金金额、一次性佣金配置和强充配置。**API 请求 MUST 支持更新 one_time_commission_amount 字段**。

#### Scenario: 更新一次性佣金金额
- **WHEN** 代理将 one_time_commission_amount 从 5000 改为 6000
- **THEN** 系统更新分配记录，后续一次性佣金按新金额计算

#### Scenario: 更新金额不能超过上级上限
- **WHEN** 代理尝试将 one_time_commission_amount 更新为超过自己被分配上限的值
- **THEN** 系统返回错误 "一次性佣金金额不能超过您的分配上限"

#### Scenario: 更新强充配置
- **WHEN** 代理将 enable_force_recharge 从 false 改为 true，设置 force_recharge_amount = 10000
- **THEN** 系统更新分配记录，后续下级客户需遵守新强充要求

#### Scenario: 更新不存在的分配
- **WHEN** 代理更新不存在的分配 ID
- **THEN** 系统返回 "分配记录不存在" 错误

---

### Requirement: 平台分配套餐系列

平台管理员 SHALL 能够为一级代理分配套餐系列，指定一次性佣金金额上限。平台作为分配链顶端，其金额上限由系列配置决定。

#### Scenario: 平台为一级代理分配
- **WHEN** 平台管理员为一级代理分配套餐系列，设置 one_time_commission_amount = 10000（100元）
- **THEN** 系统创建分配记录，一级代理能拿的一次性佣金上限为 100 元

#### Scenario: 平台金额不能超过系列配置
- **WHEN** 套餐系列配置的一次性佣金固定金额为 15000（150元）
- **AND** 平台尝试为一级代理分配，one_time_commission_amount = 20000（200元）
- **THEN** 系统返回错误 "一次性佣金金额不能超过系列配置上限"

#### Scenario: 平台配置强充要求
- **WHEN** 平台为一级代理分配系列，启用强充，force_recharge_amount = 10000
- **THEN** 系统保存强充配置，一级代理的客户需遵守强充要求

---

## ADDED Requirements

### Requirement: 套餐分配依赖系列分配

系统 SHALL 要求在分配套餐给下级店铺之前，必须先分配对应的套餐系列。

#### Scenario: 先分配系列再分配套餐
- **WHEN** 代理尝试为下级分配套餐 A（属于系列 X）
- **AND** 下级店铺已被分配系列 X
- **THEN** 系统允许创建套餐分配，并关联到系列分配记录

#### Scenario: 未分配系列时分配套餐失败
- **WHEN** 代理尝试为下级分配套餐 A（属于系列 X）
- **AND** 下级店铺未被分配系列 X
- **THEN** 系统返回错误 "请先分配该套餐所属的系列"

#### Scenario: 删除系列分配时检查套餐分配
- **WHEN** 代理尝试删除系列分配
- **AND** 存在依赖该系列分配的套餐分配
- **THEN** 系统返回错误 "存在关联的套餐分配，无法删除"

---

### Requirement: 套餐分配精简

套餐分配（ShopPackageAllocation）SHALL 只管理成本价，一次性佣金配置移到系列分配。

#### Scenario: 套餐分配只包含成本价
- **WHEN** 创建套餐分配
- **THEN** 请求/响应只包含 cost_price 字段
- **AND** 不包含 one_time_commission_amount 字段

#### Scenario: 套餐分配关联系列分配
- **WHEN** 创建套餐分配
- **THEN** 系统自动关联对应的系列分配（通过 series_allocation_id）

---

## REMOVED Requirements

### Requirement: 梯度返佣配置

**Reason**: 已在之前版本移除，此处确认删除状态

**Migration**: 使用一次性佣金的梯度模式替代

---

### Requirement: 基础返佣配置

**Reason**: commission_mode 和 commission_value 字段被 one_time_commission_amount 替代

**Migration**:
- 旧字段 commission_mode（百分比/固定值）和 commission_value 移除
- 新字段 one_time_commission_amount（分）表示代理能拿的一次性佣金上限
- 成本价差收入的计算不变，仍从套餐分配的 cost_price 计算
