Files
junhong_cmp_fiber/openspec/changes/add-realname-time-history/specs/card-realname-time/spec.md

6.1 KiB
Raw Blame History

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