# Shop Series Allocation Specification Delta

## MODIFIED Requirements

### Requirement: Shop Series Allocation Data Model

套餐系列分配的数据模型SHALL重构为更细粒度的佣金配置结构，移除旧的 `base_commission` 模式，采用独立的一次性佣金和强制充值配置字段。

**字段定义**:
- `id` (number) - 分配ID
- `series_id` (number) - 套餐系列ID
- `series_name` (string) - 套餐系列名称
- `series_code` (string) - 套餐系列编码
- `shop_id` (number) - 被分配的店铺ID
- `shop_name` (string) - 被分配的店铺名称
- `allocator_shop_id` (number) - 分配者店铺ID，0表示平台分配
- `allocator_shop_name` (string) - 分配者店铺名称
- `enable_one_time_commission` (boolean) - 是否启用一次性佣金
- `one_time_commission_amount` (number) - 该代理能拿的一次性佣金金额上限（分）
- `one_time_commission_threshold` (number, optional) - 一次性佣金触发阈值（分）
- `one_time_commission_trigger` (string, optional) - 一次性佣金触发类型: "first_recharge" | "accumulated_recharge"
- `enable_force_recharge` (boolean) - 是否启用强制充值
- `force_recharge_amount` (number, optional) - 强制充值金额（分）
- `force_recharge_trigger_type` (number, optional) - 强充触发类型: 1(单次充值) | 2(累计充值)
- `status` (number) - 状态 (1:启用, 2:禁用)
- `created_at` (string) - 创建时间
- `updated_at` (string) - 更新时间

**创建请求字段** (`CreateShopSeriesAllocationRequest`):
- `series_id` (number, required) - 套餐系列ID
- `shop_id` (number, required) - 被分配的店铺ID
- `one_time_commission_amount` (number, required) - 一次性佣金金额上限（分）
- `enable_one_time_commission` (boolean, optional) - 是否启用一次性佣金
- `one_time_commission_threshold` (number, optional) - 一次性佣金触发阈值（分）
- `one_time_commission_trigger` (string, optional) - 一次性佣金触发类型
- `enable_force_recharge` (boolean, optional) - 是否启用强制充值
- `force_recharge_amount` (number, optional) - 强制充值金额（分）
- `force_recharge_trigger_type` (number, optional) - 强充触发类型

**更新请求字段** (`UpdateShopSeriesAllocationRequest`):
- 所有字段均为可选，允许部分更新
- `enable_one_time_commission` (boolean, optional)
- `one_time_commission_amount` (number, optional)
- `one_time_commission_threshold` (number, optional)
- `one_time_commission_trigger` (string, optional)
- `enable_force_recharge` (boolean, optional)
- `force_recharge_amount` (number, optional)
- `force_recharge_trigger_type` (number, optional)
- `status` (number, optional)

#### Scenario: 创建系列分配并启用一次性佣金

- **GIVEN** 平台管理员登录系统
- **AND** 系统中存在ID为1的套餐系列和ID为100的店铺
- **WHEN** 创建系列分配时提供以下配置:
  - `series_id`: 1
  - `shop_id`: 100
  - `one_time_commission_amount`: 5000
  - `enable_one_time_commission`: true
  - `one_time_commission_threshold`: 10000
  - `one_time_commission_trigger`: "first_recharge"
- **THEN** 系统SHALL创建系列分配记录
- **AND** 响应数据中 `allocator_shop_id` 为 0（平台分配）
- **AND** 响应数据中包含所有一次性佣金配置字段

#### Scenario: 创建系列分配并启用强制充值

- **GIVEN** 代理商A登录系统，shop_id为50
- **AND** 系统中存在ID为2的套餐系列和ID为101的下级代理店铺
- **WHEN** 创建系列分配时提供以下配置:
  - `series_id`: 2
  - `shop_id`: 101
  - `one_time_commission_amount`: 3000
  - `enable_force_recharge`: true
  - `force_recharge_amount`: 15000
  - `force_recharge_trigger_type`: 1 (单次充值)
