文档

openspec/specs/force-recharge-check/spec.md

@@ -0,0 +1,115 @@
+# Capability: 强充预检
+
+## Purpose
+
+本 capability 定义强充预检接口，在充值或购买套餐前返回强充要求、允许的充值金额等信息，帮助前端正确引导用户完成支付。
+
+## Requirements
+
+### Requirement: 钱包充值预检
+
+系统 SHALL 提供钱包充值预检接口，返回强充要求、允许的充值金额等信息。
+
+#### Scenario: 无强充要求
+- **WHEN** 客户查询卡钱包充值预检，卡配置为累计充值触发且未启用强充
+- **THEN** 系统返回 need_force_recharge = false，min_amount = 100（1元），max_amount = null
+
+#### Scenario: 首次充值强充
+- **WHEN** 客户查询卡钱包充值预检，卡配置为首次充值触发，阈值 10000 分（100元），未发放佣金
+- **THEN** 系统返回 need_force_recharge = true，force_recharge_amount = 10000，trigger_type = "single_recharge"，message = "首次充值需充值100元"
+
+#### Scenario: 累计充值启用强充
+- **WHEN** 客户查询卡钱包充值预检，卡配置为累计充值触发，启用强充，强充金额 10000 分（100元）
+- **THEN** 系统返回 need_force_recharge = true，force_recharge_amount = 10000，trigger_type = "accumulated_recharge"，message = "每次充值需充值100元"
+
+#### Scenario: 一次性佣金已发放
+- **WHEN** 客户查询卡钱包充值预检，卡的一次性佣金已发放过
+- **THEN** 系统返回 need_force_recharge = false（不再强充）
+
+#### Scenario: 未启用一次性佣金
+- **WHEN** 客户查询卡钱包充值预检，卡关联系列未启用一次性佣金
+- **THEN** 系统返回 need_force_recharge = false
+
+---
+
+### Requirement: 套餐购买预检
+
+系统 SHALL 提供套餐购买预检接口，计算实际支付金额、钱包到账金额等信息。
+
+#### Scenario: 无强充要求正常购买
+- **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** 客户购买 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** 系统返回错误 "套餐不存在"