docs: 同步 OpenSpec 主规范,新增系列授权 capability 并更新强充预检规范

三个 capability 同步:
- agent-series-grant(新建):定义系列授权 CRUD,覆盖固定/梯度佣金模式和强充层级场景
- force-recharge-check(更新):新增「代理层强充层级判断」Requirement,更新钱包充值和套餐购买预检场景以反映平台/代理层级规则
- shop-series-allocation(更新):在 REMOVED 区域追加三个已废弃接口的文档说明(/shop-series-allocations、/shop-package-allocations、enable_one_time_commission 等字段)

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
This commit is contained in:
2026-03-04 11:37:46 +08:00
parent e0cb4498e6
commit f40abaf93c
3 changed files with 270 additions and 15 deletions

View File

@@ -6,21 +6,47 @@
## Requirements
### Requirement: 代理层强充层级判断
系统 SHALL 在强充预检时按层级判断生效的强充配置:平台在 PackageSeries 中设置的强充具有最高优先级;平台未设强充时,读取客户所属销售代理(`order.SellerShopID`)对应的 ShopSeriesAllocation 强充配置。
#### Scenario: 平台已设强充,代理自设被忽略
- **WHEN** PackageSeries.enable_force_recharge=true(平台层),客户在代理A 的渠道下购买,代理A 的 ShopSeriesAllocation.enable_force_recharge=false
- **THEN** 系统使用平台强充规则,need_force_recharge=true,force_recharge_amount=平台设定值
#### Scenario: 平台未设强充,代理自设生效
- **WHEN** PackageSeries.enable_force_recharge=false,客户在代理A 的渠道下购买,代理A 的 ShopSeriesAllocation.enable_force_recharge=true,force_recharge_amount=10000
- **THEN** 系统使用代理A 的强充配置,need_force_recharge=true,force_recharge_amount=10000
#### Scenario: 平台未设强充,代理也未设强充
- **WHEN** PackageSeries.enable_force_recharge=false,代理A 的 ShopSeriesAllocation.enable_force_recharge=false
- **THEN** 系统返回 need_force_recharge=false
#### Scenario: 平台未设强充,查询不到销售代理分配
- **WHEN** PackageSeries.enable_force_recharge=false,系统查询不到 SellerShop 对应的 ShopSeriesAllocation
- **THEN** 系统返回 need_force_recharge=false(降级处理,不影响购买流程)
---
### Requirement: 钱包充值预检
系统 SHALL 提供钱包充值预检接口,返回强充要求、允许的充值金额等信息。
系统 SHALL 提供钱包充值预检接口,返回强充要求、允许的充值金额等信息。强充判断 MUST 按代理层级规则执行:优先使用平台强充,平台未设时使用销售代理自设强充。
#### Scenario: 无强充要求
- **WHEN** 客户查询卡钱包充值预检,卡配置为累计充值触发且未启用强充
- **THEN** 系统返回 need_force_recharge = false,min_amount = 100(1元),max_amount = null
- **WHEN** 客户查询卡钱包充值预检,PackageSeries.enable_force_recharge=false,销售代理 ShopSeriesAllocation.enable_force_recharge=false
- **THEN** 系统返回 need_force_recharge=false
#### Scenario: 首次充值强充
- **WHEN** 客户查询卡钱包充值预检,卡配置为首次充值触发,阈值 10000 分(100元),未发放佣金
- **THEN** 系统返回 need_force_recharge = true,force_recharge_amount = 10000,trigger_type = "single_recharge",message = "首次充值需充值100元"
#### Scenario: 首次充值强充(平台层)
- **WHEN** 客户查询卡钱包充值预检,PackageSeries 配置为首次充值触发,阈值 10000 分,未发放佣金
- **THEN** 系统返回 need_force_recharge=true,force_recharge_amount=10000,trigger_type="single_recharge"
#### Scenario: 累计充值启用强充
- **WHEN** 客户查询卡钱包充值预检,卡配置为累计充值触发,启用强充,强充金额 10000 分(100元)
- **THEN** 系统返回 need_force_recharge = true,force_recharge_amount = 10000,trigger_type = "accumulated_recharge",message = "每次充值需充值100元"
#### Scenario: 累计充值启用强充(平台层)
- **WHEN** 客户查询卡钱包充值预检,PackageSeries.enable_force_recharge=true,force_amount=10000
- **THEN** 系统返回 need_force_recharge=true,force_recharge_amount=10000,trigger_type="accumulated_recharge"
#### Scenario: 代理自设累计充值强充(平台未设)
- **WHEN** PackageSeries.enable_force_recharge=false,销售代理的 ShopSeriesAllocation.enable_force_recharge=true,force_recharge_amount=8000
- **THEN** 系统返回 need_force_recharge=true,force_recharge_amount=8000
#### Scenario: 一次性佣金已发放
- **WHEN** 客户查询卡钱包充值预检,卡的一次性佣金已发放过
@@ -34,15 +60,19 @@
### Requirement: 套餐购买预检
系统 SHALL 提供套餐购买预检接口,计算实际支付金额、钱包到账金额等信息。
系统 SHALL 提供套餐购买预检接口,计算实际支付金额、钱包到账金额等信息。强充判断 MUST 按代理层级规则执行。
#### Scenario: 无强充要求正常购买
- **WHEN** 客户购买 90 元套餐,无强充要求
- **THEN** 系统返回 total_package_amount = 9000,need_force_recharge = false,actual_payment = 9000,wallet_credit = 0
- **WHEN** 客户购买 90 元套餐,平台和销售代理均未设强充
- **THEN** 系统返回 total_package_amount=9000,need_force_recharge=false,actual_payment=9000,wallet_credit=0
#### Scenario: 首次充值强充,套餐价低于阈值
- **WHEN** 客户购买 90 元套餐,首次充值阈值 100 元
- **THEN** 系统返回 total_package_amount = 9000,need_force_recharge = true,force_recharge_amount = 10000,actual_payment = 10000,wallet_credit = 1000,message = "需充值100元,购买套餐后余额10元"
#### Scenario: 代理自设强充,套餐价低于强充金额
- **WHEN** 客户购买 50 元套餐,平台未设强充,销售代理设置 force_recharge_amount=10000
- **THEN** 系统返回 actual_payment=10000,wallet_credit=5000
#### Scenario: 首次充值强充(平台层),套餐价低于阈值
- **WHEN** 客户购买 90 元套餐,首次充值阈值 100 元(平台层)
- **THEN** 系统返回 total_package_amount=9000,need_force_recharge=true,force_recharge_amount=10000,actual_payment=10000,wallet_credit=1000
#### Scenario: 首次充值强充,套餐价高于阈值
- **WHEN** 客户购买 150 元套餐,首次充值阈值 100 元