## 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** 看到当前实名时间、来源(上游返回 / 首次读到 / 迁移沿用),以及实名时间变化历史