4.0 KiB
4.0 KiB
Change: 更新套餐管理API以支持新的佣金配置模型
Why
根据最新的API文档（docs/修改原来的套餐管理.md），后端API规范发生了重大变更，主要涉及:
- 套餐系列 - 新增一次性佣金配置支持（包括固定/梯度佣金、强制充值、时效类型等复杂配置）
- 系列分配 - 佣金配置模型完全重构，从简单的base_commission改为更细粒度的配置
- 单套餐分配 - 新增系列关联字段和分配者信息字段
当前前端实现的类型定义（src/types/api/packageManagement.ts）和API服务与新规范不匹配，需要更新以支持新的数据结构。
What Changes
1. 类型定义重构
修改: src/types/api/packageManagement.ts
套餐系列相关类型:
PackageSeriesResponse- 新增enable_one_time_commission和one_time_commission_configCreatePackageSeriesRequest- 新增一次性佣金配置字段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操作
建议迁移策略
- 先更新类型定义，确保TypeScript编译通过
- 逐个页面/组件适配新数据结构
- 与后端联调确认新API规范工作正常
- 完成后删除旧的、不再使用的类型定义