docs: 新增实名时间与历史、二次实名及按资产号批量延期提案

This commit is contained in:
邹进
2026-11-08 18:44:44 +09:00
parent 0138a3fb9c
commit 76d0f38b9e
12 changed files with 552 additions and 0 deletions

View File

@@ -0,0 +1,70 @@
## ADDED Requirements
### Requirement: 二次实名批次导入
有 `iot_card:realname_reset` 权限的运营 SHALL 可导入二次实名名单(xlsx / csv,一列:ICCID、虚拟号或 IMEI,单批最多 1000 行),填写原因后提交形成一个二次实名批次。系统逐行解析:ICCID 直接定位卡;虚拟号或 IMEI 定位设备,取设备当前全部绑定卡。以下行 MUST 跳过并记录原因,不影响其他行:资产不存在、卡未实名、卡所属运营商不返回实名时间(不支持二次实名)、该卡从未读到过上游实名时间、卡已处于等待二次实名、卡当前实名时间为空(无法确定新旧基准)。批次记录导入文件、总条数、成功数、跳过数及每行结果、操作人与时间。
#### Scenario: 导入设备
- **WHEN** 导入一台绑定 3 张移动已实名卡的设备 IMEI
- **THEN** 3 张卡都进入等待二次实名
#### Scenario: 导入不支持的运营商
- **WHEN** 名单中有一张电信已实名卡
- **THEN** 该行跳过,原因"该运营商不返回实名时间,不支持二次实名",其他行照常处理
### Requirement: 二次实名清除
批次中每张合格卡 SHALL 在独立事务内执行清除:将卡 `real_name_status` 置为未实名;当前实名记录的二次实名状态置为"等待二次实名",记录清除时间、所属批次与清除前实名时间(基准);当前实名时间置空;写一条"二次实名清除"历史;按现有实名状态变化流程发出实名变化事件。已激活的套餐 MUST NOT 回退;`first_realname_at` MUST NOT 修改。
#### Scenario: 清除后资产显示未实名
- **WHEN** 卡(实名时间 07-16 19:43:39)被二次实名清除
- **THEN** 卡显示未实名、实名时间为空,历史有一条清除记录(原 07-16 19:43:39 → 空),已生效套餐不受影响
### Requirement: 二次实名新旧判定
卡处于等待二次实名时,读到"已实名"观测 SHALL 按上游实名时间判定:上游实名时间晚于基准时间 → 二次实名完成,卡置为已实名,当前实名时间取上游时间(来源 upstream),清除等待状态,写"二次实名完成"历史;上游实名时间不晚于基准时间、或未返回上游实名时间 → MUST NOT 改实名状态、MUST NOT 写当前实名时间与历史,仅更新最近检查时间。卡处于等待二次实名时读到未实名观测按现有逻辑处理(保持未实名)。
#### Scenario: 读到旧实名
- **WHEN** 基准 07-16 19:43:39,清除后轮询返回 `realStatus=true, archiveTime=2026-07-16 19:43:39`
- **THEN** 卡仍为未实名,不写历史
#### Scenario: 用户完成二次实名
- **WHEN** 基准 07-16 19:43:39,用户 11-09 10:00 重新实名,轮询返回 `archiveTime=2026-11-09 10:00:00`
- **THEN** 卡变为已实名,当前实名时间 11-09 10:00:00,写一条二次实名完成历史,触发现有实名后续流程(沉默期判定、激活等)
### Requirement: 二次实名撤销
有 `iot_card:realname_reset` 权限的运营 SHALL 可对仍处于等待二次实名的卡撤销(单张或整批):卡恢复为已实名、当前实名时间恢复为基准时间,清除等待状态,写"二次实名撤销"历史。已完成二次实名的卡不能撤销。
#### Scenario: 导错撤销
- **WHEN** 运营撤销一张等待二次实名的卡
- **THEN** 卡恢复已实名、实名时间恢复为清除前时间
### Requirement: C 端无感办理
C 端 MUST 按普通未实名卡展示等待二次实名的卡(显示"未实名"、正常发放实名链接),任何接口与页面 MUST NOT 出现"二次实名"相关字样或标记。
#### Scenario: 用户进入 C 端
- **WHEN** 等待二次实名卡的用户进入 H5 首页
- **THEN** 显示未实名,可点击去实名,与普通未实名卡一致
### Requirement: 等待二次实名卡的停复机口径
等待二次实名的卡 SHALL 与普通未实名卡同等参与现有实名停复机判定:所属运营商账户开启实名管控且套餐有效时按现有逻辑停机。系统 MUST NOT 为二次实名新增停复机路径;`enable_polling = false` 的卡 MUST NOT 被任何入口停机或复机。测试环境网关只读开关保持开启。
#### Scenario: 实名管控账户下的二次实名卡
- **WHEN** 卡所属账户开启实名管控、套餐有效,卡被二次实名清除
- **THEN** 按现有未实名停机逻辑处理,与普通未实名卡一致
#### Scenario: 关闭轮询的卡
- **WHEN** 被清除的卡 `enable_polling = false`
- **THEN** 不发起任何停机或复机

