docs: 归档 refactor-agent-series-grant 变更文档

将已完成的变更（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>

openspec/changes/archive/2026-03-04-refactor-agent-series-grant/proposal.md

@@ -0,0 +1,54 @@
+## 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/`