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

38 lines
3.7 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.
## Why
卡上的 `first_realname_at` 是系统轮询"第一次发现已实名"的时间,不是用户真实实名时间(如卡 89860885192590574640:上游实名 2026-07-16 19:43:39,库里记 20:03:25)。移动的实名查询其实已返回实名时间 `archiveTime`,但网关响应结构没解析;同时实名没有任何可查的历史。另外部分卡因上游原因需要二次实名(后一次实名覆盖前一次),C 端对已实名卡直接拒绝发放实名链接,无法办理,也无法区分上游返回的是旧实名还是新实名。
## What Changes
- 解析网关实名响应的 `archiveTime`(移动返回;联通、电信不返回)。
- 新增「卡当前实名记录」表(每卡一行):当前实名时间及来源(上游返回 / 首次读到 / 迁移沿用)、上游最近返回时间、首次读到已实名时间、二次实名状态与基准。
- 新增「卡实名时间历史」表:只在当前实名时间变化时追加一条,不是每次读到都写。
- 实名时间口径:有上游时间用上游时间;没有则用首次读到已实名的时间;已实名的老卡沿用库里现存实名时间(迁移补录);已实名但库里无时间的卡留空,等下次读到再填。
- 新增二次实名:管理端导入 ICCID / 虚拟号 / IMEI(设备则其全部绑定卡)形成批次,仅支持返回实名时间的运营商;系统清除卡实名状态与当前实名时间并记下清除前实名时间;之后上游返回的实名时间不晚于清除前时间时不覆盖,晚于时才算二次实名完成。C 端按普通未实名展示,不提示"二次实名"。
- 等待二次实名的卡按普通未实名卡处理:实名管控账户下按现有实名停机逻辑执行(关闭轮询的卡仍任何入口都不停复机),不新增停复机路径。
- 沉默期判定与资产实名时间展示改用当前实名时间;已判定过的套餐不重算。
- 管理端资产详情展示当前实名时间及来源、实名时间历史;二次实名批次导入与查询。
- `real_name_status` 保留在卡表,不迁移;`first_realname_at` 保留不删。
## Capabilities
### New Capabilities
- `card-realname-time`: 卡当前实名时间与来源、实名时间历史、上游实名时间解析与写入规则、老数据迁移补录、管理端实名记录展示。
- `card-realname-reset`: 二次实名批次导入、清除、新旧实名判定与完成、运营商支持范围、C 端无感展示、停机口径。
### Modified Capabilities
- `package-silence-period`(本迭代 `add-package-silence-period` 引入,尚未归档):沉默期"实名与过期判定"中的卡实名时间改取当前实名时间。以 ADDED 需求补充,不修改未归档变更的原文。
## Impact
- 数据库:新增 3 张表(当前实名记录、实名时间历史、二次实名批次)与迁移补录脚本;`tb_iot_card` 不加列。
- 网关:`internal/gateway/models.go` 实名响应结构新增 `archiveTime`。
- 卡观测:`internal/domain/cardobservation/realname.go`、`internal/application/cardobservation/apply.go` 增加实名时间判定与二次实名基准比较。
- 沉默期:`internal/application/packagesilence/resolve.go` 实名时间来源切换。
- 资产查询 / 导出:`internal/service/asset/service.go`、`internal/handler/admin/asset.go`、`internal/exporter/iot_card_scene.go` 实名时间字段来源切换。
- 新增管理端接口:资产实名记录查询、二次实名批次导入 / 列表 / 详情;新增权限码。
- 管理端前端(`iteration/8-11`):资产详情"实名记录"、二次实名批次页面(另行在前端仓库落地)。
- 只部署测试环境;测试环境网关只读开关保持开启。