fetch(modify):修改套餐接口

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

@@ -0,0 +1,162 @@
+# 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"