huang
4aab0bcbf2
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 4m39s
76 lines
5.3 KiB
Markdown
76 lines
5.3 KiB
Markdown
# Capability: 客户端钱包与充值
|
||
|
||
## ADDED Requirements
|
||
|
||
### Requirement: C1 钱包详情接口
|
||
|
||
系统 SHALL 提供 `GET /api/c/v1/wallet/detail?identifier=xxx`，并且 MUST 要求个人客户认证。接口 MUST 先完成资产解析与归属校验；钱包不存在时 MUST 自动创建空钱包。响应体 SHALL 包含 `wallet_id`、`resource_type`、`resource_id`、`balance`、`frozen_balance`、`updated_at`。错误码/消息 MUST 至少包含：`INVALID_PARAM/参数错误`、`FORBIDDEN/无权限操作该资产或资源不存在`。
|
||
|
||
#### Scenario: 首次访问自动建钱包
|
||
- **WHEN** 客户查询资产钱包详情且钱包记录不存在
|
||
- **THEN** 系统自动创建钱包并返回余额 0
|
||
|
||
---
|
||
|
||
### Requirement: C2 钱包流水列表接口
|
||
|
||
系统 SHALL 提供 `GET /api/c/v1/wallet/transactions?identifier=xxx`，并且 MUST 要求个人客户认证。接口 MUST 通过归属校验解析出唯一 `wallet_id` 后查询流水，实现天然隔离。请求参数 SHALL 支持 `transaction_type`、`start_time`、`end_time`、`page`、`page_size`。响应体 SHALL 包含 `list[]`、`total`、`page`、`page_size`，每条记录至少含 `transaction_id`、`type`、`amount`、`balance_after`、`created_at`、`remark`。错误码/消息 MUST 至少包含：`INVALID_PARAM/参数错误`、`FORBIDDEN/无权限操作该资产或资源不存在`。
|
||
|
||
#### Scenario: wallet_id 隔离生效
|
||
- **WHEN** 客户查询某资产流水
|
||
- **THEN** 系统仅返回该资产钱包对应流水，不返回其他钱包数据
|
||
|
||
---
|
||
|
||
### Requirement: C3 充值预检接口
|
||
|
||
系统 SHALL 提供 `GET /api/c/v1/wallet/recharge-check?identifier=xxx`，并且 MUST 要求个人客户认证。接口 MUST 在资产解析与归属校验后，**新增实名策略检查**：
|
||
|
||
- 获取生效实名策略（`GetEffectiveRealnamePolicy`）
|
||
- 生效策略为 `before_order` 且 `real_name_status=0`：MUST 返回 `CodeNeedRealname`
|
||
- 生效策略为 `after_order` 或 `none`：跳过实名检查，继续执行强充规则计算
|
||
|
||
通过实名检查后，接口 MUST 复用 `recharge.Service.GetRechargeCheck()` 计算强充规则。响应体 SHALL 包含 `need_force_recharge`、`force_recharge_amount`、`trigger_type`、`min_amount`、`max_amount`、`message`。错误码/消息 MUST 至少包含：`INVALID_PARAM/参数错误`、`FORBIDDEN/无权限操作该资产或资源不存在`、`NEED_REALNAME/该套餐需实名认证后充值`。
|
||
|
||
#### Scenario: 返回强充预检结果
|
||
- **WHEN** 资产命中强充规则
|
||
- **THEN** 系统返回 `need_force_recharge=true` 与对应强充金额和触发类型
|
||
|
||
#### Scenario: before_order 未实名时充值预检被拦截
|
||
- **WHEN** 生效策略为 before_order 且 real_name_status=0
|
||
- **THEN** 系统返回 CodeNeedRealname，不返回强充预检结果
|
||
|
||
---
|
||
|
||
### Requirement: C4 创建充值订单接口
|
||
|
||
系统 SHALL 提供 `POST /api/c/v1/wallet/recharge`，并且 MUST 要求个人客户认证。请求体 MUST 包含：`identifier`、`amount`（100~10000000 分）、`payment_method=wechat`、`app_type`。
|
||
|
||
接口 MUST 在归属校验后、OpenID 查询前，**新增实名策略检查**：
|
||
- 生效策略为 `before_order` 且 `real_name_status=0`：MUST 返回 `CodeNeedRealname`，充值订单不创建
|
||
- 生效策略为 `after_order` 或 `none`：继续执行后续流程
|
||
|
||
接口 MUST 禁止客户端传入 OpenID，并由后端按 `customer_id + app_type` 查询 OpenID。订单创建时 MUST 写入：`operator_type=personal_customer` 与资产当前 `generation` 快照。响应体 SHALL 返回 `recharge` 与 `pay_config`，其中 `recharge` 至少含 `recharge_id`、`recharge_no`、`amount`、`status`，`pay_config` 为微信 JSAPI 拉起参数。错误码/消息 MUST 至少包含：`INVALID_PARAM/参数错误`、`OPENID_NOT_FOUND/未找到微信授权信息，请先完成授权`、`FORBIDDEN/无权限操作该资产或资源不存在`、`PAYMENT_NOT_SUPPORTED/仅支持微信支付`、`NEED_REALNAME/该套餐需实名认证后充值`。
|
||
|
||
#### Scenario: 后端查 OpenID 并返回支付参数
|
||
- **WHEN** 客户传入合法参数且后端成功查询到 OpenID
|
||
- **THEN** 系统创建充值单并返回 `recharge + pay_config`
|
||
|
||
#### Scenario: before_order 未实名时充值订单创建被拦截
|
||
- **WHEN** 生效策略为 before_order 且 real_name_status=0，用户调用充值下单接口
|
||
- **THEN** 系统返回 CodeNeedRealname（1187），充值单不创建
|
||
|
||
#### Scenario: after_order 模式充值放行
|
||
- **WHEN** 生效策略为 after_order 且 real_name_status=0，用户调用充值下单接口
|
||
- **THEN** 系统正常创建充值单，不检查实名状态
|
||
|
||
---
|
||
|
||
### Requirement: C5 充值订单列表接口
|
||
|
||
系统 SHALL 提供 `GET /api/c/v1/wallet/recharges?identifier=xxx`，并且 MUST 要求个人客户认证。接口 MUST 在归属校验后按资产当前 generation 过滤充值记录。请求参数 SHALL 支持 `status`、`page`、`page_size`。响应体 SHALL 返回 `list[]`、`total`、`page`、`page_size`，每项至少含 `recharge_id`、`recharge_no`、`amount`、`status`、`payment_method`、`created_at`。错误码/消息 MUST 至少包含：`INVALID_PARAM/参数错误`、`FORBIDDEN/无权限操作该资产或资源不存在`。
|
||
|
||
#### Scenario: generation 过滤充值历史
|
||
- **WHEN** 资产存在多代充值记录
|
||
- **THEN** 系统仅返回当前 generation 对应的充值记录
|