fetch(modify):修改套餐接口

openspec/changes/update-package-management-api/proposal.md

@@ -0,0 +1,82 @@
+# Change: 更新套餐管理API以支持新的佣金配置模型
+
+## Why
+
+根据最新的API文档（`docs/修改原来的套餐管理.md`），后端API规范发生了重大变更，主要涉及:
+
+1. **套餐系列** - 新增一次性佣金配置支持（包括固定/梯度佣金、强制充值、时效类型等复杂配置）
+2. **系列分配** - 佣金配置模型完全重构，从简单的base_commission改为更细粒度的配置
+3. **单套餐分配** - 新增系列关联字段和分配者信息字段
+
+当前前端实现的类型定义（`src/types/api/packageManagement.ts`）和API服务与新规范不匹配，需要更新以支持新的数据结构。
+
+## What Changes
+
+### 1. 类型定义重构
+
+**修改**: `src/types/api/packageManagement.ts`
+
+**套餐系列相关类型**:
+- `PackageSeriesResponse` - 新增 `enable_one_time_commission` 和 `one_time_commission_config`
+- `CreatePackageSeriesRequest` - 新增一次性佣金配置字段
+- `UpdatePackageSeriesRequest` - 新增一次性佣金配置字段
+- 新增 `SeriesOneTimeCommissionConfig` - 一次性佣金配置（支持固定/梯度模式）
+- 新增 `OneTimeCommissionTier` - 梯度佣金档位配置
+
+**系列分配相关类型**:
+- **BREAKING**: `ShopSeriesAllocationResponse` - 完全重构字段结构
+  - 移除: `base_commission` (BaseCommissionConfig)
+  - 新增: `series_code`, `enable_force_recharge`, `enable_one_time_commission`, `force_recharge_amount`, `force_recharge_trigger_type`, `one_time_commission_amount`, `one_time_commission_threshold`, `one_time_commission_trigger`
+- **BREAKING**: `CreateShopSeriesAllocationRequest` - 重构请求字段
+- **BREAKING**: `UpdateShopSeriesAllocationRequest` - 重构请求字段
+- 移除不再使用的类型: `BaseCommissionConfig`, `TierEntry`, `TierCommissionConfig`, `OneTimeCommissionTierEntry`, `OneTimeCommissionConfig`(旧版)
+
+**单套餐分配相关类型**:
+- `ShopPackageAllocationResponse` - 字段调整
+  - 新增: `series_id`, `series_name`, `series_allocation_id`, `allocator_shop_id`, `allocator_shop_name`
+  - 移除: `allocation_id` (重命名为 `series_allocation_id`), `calculated_cost_price`
+- `ShopPackageAllocationQueryParams` - 新增 `series_allocation_id`, `allocator_shop_id` 筛选参数
+
+### 2. API服务层无需修改
+
+现有的API服务类（`PackageSeriesService`, `ShopSeriesAllocationService`, `ShopPackageAllocationService`）的方法签名保持不变，只是底层数据类型发生变化。
+
+### 3. 页面/组件适配（实施阶段处理）
+
+以下文件需要适配新的数据结构（本提案阶段不编写代码）:
+- 套餐系列管理页面 - 需支持一次性佣金配置表单
+- 系列分配页面 - 需重构佣金配置表单UI
+- 单套餐分配页面 - 需展示新增的关联字段
+
+## Impact
+
+### 受影响的规范
+
+- `package-series-management` - MODIFIED (新增一次性佣金配置能力)
+- `shop-series-allocation` - MODIFIED (佣金配置模型重构)
+- `shop-package-allocation` - MODIFIED (新增系列关联和分配者字段)
+
+### 受影响的代码
+
+- `src/types/api/packageManagement.ts` - **BREAKING CHANGE** 类型定义重构
+- 所有使用 `ShopSeriesAllocationResponse` 的页面/组件 - 需适配新字段结构
+- 所有使用 `PackageSeriesResponse` 的页面/组件 - 需处理新增的一次性佣金配置
+
+### 依赖关系
+
+- 后端API已按新规范实现（`docs/修改原来的套餐管理.md`）
+- 前端需要先完成类型定义更新，再更新UI组件
+
+### 风险评估
+
+- **高风险**: 这是一个BREAKING CHANGE，会影响所有使用系列分配的功能
+- **兼容性**: 需要确保后端API已更新，否则会导致运行时错误
+- **迁移成本**: 现有页面中的表单组件需要重写以支持新的数据结构
+- **测试需求**: 需要全面测试套餐系列、系列分配、单套餐分配的所有CRUD操作
+
+### 建议迁移策略
+
+1. 先更新类型定义，确保TypeScript编译通过
+2. 逐个页面/组件适配新数据结构
+3. 与后端联调确认新API规范工作正常
+4. 完成后删除旧的、不再使用的类型定义

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

