## Why 代理套餐授权体系存在四类问题: 1. **接口割裂**:给代理授权套餐需要两步独立 API(先创建系列分配,再多次创建套餐分配),但这本质是一个业务动作 2. **死字段**:`ShopSeriesAllocation` 有 3 个字段(`enable_one_time_commission`、`one_time_commission_trigger`、`one_time_commission_threshold`)从未被计算引擎读取,与 PackageSeries 配置语义完全重复 3. **强充逻辑未接入**:代理自设强充的 3 个字段虽然存储,但 `checkForceRechargeRequirement` 从不读取,导致代理无论如何设置都不生效 4. **梯度模式实现错误**:梯度佣金计算引擎用 PackageSeries 全局阶梯表(所有代理同一套金额),但业务模型要求每个代理有自己的专属阶梯金额(可压缩、不超父级同档位上限);且数据库中没有存储每代理专属阶梯金额的字段 ## What Changes - **新增** 统一"系列授权"接口(`/shop-series-grants`),一次操作原子性完成系列分配 + 套餐列表分配,底层仍为两张表 - **删除** 旧的 `/shop-series-allocations` 和 `/shop-package-allocations` 接口及其全部 Handler、routes、DTO、Service(开发阶段,干净重构) - **修复** 强充层级:订单服务接入销售代理的 `ShopSeriesAllocation` 强充配置,实现"平台未设强充 → 代理自设生效" - **修复** 梯度模式数据模型:`ShopSeriesAllocation` 新增 `commission_tiers_json` JSONB 字段,存储每代理专属阶梯金额 - **修复** 梯度模式计算引擎:读取各代理自己的阶梯金额,而不是 PackageSeries 全局阶梯 - **新增** 金额上限校验:固定模式——子级 `one_time_commission_amount` 不得超过父级;梯度模式——子级每档位金额不得超过父级同档位金额 - **清理** 删除 3 个死字段(`enable_one_time_commission`、`one_time_commission_trigger`、`one_time_commission_threshold`) ## Capabilities ### New Capabilities - `agent-series-grant`:统一代理系列授权 CRUD,单次操作包含套餐系列 + 套餐列表 + 成本价 + 一次性佣金配置(固定模式:单个上限金额;梯度模式:每档位上限金额列表)+ 强充配置(平台未设时) ### Modified Capabilities - `force-recharge-check`:强充检查增加层级判断——平台系列已设强充时沿用,未设时改为读取销售代理的 `ShopSeriesAllocation` 强充配置 ### Removed Capabilities - `shop-series-allocation`:旧系列分配接口全部删除(Handler、routes、DTO、Service) - `shop-package-allocation`:旧套餐分配接口全部删除(Handler、routes、DTO、Service) ## Impact **受影响的数据库表** - `tb_shop_series_allocation`: - 删除 3 列(enable_one_time_commission、one_time_commission_trigger、one_time_commission_threshold) - 新增 1 列(commission_tiers_json JSONB,梯度模式专用) **受影响的 API** - 新增:`POST/GET/PUT/DELETE /api/admin/shop-series-grants` 系列 - 新增:`PUT /api/admin/shop-series-grants/:id/packages` - 删除:`/api/admin/shop-series-allocations` 全部接口 - 删除:`/api/admin/shop-package-allocations` 全部接口 - 变更:强充预检接口(`/purchase-check`、`/wallet-recharge-check`)返回结果受新逻辑影响 **受影响的服务** - `internal/service/order/service.go`:`checkForceRechargeRequirement` 增加代理分配查询 - `internal/service/commission_calculation/service.go`:梯度模式改为读取各代理专属阶梯金额 - 删除:`internal/service/shop_series_allocation/` - 删除:`internal/service/shop_package_allocation/` - 新增:`internal/service/shop_series_grant/`