# 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. 完成后删除旧的、不再使用的类型定义