feat: 实现资产实名认证策略功能 (asset-realname-policy)
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 6m44s

- 新增 realname_policy 字段到 tb_iot_card、tb_device、tb_iot_card_import_task、tb_device_import_task 四张表
- 策略枚举:none(无需实名)、before_order(先实名后充值/购买)、after_order(先充值/购买后实名)
- C端充值拦截:before_order 策略下未实名用户禁止充值
- C端订单拦截:before_order 策略下未实名用户禁止购买套餐
- C端实名链接拦截:after_order 策略下无充值/订单用户禁止实名认证
- Admin API:PATCH /api/admin/assets/:identifier/realname-mode
- 新增错误码 CodeRealnameNotAvailable=1189
This commit is contained in:
2026-04-17 17:03:41 +08:00
parent e0a37f4a11
commit 505b30aa8f
12 changed files with 623 additions and 0 deletions

View File

@@ -0,0 +1,45 @@
## MODIFIED 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** 系统正常返回实名链接(无策略限制,允许用户自愿实名)