Telegram 注册结果与刷新尝试的数据模型

为什么一个布尔值不够

Telegram 注册结果是完成检测产生的带时间戳观测，不是永久附着在手机号上的事实。

telegram_valid 之类的字段会丢失关键上下文：它没有说明实际检测的是哪个规范号码、检测发生在什么时候、false 是否来自完成判断，甚至无法确认请求是不是失败了。数据库必须保留这些区别，应用才能诚实地展示和刷新结果。

TG Validator 同步返回完成判断，因此 HTTP 响应到达时就可以写入观测。返回字段应原样保存，不需要再发明一组产品状态。

把主体记录与检测观测分开

使用一条稳定的内部手机号记录，再关联多条检测观测。这样无需改写历史，后续刷新也容易理解。

记录	建议字段	用途
手机号来源	phone_id、source_phone、source_system	保留原始业务记录
规范手机号	phone_id、e164_phone、normalized_at	记录实际被检测的规范值
检测观测	phone_id、status、registered、received_at、transaction_id	保存一次同步结果

如果因为纠正国家信息而改变规范结果，应新建或版本化规范记录，不能把旧 Telegram 结果悄悄关联到重新解释后的手机号。

使用准确的公开响应形态

返回形态	registered 值	含义
code=0、data.status=success	true	完成检测报告已注册
code=0、data.status=success	false	完成检测报告未注册
code=0、data.status=undetermined	null	没有注册判断，最终不扣费
非零 API code、data=null	不存在	API 错误，不是注册结果

允许为空是刻意的设计。文档定义的无法判定结果中，null 表示服务没有布尔答案。输入无效、限流、余额不足、维护和内部失败使用独立错误响应，不会给 data.status 增加更多取值。

当前状态与最新尝试应是两个视图

系统通常需要回答两个问题：

1. 最新一次完成的注册观测是什么？
2. 最新一次请求尝试发生了什么？

它们可能指向不同记录。T1 完成得到 true，T2 刷新返回 API 错误时，最新完成观测仍是 T1 的 true，而独立请求日志可以保存 T2 的 HTTP 状态与 API code。同时展示两者，可以避免操作人员把 T1 误认为新结果，或把 T2 误认为 false。

后续 T3 完成得到 false 时，当前完成视图才前进到 T3；T1 和 T2 仍保留用于审计与排查。

明确定义何时必须刷新

TG Validator 在被调用时提供同步当前观测，但结果新鲜度策略属于接入应用。应根据实际判断选择最大可接受年龄，并在界面中展示这个时间差。

刷新策略需要说明：

• 每种流程接受的最大结果年龄；
• 后续 API 错误发生后，操作人员能否使用更早的完成结果；
• 无法判定响应是否需要稍后再次提交；
• 速率与并发限制如何影响调度；
• 长期保留每次尝试，还是只保留完成观测。

不要仅仅因为完成结果是 registered=false 就立即重试。只有需要更晚的时点观测，或者上次尝试根本没有产生判断时，重试才有意义。

准确查询当前状态

当前注册状态应选择返回 status=success 的最新观测，并始终同时返回 registered 和本地 received_at。绝不能只展示布尔值而隐藏时间戳。

最新尝试状态则选择任意状态中的最新观测。如果它尚未完成，界面可以说明发生过更新尝试，同时不替换最近已知注册结果。

可持续的数据原则

追加观测、保留时间戳，永远不要把运行不确定性强制转换为 Telegram 注册值。

这个模型与产品完全一致：TG Validator 同步回答一个注册问题，不提供身份或账号资料。客户应用负责稳定记录、保存策略、刷新计划以及围绕每次观测作出的业务判断。