View File

@@ -0,0 +1,91 @@
## ADDED Requirements
### Requirement: 上游实名时间解析
系统 SHALL 解析网关实名查询响应中的 `archiveTime`(格式 `YYYY-MM-DD HH:mm:ss`,按北京时间解释)作为上游实名时间。字段缺失、为 null、为空串或无法解析时 MUST 视为"上游未返回实名时间",不得报错、不得影响实名状态判定。`realStatus = false` 时即使返回了 `archiveTime` 也 MUST 忽略。
#### Scenario: 移动返回实名时间
- **WHEN** 网关返回 `{"archiveTime":"2026-07-16 19:43:39","iccid":"89860885192590574640","realStatus":true}`
- **THEN** 本次观测的上游实名时间为 2026-07-16 19:43:39(+08:00)
#### Scenario: 联通、电信不返回实名时间
- **WHEN** 网关返回 `{"iccid":"8986112520903884400","realStatus":true}` 或带 `extend` 但无 `archiveTime`
- **THEN** 本次观测没有上游实名时间,实名状态照常按 `realStatus` 判定
#### Scenario: 未实名时的空实名时间
- **WHEN** 网关返回 `{"archiveTime":null,"realStatus":false}`
- **THEN** 不产生上游实名时间,按未实名观测处理
### Requirement: 卡当前实名记录
系统 SHALL 为每张卡维护至多一条当前实名记录,包含:当前实名时间、时间来源(`upstream` 上游返回 / `first_observed` 首次读到已实名 / `migrated` 迁移沿用库里时间)、上游最近一次返回的实名时间、首次读到已实名的时间、二次实名状态及基准(见 `card-realname-reset`)。卡的实名状态 `real_name_status` MUST 继续保存在卡表,当前实名记录不替代它。
#### Scenario: 查询卡当前实名时间
- **WHEN** 管理端查询一张已实名卡
- **THEN** 返回当前实名时间与来源;无当前实名记录或时间为空时实名时间返回空
### Requirement: 当前实名时间的确定与更新
卡读到"已实名"观测(轮询、手动刷新、运营商回调、业务观测)并被采纳为已实名时,系统 SHALL 按以下顺序确定实名时间:
1. 观测带上游实名时间 → 取上游实名时间,来源 `upstream`;
2. 否则当前记录已有实名时间 → 保持不变;
3. 否则 → 取本次观测时间(首次读到已实名),来源 `first_observed`。
只有确定出的实名时间与当前实名时间不同时,系统 MUST 在同一事务内更新当前实名记录并追加一条实名时间历史;相同则 MUST NOT 写当前记录的实名时间、MUST NOT 写历史。上游最近返回时间可随观测更新但不产生历史。卡被判定为未实名(含连续逆转、人工改未实名)时当前实名时间保持不变,不写历史;之后再次被判定为已实名时按上述顺序重新确定,变化才写历史。
#### Scenario: 每次轮询读到相同实名时间
- **WHEN** 移动卡当前实名时间为 2026-07-16 19:43:39(来源 upstream),本次轮询上游仍返回 2026-07-16 19:43:39
- **THEN** 不更新当前实名时间,不写历史
#### Scenario: 上游更正迁移时间
- **WHEN** 移动卡当前实名时间为迁移沿用的 2026-07-16 20:03:25(来源 migrated),本次轮询上游返回 2026-07-16 19:43:39
- **THEN** 当前实名时间更新为 19:43:39、来源改为 upstream,并写一条历史(原 20:03:25 → 新 19:43:39)
#### Scenario: 不返回时间的运营商首次实名
- **WHEN** 电信卡此前未实名、无当前实名时间,本次轮询于 11-08 10:00 首次读到已实名
- **THEN** 当前实名时间为 11-08 10:00、来源 first_observed,写一条历史;之后每次读到已实名都不再写
#### Scenario: 逆转为未实名后再次实名
- **WHEN** 电信卡当前实名时间为 09-01 10:00,被连续逆转判定为未实名,之后 11-08 12:00 再次读到已实名
- **THEN** 逆转时不写历史;再次实名时当前实名时间仍为 09-01 10:00(规则 2),不写历史
### Requirement: 实名时间历史
系统 SHALL 在当前实名时间发生变化时追加一条实名时间历史,记录:卡、ICCID、原实名时间、新实名时间、新时间来源、变化类型(首次实名 / 上游更正 / 二次实名清除 / 二次实名完成 / 二次实名撤销 / 迁移补录)、观测来源(轮询 / 手动刷新 / 回调 / 业务观测 / 人工 / 批次)、关联二次实名批次、操作人(人工时)、发现时间。历史 MUST 只追加不修改。
#### Scenario: 历史条数不随轮询增长
- **WHEN** 一张卡实名后被轮询 1000 次,上游实名时间始终相同
- **THEN** 该卡只有首次实名(或迁移补录)对应的历史,不随轮询增加
### Requirement: 实名时间老数据迁移
上线时系统 SHALL 对 `real_name_status = 已实名` 的卡补录当前实名记录:库里 `first_realname_at` 不为空的,当前实名时间取该值、来源 `migrated`,并写一条"迁移补录"历史;`first_realname_at` 为空的,当前实名时间留空、不写历史,等之后读到已实名时按"当前实名时间的确定与更新"规则填写。迁移 MUST 可重复执行且不产生重复记录。
#### Scenario: 已实名有时间的老卡
- **WHEN** 卡已实名、`first_realname_at = 2026-07-16 20:03:25`
- **THEN** 当前实名时间为 20:03:25、来源 migrated,有一条迁移补录历史
#### Scenario: 已实名无时间的老卡
- **WHEN** 卡已实名、`first_realname_at` 为空,之后移动轮询返回上游时间 2026-08-01 09:00:00
- **THEN** 迁移时不写;轮询后当前实名时间为 2026-08-01 09:00:00、来源 upstream,写一条历史
### Requirement: 资产实名时间展示
管理端资产详情、卡列表与导出中的"实名时间" SHALL 取当前实名时间;设备的实名时间沿用现有聚合口径(已绑定且已实名卡中 `max(卡实名时间, 绑定时间)` 的最小值),其中卡实名时间改取当前实名时间。管理端 SHALL 提供按卡查询实名时间历史的接口(分页、按时间倒序),资产详情展示当前实名时间、来源与历史。
#### Scenario: 资产详情查看实名记录
- **WHEN** 运营打开卡 89860885192590574640 的资产详情
- **THEN** 看到当前实名时间、来源(上游返回 / 首次读到 / 迁移沿用),以及实名时间变化历史

View File

@@ -0,0 +1,15 @@
## ADDED Requirements
### Requirement: 沉默期判定使用当前实名时间
沉默期"实名与过期判定"中卡的实名时间 SHALL 取卡当前实名记录的当前实名时间(见 `card-realname-time`),不再取 `first_realname_at`;设备聚合口径不变,其中卡实名时间同样取当前实名时间。卡已实名但当前实名时间为空时 MUST 按原规则视为期内已实名,并以判定时间作为首次读到时间写入当前实名记录(来源 `first_observed`,写历史)。本规则只作用于上线后发生的判定;已经是 `ended` 或 `expired` 的套餐 MUST NOT 因实名时间来源变化而重算。
#### Scenario: 上游实名时间早于发现时间
- **WHEN** 套餐截止日 11-08 23:59:59,移动卡上游实名时间 11-08 23:50,系统 11-09 00:10 才读到
- **THEN** 判定为期内已实名,沉默期结束
#### Scenario: 已判定的套餐不重算
- **WHEN** 某套餐上线前已按旧口径标记为 `expired`,上线后其卡的当前实名时间被上游更正为截止日之前
- **THEN** 该套餐保持 `expired`,不自动改判