6.2 KiB
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。 - 不为上游不返回
archiveTime的卡做二次实名(无实名时间无法区分新旧)。 - 不重算已判定的沉默期套餐。
- 不改实名逆转阈值、停复机规则。
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 字段与历史。是否支持只看该卡 upstream_realname_at 是否非空(上游返回过 archiveTime),不按运营商写死;基准取 upstream_realname_at。
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时区或格式变化] → 解析失败视为空,不影响状态,日志告警。 - [迁移补录数据量大] → 分批插入、可重复执行。
- [当前实名时间改为上游时间后,个别沉默期新判定结果与旧口径不同] → 用户确认采用新口径,已判定的不重算。
Migration Plan
- 部署迁移:建 3 张表 → 分批补录当前实名记录与迁移历史。
- 部署 api / worker:开始解析
archiveTime并写当前记录与历史;沉默期与展示切换读取源。 - 管理端前端上线实名记录与二次实名页面,分配权限
iot_card:realname_reset。 - 回滚:回滚 api / worker 镜像即可恢复旧读取(
first_realname_at一直保留且仍按旧规则写入);新表可保留。