@@ -0,0 +1,140 @@
+# Package Series Management Specification Delta
+
+## MODIFIED Requirements
+
+### Requirement: Package Series Data Model
+
+套餐系列的数据模型SHALL支持一次性佣金配置，包括固定佣金、梯度佣金、强制充值、时效类型等高级功能。
+
+**字段定义**:
+- `id` (number) - 系列ID
+- `series_code` (string) - 系列编码，唯一标识
+- `series_name` (string) - 系列名称
+- `description` (string, optional) - 系列描述
+- `enable_one_time_commission` (boolean) - 是否启用一次性佣金
+- `one_time_commission_config` (SeriesOneTimeCommissionConfig, optional) - 一次性佣金配置对象
+- `status` (number) - 状态 (1:启用, 2:禁用)
+- `created_at` (string) - 创建时间
+- `updated_at` (string) - 更新时间
+
+**一次性佣金配置结构** (`SeriesOneTimeCommissionConfig`):
+- `enable` (boolean) - 是否启用一次性佣金
+- `commission_type` (string) - 佣金类型: "fixed"(固定) | "tiered"(梯度)
+- `commission_amount` (number, optional) - 固定佣金金额（分），commission_type=fixed时使用
+- `threshold` (number) - 触发阈值（分）
+- `trigger_type` (string) - 触发类型: "first_recharge"(首次充值) | "accumulated_recharge"(累计充值)
+- `tiers` (OneTimeCommissionTier[], optional) - 梯度配置列表，commission_type=tiered时使用
+- `enable_force_recharge` (boolean) - 是否启用强充
+- `force_amount` (number, optional) - 强充金额（分）
+- `force_calc_type` (string, optional) - 强充计算类型: "fixed"(固定) | "dynamic"(动态)
+- `validity_type` (string) - 时效类型: "permanent"(永久) | "fixed_date"(固定日期) | "relative"(相对时长)
+- `validity_value` (string, optional) - 时效值（日期字符串或月数）
+
+**梯度档位结构** (`OneTimeCommissionTier`):
+- `threshold` (number) - 达标阈值
+- `dimension` (string) - 统计维度: "sales_count"(销量) | "sales_amount"(销售额)
+- `amount` (number) - 佣金金额（分）
+- `stat_scope` (string, optional) - 统计范围: "self"(仅自己) | "self_and_sub"(自己+下级)
+
+#### Scenario: 创建套餐系列并启用固定一次性佣金
+
+- **GIVEN** 管理员登录系统
+- **WHEN** 创建套餐系列时提供以下配置:
+  - `series_code`: "SERIES001"
+  - `series_name`: "标准流量系列"
+  - `enable_one_time_commission`: true
+  - `one_time_commission_config`:
+    - `enable`: true
+    - `commission_type`: "fixed"
+    - `commission_amount`: 5000 (50元)
+    - `threshold`: 10000 (100元)
+    - `trigger_type`: "first_recharge"
+    - `validity_type`: "permanent"
+- **THEN** 系统SHALL创建套餐系列，并保存一次性佣金配置
+
+#### Scenario: 创建套餐系列并启用梯度一次性佣金
+
+- **GIVEN** 管理员登录系统
+- **WHEN** 创建套餐系列时提供以下配置:
+  - `series_code`: "SERIES002"
+  - `series_name`: "高级流量系列"
+  - `enable_one_time_commission`: true
+  - `one_time_commission_config`:
+    - `enable`: true
+    - `commission_type`: "tiered"
+    - `threshold`: 5000
+    - `trigger_type`: "accumulated_recharge"
+    - `tiers`: [
+        { threshold: 10, dimension: "sales_count", amount: 3000 },
+        { threshold: 50, dimension: "sales_count", amount: 8000 }
+      ]
+    - `validity_type`: "relative"
+    - `validity_value`: "12" (12个月)
+- **THEN** 系统SHALL创建套餐系列，并保存梯度佣金配置
+
+#### Scenario: 查询启用一次性佣金的套餐系列
+
+- **GIVEN** 系统中存在多个套餐系列，部分启用了一次性佣金
+- **WHEN** 使用查询参数 `enable_one_time_commission=true` 查询列表
+- **THEN** 系统SHALL返回所有启用一次性佣金的套餐系列
+
+#### Scenario: 更新套餐系列的一次性佣金配置
+
+- **GIVEN** 系统中存在ID为1的套餐系列
+- **WHEN** 更新该系列时提供新的一次性佣金配置:
+  - `one_time_commission_config.commission_amount`: 8000 (从5000更新到8000)
+  - `one_time_commission_config.enable_force_recharge`: true
+  - `one_time_commission_config.force_amount`: 20000
+  - `one_time_commission_config.force_calc_type`: "fixed"
+- **THEN** 系统SHALL更新套餐系列的一次性佣金配置，并返回更新后的数据
+
+#### Scenario: 获取套餐系列详情时包含完整的一次性佣金配置
+
+- **GIVEN** 系统中存在ID为1的套餐系列，已配置一次性佣金
+- **WHEN** 请求获取该系列的详情 (GET /api/admin/package-series/1)
+- **THEN** 系统SHALL返回包含完整 `one_time_commission_config` 对象的响应数据
+
+## ADDED Requirements
+
+### Requirement: One-Time Commission Query Filter
+
+系统SHALL支持按一次性佣金启用状态筛选套餐系列列表。
+
+#### Scenario: 按一次性佣金启用状态筛选
+
+- **GIVEN** 系统中存在多个套餐系列
+- **WHEN** 使用查询参数 `enable_one_time_commission=true`
+- **THEN** 系统SHALL只返回 `enable_one_time_commission` 为 true 的套餐系列
+- **AND** 分页信息正确反映筛选后的结果数量
+
+### Requirement: One-Time Commission Configuration Validation
+
+系统SHALL验证一次性佣金配置的完整性和逻辑一致性。
+
+#### Scenario: 固定佣金模式的验证
+
+- **GIVEN** 管理员创建套餐系列
+- **WHEN** `commission_type` 为 "fixed"
+- **THEN** 系统SHALL要求 `commission_amount` 字段必填
+- **AND** `tiers` 字段不应被使用
+
+#### Scenario: 梯度佣金模式的验证
+
+- **GIVEN** 管理员创建套餐系列
+- **WHEN** `commission_type` 为 "tiered"
+- **THEN** 系统SHALL要求 `tiers` 数组不为空
+- **AND** 每个梯度档位的 `threshold`, `dimension`, `amount` 字段必填
+
+#### Scenario: 强制充值配置的验证
+
+- **GIVEN** 管理员创建套餐系列
+- **WHEN** `enable_force_recharge` 为 true
+- **THEN** 系统SHALL要求 `force_amount` 和 `force_calc_type` 字段必填
+
+#### Scenario: 时效配置的验证
+
+- **GIVEN** 管理员创建套餐系列
+- **WHEN** `validity_type` 为 "fixed_date"
+- **THEN** 系统SHALL要求 `validity_value` 字段必填，且格式为有效的日期字符串
+- **WHEN** `validity_type` 为 "relative"
+- **THEN** 系统SHALL要求 `validity_value` 字段必填，且为表示月数的数字字符串

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返回所有关联该系列分配的单套餐分配记录

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"

