huang
f40abaf93c
三个 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>
146 lines
7.2 KiB
Markdown
146 lines
7.2 KiB
Markdown
# Capability: 强充预检
|
||
|
||
## Purpose
|
||
|
||
本 capability 定义强充预检接口，在充值或购买套餐前返回强充要求、允许的充值金额等信息，帮助前端正确引导用户完成支付。
|
||
|
||
## 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 提供钱包充值预检接口，返回强充要求、允许的充值金额等信息。强充判断 MUST 按代理层级规则执行：优先使用平台强充，平台未设时使用销售代理自设强充。
|
||
|
||
#### Scenario: 无强充要求
|
||
- **WHEN** 客户查询卡钱包充值预检，PackageSeries.enable_force_recharge=false，销售代理 ShopSeriesAllocation.enable_force_recharge=false
|
||
- **THEN** 系统返回 need_force_recharge=false
|
||
|
||
#### Scenario: 首次充值强充（平台层）
|
||
- **WHEN** 客户查询卡钱包充值预检，PackageSeries 配置为首次充值触发，阈值 10000 分，未发放佣金
|
||
- **THEN** 系统返回 need_force_recharge=true，force_recharge_amount=10000，trigger_type="single_recharge"
|
||
|
||
#### 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** 客户查询卡钱包充值预检，卡的一次性佣金已发放过
|
||
- **THEN** 系统返回 need_force_recharge = false（不再强充）
|
||
|
||
#### Scenario: 未启用一次性佣金
|
||
- **WHEN** 客户查询卡钱包充值预检，卡关联系列未启用一次性佣金
|
||
- **THEN** 系统返回 need_force_recharge = false
|
||
|
||
---
|
||
|
||
### Requirement: 套餐购买预检
|
||
|
||
系统 SHALL 提供套餐购买预检接口，计算实际支付金额、钱包到账金额等信息。强充判断 MUST 按代理层级规则执行。
|
||
|
||
#### Scenario: 无强充要求正常购买
|
||
- **WHEN** 客户购买 90 元套餐，平台和销售代理均未设强充
|
||
- **THEN** 系统返回 total_package_amount=9000，need_force_recharge=false，actual_payment=9000，wallet_credit=0
|
||
|
||
#### 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 元
|
||
- **THEN** 系统返回 total_package_amount = 15000，need_force_recharge = true，force_recharge_amount = 10000，actual_payment = 15000，wallet_credit = 0，message = "套餐总价150元，无需额外充值"
|
||
|
||
#### Scenario: 首次充值强充，套餐价等于阈值
|
||
- **WHEN** 客户购买 100 元套餐，首次充值阈值 100 元
|
||
- **THEN** 系统返回 total_package_amount = 10000，need_force_recharge = true，force_recharge_amount = 10000，actual_payment = 10000，wallet_credit = 0
|
||
|
||
#### Scenario: 累计充值启用强充，套餐价低于强充金额
|
||
- **WHEN** 客户购买 50 元套餐，累计充值启用强充，强充金额 100 元
|
||
- **THEN** 系统返回 actual_payment = 10000，wallet_credit = 5000，message = "需充值100元，购买套餐后余额50元"
|
||
|
||
#### Scenario: 累计充值启用强充，套餐价高于强充金额
|
||
- **WHEN** 客户购买 150 元套餐，累计充值启用强充，强充金额 100 元
|
||
- **THEN** 系统返回 actual_payment = 15000，wallet_credit = 0，message = "套餐总价150元，无需额外充值"
|
||
|
||
#### Scenario: 购买多个套餐
|
||
- **WHEN** 客户购买 3 个套餐，总价 120 元，首次充值阈值 100 元
|
||
- **THEN** 系统返回 total_package_amount = 12000，actual_payment = 12000，wallet_credit = 0
|
||
|
||
---
|
||
|
||
### Requirement: 预检接口响应格式
|
||
|
||
预检接口响应 SHALL 包含完整的充值/购买指引信息。
|
||
|
||
#### Scenario: 充值预检响应字段
|
||
- **WHEN** 调用钱包充值预检接口
|
||
- **THEN** 响应包含：need_force_recharge, force_recharge_amount, trigger_type, min_amount, max_amount, current_accumulated, threshold, message
|
||
|
||
#### Scenario: 购买预检响应字段
|
||
- **WHEN** 调用套餐购买预检接口
|
||
- **THEN** 响应包含：total_package_amount, need_force_recharge, force_recharge_amount, actual_payment, wallet_credit, message
|
||
|
||
---
|
||
|
||
### Requirement: 预检接口性能
|
||
|
||
预检接口响应时间 MUST 小于 100ms。
|
||
|
||
#### Scenario: 快速响应
|
||
- **WHEN** 调用预检接口
|
||
- **THEN** 系统在 100ms 内返回结果
|
||
|
||
#### Scenario: 缓存系列分配配置
|
||
- **WHEN** 频繁查询同一卡的预检信息
|
||
- **THEN** 系统可以缓存系列分配配置，减少数据库查询
|
||
|
||
---
|
||
|
||
### Requirement: 预检接口错误处理
|
||
|
||
预检接口 SHALL 正确处理异常情况。
|
||
|
||
#### Scenario: 卡不存在
|
||
- **WHEN** 查询不存在的卡的充值预检
|
||
- **THEN** 系统返回错误 "卡不存在"
|
||
|
||
#### Scenario: 卡未关联系列
|
||
- **WHEN** 查询未关联套餐系列的卡的充值预检
|
||
- **THEN** 系统返回 need_force_recharge = false（无系列分配，无强充要求）
|
||
|
||
#### Scenario: 设备不存在
|
||
- **WHEN** 查询不存在的设备的充值预检
|
||
- **THEN** 系统返回错误 "设备不存在"
|
||
|
||
#### Scenario: 套餐不存在
|
||
- **WHEN** 套餐购买预检时，套餐 ID 不存在
|
||
- **THEN** 系统返回错误 "套餐不存在"
|