Files
junhong_cmp_fiber/openspec/changes/add-realname-time-history/design.md

6.8 KiB
Raw Blame History

Context

  • 实名状态唯一写入口是 internal/application/cardobservation/apply.go 的 ApplyCardObservation(轮询、手动刷新、回调、业务观测、人工纠偏都汇到这里),领域判定在 internal/domain/cardobservation/realname.go。
  • 网关 RealnameStatusResp 只有 iccid、realStatus。测试环境 worker 日志抽样(11-08,约 4900 条实名响应):移动 15 返回 archiveTime(已实名必带,未实名为 null);联通 31/22/50/2 返回 extend 文本无时间;电信 10/4 只有 iccid、realStatus。
  • first_realname_at 由首次判为已实名时写入观测时间,被沉默期判定、资产展示、导出、首次实名激活使用。
  • 实名状态 real_name_status 被停复机、C 端、沉默期、导出等 40 余处读取。
  • 约束:不新增停复机路径;enable_polling=false 永不停复机;不查询 tb_audit_event* / tb_integration_log;只部署测试环境。

Goals / Non-Goals

Goals:

  • 记录准确的当前实名时间与来源,只在变化时写历史。
  • 支持移动卡二次实名,C 端无感。
  • 沉默期改用当前实名时间。

Non-Goals:

  • 不迁移 real_name_status,不删除 first_realname_at。
  • 不为联通、电信做二次实名(无实名时间无法区分新旧)。
  • 不重算已判定的沉默期套餐。
  • 不改实名逆转阈值、停复机规则。

Decisions

1. 三张新表,不给 tb_iot_card 加列

  • tb_iot_card_realname:card_id 唯一;realname_at、realname_at_source、upstream_realname_at(最近一次上游返回)、first_observed_at;reset_status(none / pending)、reset_at、reset_baseline_at、reset_batch_id;时间戳。
  • tb_iot_card_realname_history:只追加;card_id、iccid、before_at、after_at、after_source、change_type、observation_source、reset_batch_id、operator_id、observed_at、created_at;索引 (card_id, id desc)。
  • tb_iot_card_realname_reset_batch:batch_no、import_file_key、reason、total/succeeded/skipped/reverted、items(jsonb 行结果:行号、输入值、卡 ID、结果、原因)、operator_id。

理由:卡表是轮询高频更新的大表,二次实名状态与时间独立成表可避免加宽卡表、减少行锁竞争,并让历史与当前值语义清晰。备选"卡表加列"改动小,但二次实名状态字段多,否决。每卡状态在 tb_iot_card_realname 上,批次表不再拆明细表。

2. 观测携带可选上游实名时间

RealnameStatusResp 增加 ArchiveTime *string(json:"archiveTime"),解析为 *time.Time(Asia/Shanghai),解析失败视为空并打 warn 日志。domain.RealnameObservation 增加 UpstreamRealnameAt *time.Time,所有调用网关实名查询的入口(polling_realname_handler.go、series_runner.go、iot_card/service.go 手动刷新)透传;回调、人工入口为空。

3. 实名时间在同一事务内决定

在 ApplyCardObservation 锁卡事务内,读取 / 创建 tb_iot_card_realname 行(SELECT ... FOR UPDATE),由领域函数 DecideRealnameTime(snapshot, observation, decision) 输出:是否更新 realname_at、新值与来源、是否写历史、变化类型、是否拦截本次已实名(二次实名)。纯函数便于表驱动测试。

二次实名拦截发生在 ApplyRealname 之前:卡处于 pending 且观测为已实名时,若 upstream > baseline 则照常走已实名判定(StatusChanged=true,FirstVerified=false,因 first_realname_at 非空),否则把观测降级为"不改状态",只更新 last_real_name_check_at。

4. 迁移补录用 SQL 一次性插入

迁移文件中 INSERT INTO tb_iot_card_realname (...) SELECT ... FROM tb_iot_card WHERE real_name_status=1 AND deleted_at IS NULL ON CONFLICT (card_id) DO NOTHING,同时按 first_realname_at IS NOT NULL 插入 migrated 历史(用 NOT EXISTS 防重复)。数据量大时分批(按 id 区间)执行,避免长事务。

5. 沉默期与展示切换读取源

packagesilence/resolve.go 的 realnameFacts 改为 LEFT JOIN tb_iot_card_realname 取 realname_at;"已实名但时间为空"的补写改写 tb_iot_card_realname(来源 first_observed,写历史)而不是 first_realname_at。资产详情、卡列表、导出的"实名时间"同样改取 realname_at。只对上线后的判定生效,不做回算任务。

6. 二次实名执行

导入接口同步解析与校验(≤1000 行),逐卡独立事务执行清除;清除复用 ApplyCardObservation 的人工纠偏通道(Source=manual_override,置未实名)以保持实名变化事件、审计与停复机评估一致,并在同事务写 tb_iot_card_realname 的 pending 字段与历史。运营商是否支持按卡所属运营商 carrier_type = CMCC 判定(常量白名单,后续确认其他运营商返回时间后再放开);同时要求当前实名时间非空作为基准。

7. 权限与接口

  • GET /api/admin/iot-cards/:id/realname-history(复用资产详情查看权限)。
  • POST /api/admin/realname-reset/batches(导入)、GET /api/admin/realname-reset/batches、GET /api/admin/realname-reset/batches/:id、POST /api/admin/realname-reset/batches/:id/revert(撤销整批或指定卡);新增权限码 iot_card:realname_reset。

Risks / Trade-offs

  • [仅抽样一个移动账户返回 archiveTime] → 白名单按运营商类型 CMCC;导入时额外要求卡当前实名时间来源为 upstream 或有上游最近返回时间,否则跳过并提示,避免对不返回时间的账户误清。
  • [清除后实名管控账户会停机] → 用户已确认按普通未实名处理;测试环境网关只读,不会真实下发。
  • [上游 archiveTime 时区或格式变化] → 解析失败视为空,不影响状态,日志告警。
  • [迁移补录数据量大] → 分批插入、可重复执行。
  • [当前实名时间改为上游时间后,个别沉默期新判定结果与旧口径不同] → 用户确认采用新口径,已判定的不重算。

Migration Plan

  1. 部署迁移:建 3 张表 → 分批补录当前实名记录与迁移历史。
  2. 部署 api / worker:开始解析 archiveTime 并写当前记录与历史;沉默期与展示切换读取源。
  3. 管理端前端上线实名记录与二次实名页面,分配权限 iot_card:realname_reset。
  4. 回滚:回滚 api / worker 镜像即可恢复旧读取(first_realname_at 一直保留且仍按旧规则写入);新表可保留。

Open Questions

  • 其他移动账户是否都返回 archiveTime、联通 / 电信能否提供实名时间,需与网关确认;确认后扩充二次实名支持白名单。
  • 上游对已实名过的卡是否仍能正常生成实名链接,需上线后用一张测试卡验证。