huang
4aab0bcbf2
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 4m39s
48 lines
2.9 KiB
Markdown
48 lines
2.9 KiB
Markdown
# Capability: 客户端实名跳转
|
||
|
||
## ADDED Requirements
|
||
|
||
### Requirement: E1 获取实名跳转链接接口
|
||
|
||
系统 SHALL 提供 `GET /api/c/v1/realname/link?identifier=xxx&iccid=xxx`，并且 MUST 要求个人客户认证。该接口 MUST 支持两类入口：购买拦截入口与设备卡列表主动入口。目标卡定位 MUST 支持三种路径：
|
||
|
||
1. 标识符直达卡：直接使用该卡
|
||
2. 标识符为设备且传 `iccid`：定位对应设备下卡
|
||
3. 标识符为设备且未传 `iccid`：定位设备当前活跃卡
|
||
|
||
接口在确定目标卡后，MUST 获取生效实名策略（`GetEffectiveRealnamePolicy`），按以下顺序执行前置检查：
|
||
|
||
**实名策略检查**（新增，在实名状态检查之前执行）：
|
||
- 生效策略为 `after_order`：检查该资产当前 generation 内是否存在有效充值（`status=2`）或已支付订单（`payment_status=2`）
|
||
- 无记录 → MUST 返回 `CodeRealnameNotAvailable`，消息"请先完成充值或购买套餐后再进行实名认证"
|
||
- 有记录 → 继续执行后续检查
|
||
- 生效策略为 `none` 或 `before_order`：不执行此检查，继续执行后续检查
|
||
|
||
**原有检查保留**：
|
||
- 当 `real_name_status=1` 时 MUST 返回"该卡已完成实名"错误
|
||
- 运营商实名模式 MUST 支持：`none`（不支持在线实名）、`template`（模板替换）、`gateway`（调用网关）
|
||
|
||
响应体 SHALL 至少包含 `realname_mode`（运营商链接类型）、`realname_url`、`card_info{iccid,msisdn,virtual_no}`、`expire_at`（可空）。
|
||
|
||
错误码/消息 MUST 至少包含（新增 `REALNAME_NOT_AVAILABLE`）：`INVALID_PARAM/参数错误`、`FORBIDDEN/无权限操作该资产或资源不存在`、`REALNAME_ALREADY_DONE/该卡已完成实名`、`REALNAME_NOT_SUPPORTED/该运营商暂不支持在线实名`、`GATEWAY_ERROR/获取实名链接失败`、`REALNAME_NOT_AVAILABLE/请先完成充值或购买套餐后再进行实名认证`。
|
||
|
||
#### Scenario: 设备未传 iccid 自动选活跃卡
|
||
- **WHEN** 客户传入设备标识符且不传 `iccid`
|
||
- **THEN** 系统自动选择设备活跃卡并返回实名跳转链接
|
||
|
||
#### Scenario: after_order 模式有充值记录时放行
|
||
- **WHEN** 生效策略为 after_order 且当前 generation 内存在 status=2 的充值记录
|
||
- **THEN** 系统正常返回实名链接
|
||
|
||
#### Scenario: after_order 模式无记录时拦截
|
||
- **WHEN** 生效策略为 after_order 且当前 generation 内无任何有效充值或已支付订单
|
||
- **THEN** 系统返回错误码 CodeRealnameNotAvailable，消息"请先完成充值或购买套餐后再进行实名认证"
|
||
|
||
#### Scenario: before_order 模式正常返回链接
|
||
- **WHEN** 生效策略为 before_order 且该卡尚未实名
|
||
- **THEN** 系统正常返回实名链接（引导用户先实名）
|
||
|
||
#### Scenario: none 模式正常返回链接
|
||
- **WHEN** 生效策略为 none
|
||
- **THEN** 系统正常返回实名链接（无策略限制，允许用户自愿实名）
|