junhong_cmp_fiber/openspec/changes/archive/2026-03-05-fix-tiered-commission-tier-fields/specs/agent-series-grant/spec.md

MODIFIED Requirements

Requirement: 查询系列授权详情

系统 SHALL 提供 GET /shop-series-grants/:id 接口，返回包含套餐列表的聚合视图。梯度模式下，commission_tiers 中每个档位 MUST 包含 dimension（统计维度）和 stat_scope（统计范围）字段，这两个字段从 PackageSeries 全局配置按 threshold 合并，对代理只读。

变更说明：GrantCommissionTierItem 新增 dimension 和 stat_scope 字段，buildGrantResponse() 在合并 operator 的同时同步合并这两个字段。

Scenario: 固定模式详情

• WHEN 查询固定模式系列授权详情
• THEN 响应包含 commission_type="fixed"，one_time_commission_amount=有效值，commission_tiers=[]

Scenario: 梯度模式详情

• WHEN 查询梯度模式系列授权详情
• THEN 响应包含 commission_type="tiered"，one_time_commission_amount=0
• AND commission_tiers 中每个档位包含 operator、dimension、stat_scope、threshold、amount 五个字段
• AND operator、dimension、stat_scope 的值来自 PackageSeries 全局配置（对应 threshold 的档位），代理的 amount 来自 ShopSeriesAllocation.commission_tiers_json

Scenario: 梯度模式 dimension 为销售量

• WHEN 查询梯度模式授权详情，PackageSeries 阶梯 dimension = "sales_count"
• THEN 响应中对应档位 dimension = "sales_count"，前端展示"销售量"条件

Scenario: 梯度模式 dimension 为销售额

• WHEN 查询梯度模式授权详情，PackageSeries 阶梯 dimension = "sales_amount"
• THEN 响应中对应档位 dimension = "sales_amount"，前端展示"销售额"条件

Scenario: 梯度模式 stat_scope 区分

• WHEN 查询梯度模式授权详情
• THEN 响应中 stat_scope 正确反映 PackageSeries 配置的统计范围（"self" 或 "self_and_sub"）

Scenario: 查询不存在的授权

• WHEN 查询不存在的授权 ID
• THEN 系统返回错误"授权记录不存在"

---

Requirement: 创建系列授权（梯度模式）

系统 SHALL 支持梯度模式的系列授权创建。梯度模式下，commission_tiers MUST 为必填，且必须包含与 PackageSeries 完全相同数量和阈值的阶梯（不多不少）。若某档位不希望给下级佣金，应将该档位的 amount 设为 0，不可省略该档位。创建成功后的响应中，commission_tiers 每个档位 MUST 包含 operator、dimension、stat_scope 字段（从全局配置合并）。

变更说明：Create 响应复用同一 buildGrantResponse()，故创建响应也自动包含 dimension/stat_scope。

Scenario: 代理成功创建梯度模式授权

• WHEN 代理A 的专属阶梯为 [{operator:">=", threshold:100, amount:80}, {operator:">=", threshold:150, amount:120}]，A 为代理B 创建授权，传入 commission_tiers=[{threshold:100, amount:50}, {threshold:150, amount:100}]
• THEN 系统创建授权，commission_tiers_json 存储 [{threshold:100, amount:50}, {threshold:150, amount:100}]
• AND 响应中 commission_tiers=[{operator:">=", dimension:"sales_count", stat_scope:"self", threshold:100, amount:50}, ...]

Scenario: 平台成功创建梯度模式授权

• WHEN 平台为顶级代理A 创建授权，PackageSeries 阶梯含 operator/dimension/stat_scope
• THEN 系统创建授权，响应中 commission_tiers 包含 PackageSeries 全局 operator、dimension、stat_scope

Scenario: 梯度模式某档位金额超过父级

• WHEN 代理A 的阶梯第一档 amount=80，A 为 B 创建授权时传入第一档 amount=90
• THEN 系统返回错误"某档位佣金金额超过上级天花板"

Scenario: 梯度模式传入了不存在的阈值

• WHEN PackageSeries 只有 threshold=100 和 150 两档，请求中传入 threshold=200
• THEN 系统返回错误"梯度阶梯 threshold 与系列配置不匹配"

Scenario: 梯度模式 commission_tiers 为必填

• WHEN 请求中不包含 commission_tiers 或为空数组
• THEN 系统返回参数错误"梯度模式必须填写阶梯配置"

---

Requirement: 系列授权列表强充状态正确反映

系列授权列表 (GET /shop-series-grants) MUST 在每个列表项中返回 force_recharge_locked（是否被套餐系列锁定）和 force_recharge_amount（强充金额）。force_recharge_enabled MUST 反映有效状态：当锁定时为 true（无论分配记录自身如何）；未锁定时取分配记录的实际设置。

变更说明：ShopSeriesGrantListItem 新增 force_recharge_locked bool、force_recharge_amount int64。列表构建时从套餐系列配置计算有效强充状态。

Scenario: 套餐系列锁定强充

• WHEN 套餐系列配置 enable_force_recharge=true 或 trigger_type=first_recharge，查询列表
• THEN 列表项中 force_recharge_locked=true，force_recharge_enabled=true，force_recharge_amount=系列配置的 force_amount

Scenario: 代理自身开启强充（未锁定）

• WHEN 套餐系列未锁定强充，分配记录中 enable_force_recharge=true，查询列表
• THEN 列表项中 force_recharge_locked=false，force_recharge_enabled=true，force_recharge_amount=分配记录的实际金额

Scenario: 代理未开启强充（未锁定）

• WHEN 套餐系列未锁定强充，分配记录中 enable_force_recharge=false，查询列表
• THEN 列表项中 force_recharge_locked=false，force_recharge_enabled=false，force_recharge_amount=0

---

Requirement: 查询系列授权详情强充有效状态

系列授权详情 (GET /shop-series-grants/:id) 中，force_recharge_enabled MUST 反映有效状态：当锁定时为 true；force_recharge_amount 锁定时应返回系列配置的 force_amount。

变更说明：buildGrantResponse() 修正强充字段有效状态计算逻辑。

Scenario: 锁定强充时详情响应

• WHEN 套餐系列锁定强充，查询对应分配记录详情
• THEN force_recharge_locked=true，force_recharge_enabled=true，force_recharge_amount=系列配置的 force_amount