# Shop Package Allocation Specification Delta

## MODIFIED Requirements

### Requirement: Shop Package Allocation Data Model

单套餐分配的数据模型SHALL新增系列关联字段和分配者信息字段，以支持更完整的分配关系追溯。

**字段定义**:
- `id` (number) - 分配ID
- `package_id` (number) - 套餐ID
- `package_code` (string) - 套餐编码
- `package_name` (string) - 套餐名称
- `series_id` (number) - 套餐系列ID
- `series_name` (string) - 套餐系列名称
- `shop_id` (number) - 被分配的店铺ID
- `shop_name` (string) - 被分配的店铺名称
- `allocator_shop_id` (number) - 分配者店铺ID，0表示平台分配
- `allocator_shop_name` (string) - 分配者店铺名称
- `series_allocation_id` (number, nullable) - 关联的系列分配ID（可选）
- `cost_price` (number) - 该代理的成本价（分）
- `status` (number) - 状态 (1:启用, 2:禁用)
- `created_at` (string) - 创建时间
- `updated_at` (string) - 更新时间

**查询参数** (`ShopPackageAllocationQueryParams`):
- `page` (number, optional) - 页码
- `page_size` (number, optional) - 每页数量
- `shop_id` (number, optional) - 被分配的店铺ID
- `package_id` (number, optional) - 套餐ID
- `series_allocation_id` (number, optional) - 系列分配ID
- `allocator_shop_id` (number, optional) - 分配者店铺ID
- `status` (number, optional) - 状态

#### Scenario: 创建单套餐分配时包含系列信息

- **GIVEN** 平台管理员登录系统
- **AND** 系统中存在ID为10的套餐，该套餐属于系列ID为2，系列名称为"标准流量系列"
- **AND** 系统中存在ID为100的店铺
- **WHEN** 创建单套餐分配:
  - `package_id`: 10
  - `shop_id`: 100
  - `cost_price`: 15000
- **THEN** 系统SHALL创建单套餐分配记录
- **AND** 响应数据中自动填充 `series_id` 为 2
- **AND** 响应数据中自动填充 `series_name` 为 "标准流量系列"
- **AND** 响应数据中 `allocator_shop_id` 为 0（平台分配）

#### Scenario: 创建单套餐分配并关联系列分配

- **GIVEN** 系统中存在ID为20的系列分配，关联系列ID为2，店铺ID为100
- **AND** 系列2下存在套餐ID为10
- **WHEN** 为店铺100创建套餐10的分配
- **THEN** 系统MAY自动关联系列分配，设置 `series_allocation_id` 为 20

#### Scenario: 查询单套餐分配列表并显示完整关联信息

- **GIVEN** 系统中存在多个单套餐分配
- **WHEN** 查询单套餐分配列表 (GET /api/admin/shop-package-allocations)
- **THEN** 系统SHALL返回所有分配记录
- **AND** 每条记录包含 `series_id`, `series_name`, `allocator_shop_id`, `allocator_shop_name`
- **AND** 如果存在关联的系列分配，`series_allocation_id` 不为空

#### Scenario: 按系列分配ID筛选单套餐分配

- **GIVEN** 系统中存在多个单套餐分配，部分关联了系列分配ID为20的系列分配
- **WHEN** 使用查询参数 `series_allocation_id=20`
- **THEN** 系统SHALL返回所有 `series_allocation_id` 为 20 的单套餐分配记录

#### Scenario: 按分配者店铺ID筛选单套餐分配

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

#### Scenario: 获取单套餐分配详情时显示完整信息

- **GIVEN** 系统中存在ID为100的单套餐分配
- **WHEN** 请求获取该分配的详情 (GET /api/admin/shop-package-allocations/100)
- **THEN** 响应数据SHALL包含所有字段，包括:
  - `series_id`, `series_name` - 套餐所属系列信息
  - `allocator_shop_id`, `allocator_shop_name` - 分配者信息
  - `series_allocation_id` - 关联的系列分配ID（如果存在）

## RENAMED Requirements

- FROM: `allocation_id`
- TO: `series_allocation_id`

**说明**: 将字段名从 `allocation_id` 重命名为 `series_allocation_id`，使其语义更加明确，表示关联的系列分配ID。

## REMOVED Requirements

### Requirement: Calculated Cost Price Field

旧版的 `calculated_cost_price` 字段已被移除。

**Reason**: 该字段仅用于参考，增加了数据模型的复杂性，且前端很少使用。成本价信息应直接使用 `cost_price` 字段。

**Migration**: 移除所有使用 `calculated_cost_price` 字段的代码。如果需要查看原始成本价信息，可以通过关联的系列分配或套餐系列获取。

## ADDED Requirements

### Requirement: Series Information in Package Allocation

系统SHALL在单套餐分配响应数据中包含套餐所属系列的ID和名称。

#### Scenario: 创建分配时自动关联系列信息

- **GIVEN** 系统中存在套餐，且该套餐属于某个系列
- **WHEN** 创建单套餐分配
- **THEN** 系统SHALL自动从套餐数据中获取 `series_id` 和 `series_name`
- **AND** 填充到分配响应数据中

### Requirement: Allocator Information Tracking in Package Allocation

系统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: Query by Allocator Shop ID

系统SHALL支持按分配者店铺ID筛选单套餐分配列表。

#### Scenario: 查看平台创建的所有分配

- **GIVEN** 系统中存在多个单套餐分配
- **WHEN** 使用查询参数 `allocator_shop_id=0`
- **THEN** 系统SHALL返回所有由平台创建的单套餐分配记录

#### Scenario: 查看特定代理商创建的所有分配

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

### Requirement: Query by Series Allocation ID

系统SHALL支持按系列分配ID筛选单套餐分配列表，以便查找由特定系列分配派生的所有单套餐分配。

#### Scenario: 查找系列分配的所有派生单套餐分配

- **GIVEN** 系统中存在系列分配ID为20的系列分配
- **AND** 该系列分配下有多个单套餐分配
- **WHEN** 使用查询参数 `series_allocation_id=20`
- **THEN** 系统SHALL返回所有关联该系列分配的单套餐分配记录