openspec/changes/update-package-management-api/tasks.md

@@ -0,0 +1,62 @@
+# Implementation Tasks
+
+## 1. 类型定义更新
+
+- [ ] 1.1 更新 `PackageSeriesResponse` - 新增一次性佣金字段
+- [ ] 1.2 新增 `SeriesOneTimeCommissionConfig` 类型定义
+- [ ] 1.3 新增 `OneTimeCommissionTier` 类型定义
+- [ ] 1.4 更新 `CreatePackageSeriesRequest` - 新增一次性佣金配置参数
+- [ ] 1.5 更新 `UpdatePackageSeriesRequest` - 新增一次性佣金配置参数
+- [ ] 1.6 更新 `PackageSeriesQueryParams` - 新增 `enable_one_time_commission` 筛选参数
+- [ ] 1.7 重构 `ShopSeriesAllocationResponse` - 替换为新的字段结构
+- [ ] 1.8 重构 `CreateShopSeriesAllocationRequest` - 更新为新的请求结构
+- [ ] 1.9 重构 `UpdateShopSeriesAllocationRequest` - 更新为新的请求结构
+- [ ] 1.10 更新 `ShopPackageAllocationResponse` - 新增系列关联和分配者字段
+- [ ] 1.11 更新 `ShopPackageAllocationQueryParams` - 新增筛选参数
+- [ ] 1.12 移除废弃的类型定义 (`BaseCommissionConfig`, 旧版 `OneTimeCommissionConfig` 等)
+
+## 2. 套餐系列管理页面适配
+
+- [ ] 2.1 更新套餐系列列表 - 显示一次性佣金启用状态
+- [ ] 2.2 更新套餐系列表单 - 新增一次性佣金配置区块
+- [ ] 2.3 实现一次性佣金配置表单组件 (固定模式)
+- [ ] 2.4 实现一次性佣金配置表单组件 (梯度模式)
+- [ ] 2.5 实现强制充值配置表单组件
+- [ ] 2.6 实现时效配置表单组件 (永久/固定日期/相对时长)
+- [ ] 2.7 添加一次性佣金配置的表单验证逻辑
+- [ ] 2.8 更新套餐系列详情展示 - 显示完整的一次性佣金配置
+
+## 3. 系列分配管理页面适配
+
+- [ ] 3.1 更新系列分配列表 - 适配新的响应字段结构
+- [ ] 3.2 移除基础返佣配置表单（旧版）
+- [ ] 3.3 实现新的系列分配表单 - 强制充值配置
+- [ ] 3.4 实现新的系列分配表单 - 一次性佣金配置
+- [ ] 3.5 更新系列分配详情展示 - 显示所有新字段
+- [ ] 3.6 更新系列分配编辑表单 - 支持修改所有可选字段
+- [ ] 3.7 添加表单验证逻辑 - 确保必填字段和逻辑一致性
+
+## 4. 单套餐分配页面适配
+
+- [ ] 4.1 更新单套餐分配列表 - 显示系列信息和分配者信息
+- [ ] 4.2 更新列表筛选条件 - 新增系列分配ID和分配者店铺ID筛选
+- [ ] 4.3 更新单套餐分配详情展示 - 显示所有新字段
+- [ ] 4.4 移除列表中的"计算成本价"字段显示（已废弃）
+
+## 5. 测试与验证
+
+- [ ] 5.1 测试套餐系列的创建 - 包含一次性佣金配置（固定模式）
+- [ ] 5.2 测试套餐系列的创建 - 包含一次性佣金配置（梯度模式）
+- [ ] 5.3 测试套餐系列的编辑 - 修改一次性佣金配置
+- [ ] 5.4 测试系列分配的创建 - 使用新的字段结构
+- [ ] 5.5 测试系列分配的编辑 - 修改强制充值和一次性佣金参数
+- [ ] 5.6 测试单套餐分配 - 验证系列关联字段正确显示
+- [ ] 5.7 测试单套餐分配筛选 - 验证新增筛选参数工作正常
+- [ ] 5.8 回归测试 - 确保所有现有功能仍然正常工作
+
+## 6. 文档与清理
+
+- [ ] 6.1 更新类型定义文件的注释 - 标注新增/修改的字段
+- [ ] 6.2 删除废弃的类型定义和相关代码
+- [ ] 6.3 更新相关组件的注释文档
+- [ ] 6.4 记录API变更影响和迁移说明（如需要）