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

72 lines
6.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
## 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
1. 部署迁移:建 3 张表 → 分批补录当前实名记录与迁移历史。
2. 部署 api / worker:开始解析 `archiveTime` 并写当前记录与历史;沉默期与展示切换读取源。
3. 管理端前端上线实名记录与二次实名页面,分配权限 `iot_card:realname_reset`。
4. 回滚:回滚 api / worker 镜像即可恢复旧读取(`first_realname_at` 一直保留且仍按旧规则写入);新表可保留。