## 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`、联通 / 电信能否提供实名时间,需与网关确认;确认后扩充二次实名支持白名单。 - 上游对已实名过的卡是否仍能正常生成实名链接,需上线后用一张测试卡验证。