fetch(modify):修改套餐接口

openspec/changes/update-package-management-api/specs/shop-package-allocation/spec.md

@@ -0,0 +1,158 @@
+# 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返回所有关联该系列分配的单套餐分配记录