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