huang
e0cb4498e6
将已完成的变更（proposal、design、tasks、delta specs）归档至 openspec/changes/archive/2026-03-04-refactor-agent-series-grant/。变更内容：合并系列分配和套餐分配为系列授权（Grant）、新增梯度佣金模式、新增代理层强充层级规则。50/50 任务全部完成。 Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
3.7 KiB
3.7 KiB
Why
代理套餐授权体系存在四类问题：
- 接口割裂：给代理授权套餐需要两步独立 API（先创建系列分配，再多次创建套餐分配），但这本质是一个业务动作
- 死字段：
ShopSeriesAllocation有 3 个字段（enable_one_time_commission、one_time_commission_trigger、one_time_commission_threshold）从未被计算引擎读取，与 PackageSeries 配置语义完全重复 - 强充逻辑未接入：代理自设强充的 3 个字段虽然存储，但
checkForceRechargeRequirement从不读取，导致代理无论如何设置都不生效 - 梯度模式实现错误：梯度佣金计算引擎用 PackageSeries 全局阶梯表（所有代理同一套金额），但业务模型要求每个代理有自己的专属阶梯金额（可压缩、不超父级同档位上限）；且数据库中没有存储每代理专属阶梯金额的字段
What Changes
- 新增 统一"系列授权"接口（
/shop-series-grants），一次操作原子性完成系列分配 + 套餐列表分配，底层仍为两张表 - 删除 旧的
/shop-series-allocations和/shop-package-allocations接口及其全部 Handler、routes、DTO、Service（开发阶段，干净重构） - 修复 强充层级：订单服务接入销售代理的
ShopSeriesAllocation强充配置，实现"平台未设强充 → 代理自设生效" - 修复 梯度模式数据模型：
ShopSeriesAllocation新增commission_tiers_jsonJSONB 字段，存储每代理专属阶梯金额 - 修复 梯度模式计算引擎：读取各代理自己的阶梯金额，而不是 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/