- **THEN** 系统SHALL创建系列分配记录
- **AND** 响应数据中 `allocator_shop_id` 为 50（代理商A）
- **AND** 响应数据中包含所有强制充值配置字段

#### Scenario: 更新系列分配的一次性佣金配置

- **GIVEN** 系统中存在ID为10的系列分配
- **WHEN** 更新该分配时提供以下字段:
  - `one_time_commission_amount`: 8000 (从5000更新到8000)
  - `one_time_commission_threshold`: 20000
- **THEN** 系统SHALL更新指定字段
- **AND** 其他字段保持不变
- **AND** 响应数据中 `updated_at` 字段更新为当前时间

#### Scenario: 更新系列分配的强制充值配置

- **GIVEN** 系统中存在ID为10的系列分配
- **WHEN** 更新该分配时提供以下字段:
  - `enable_force_recharge`: true
  - `force_recharge_amount`: 25000
  - `force_recharge_trigger_type`: 2 (累计充值)
- **THEN** 系统SHALL更新强制充值配置
- **AND** 响应数据中包含更新后的强制充值字段

#### Scenario: 查询系列分配列表并显示分配者信息

- **GIVEN** 系统中存在多个系列分配，部分由平台创建，部分由代理商创建
- **WHEN** 查询系列分配列表 (GET /api/admin/shop-series-allocations)
- **THEN** 系统SHALL返回所有分配记录
- **AND** 每条记录包含 `allocator_shop_id` 和 `allocator_shop_name`
- **AND** 平台创建的分配记录中 `allocator_shop_id` 为 0

#### Scenario: 按分配者店铺ID筛选系列分配

- **GIVEN** 系统中存在多个系列分配
- **WHEN** 使用查询参数 `allocator_shop_id=50`
- **THEN** 系统SHALL返回所有由店铺ID为50的代理商创建的分配记录

## REMOVED Requirements

### Requirement: Base Commission Configuration

旧版的 `base_commission` 配置模式已被移除，不再使用 `BaseCommissionConfig` 类型。

**Reason**: 新的佣金配置模型更加灵活和细粒度，将一次性佣金配置分散到独立字段中，便于查询和管理。

**Migration**: 现有使用 `base_commission` 字段的代码需要迁移到新的字段结构。如果有历史数据，需要后端提供数据迁移方案。

### Requirement: Tiered Commission Configuration

旧版的 `TierCommissionConfig` (周期性梯度返佣) 配置已被移除。

**Reason**: 系列分配层面不再支持复杂的梯度返佣配置，改为在系列级别统一配置一次性佣金梯度。

**Migration**: 梯度佣金配置现在在套餐系列级别 (`PackageSeries.one_time_commission_config.tiers`) 进行管理。

## ADDED Requirements

### Requirement: Allocator Information Tracking

系统SHALL记录系列分配的创建者（分配者）信息，包括分配者店铺ID和名称。

#### Scenario: 平台创建的分配标记为平台分配

- **GIVEN** 平台管理员登录系统
- **WHEN** 创建系列分配
- **THEN** 系统SHALL自动设置 `allocator_shop_id` 为 0
- **AND** `allocator_shop_name` 为 "平台" 或相应的平台标识

#### Scenario: 代理商创建的分配记录代理商信息

- **GIVEN** 代理商A登录系统，shop_id为50，shop_name为"代理商A"
- **WHEN** 创建系列分配给下级代理
- **THEN** 系统SHALL自动设置 `allocator_shop_id` 为 50
- **AND** `allocator_shop_name` 为 "代理商A"

### Requirement: Series Code in Allocation Response

系统SHALL在系列分配响应数据中包含套餐系列编码 (`series_code`)。

#### Scenario: 获取系列分配详情时包含系列编码

- **GIVEN** 系统中存在ID为10的系列分配，关联系列编码为"SERIES001"
- **WHEN** 请求获取该分配的详情 (GET /api/admin/shop-series-allocations/10)
- **THEN** 响应数据中SHALL包含 `series_code` 字段
- **AND** 其值为 "SERIES001"