Жизненный цикл результата
Модель данных для результатов регистрации в Telegram и повторных проверок
Храните поля ответа о регистрации в Telegram, отличайте завершенные результаты от ошибок API и сохраняйте локальную отметку времени ответа.
Почему одного логического значения недостаточно
Результат регистрации в Telegram — это наблюдение с отметкой времени, полученное в результате завершенной проверки, а не постоянная истина, привязанная к номеру телефона.
Поле вроде telegram_valid теряет важный контекст. Из него не ясно, какой нормализованный номер проверялся, когда выполнялась проверка, было ли false завершенным решением и не завершился ли запрос на самом деле ошибкой. База данных должна сохранять эти различия, чтобы приложение могло честно отображать и обновлять результат.
TG Validator возвращает завершенное решение синхронно, поэтому наблюдение можно записать сразу после получения HTTP-ответа. Возвращенные поля следует хранить как есть, не придумывая дополнительный набор статусов продукта.
Отделяйте объект от наблюдений
Используйте одну стабильную внутреннюю запись номера телефона и привязывайте к ней несколько наблюдений проверок. Это позволяет не переписывать историю и упрощает понимание последующих обновлений.
| Запись | Рекомендуемые поля | Назначение |
|---|---|---|
| Исходный номер | phone_id, source_phone, source_system |
Сохраняет исходную бизнес-запись |
| Нормализованный номер | phone_id, e164_phone, normalized_at |
Фиксирует каноническое значение, используемое для проверок |
| Наблюдение проверки | phone_id, service_type, registered, received_at |
Хранит один синхронный результат |
Если нормализация меняется из-за исправления исходного контекста страны, создайте новую каноническую запись или новую ее версию. Не привязывайте молча старый результат Telegram к заново интерпретированному номеру телефона.
Используйте точные задокументированные структуры ответа
| Возвращенная структура | Значение registered |
Смысл |
|---|---|---|
code=0, data.registered=true |
true | Завершенная проверка сообщила: зарегистрирован |
code=0, data.registered=false |
false | Завершенная проверка сообщила: не зарегистрирован |
Ненулевой code API |
Отсутствует | Решения о регистрации нет; это ошибка API, а не результат регистрации |
Это различие намеренное. Ненулевой код API означает, что у сервиса нет логического ответа, который можно сохранить. Недопустимые входные данные, отказы из-за ограничения параллельности, недостаточный баланс, техническое обслуживание и внутренние сбои не добавляют новых значений в data.registered.
Храните текущее состояние и последнюю попытку как два представления
Часто полезны два вопроса:
- Каково самое свежее завершенное наблюдение за регистрацией?
- Что произошло при самой последней попытке запроса?
Они могут указывать на разные строки. Если за завершенным результатом true в момент T1 следует ошибка API в момент T2, самым свежим завершенным наблюдением по-прежнему остается true в T1, а отдельный журнал запросов может зафиксировать HTTP-статус и код API из T2. Это не позволит оператору принять T1 за свежий результат или T2 — за false.
Когда последующий вызов в момент T3 завершается с false, представление текущего завершенного состояния переходит к T3. Записи T1 и T2 остаются доступными для аудита и диагностики.
Определите, когда требуется обновление
TG Validator при вызове предоставляет актуальное синхронное наблюдение, но политику свежести данных определяет интегрирующее приложение. Выберите максимально допустимый возраст результата в зависимости от принимаемого решения и сделайте этот возраст видимым в интерфейсе.
Политика обновления должна определять:
- максимально допустимый возраст для каждого процесса;
- могут ли операторы использовать более старый завершенный результат после последующей ошибки API;
- какие ненулевые ответы API следует отправить повторно позже;
- как ограничение параллельности для каждого пользователя влияет на планирование;
- хранятся ли долгосрочно все попытки или только завершенные наблюдения.
Не повторяйте завершенную проверку с registered=false только потому, что результат — false. Повторяйте проверку, когда нужно более новое наблюдение на определенный момент или когда предыдущая попытка не дала решения.
Точный запрос текущего состояния
Текущее состояние регистрации должно выбирать последнее наблюдение, у которого внешний ответ имел code=0, и возвращать его значение registered вместе с локальным received_at. Никогда не возвращайте логическое значение без отметки времени.
Состояние последней попытки должно выбирать самое новое наблюдение с любым статусом. Если оно не завершено, интерфейс может пояснить, что была предпринята более новая проверка, не заменяя последний известный результат регистрации.
Принцип надежного проектирования
Добавляйте наблюдения, сохраняйте их отметки времени и никогда не превращайте операционную неопределенность в значение регистрации в Telegram.
Эта модель в точности соответствует продукту. TG Validator синхронно отвечает на один вопрос о регистрации; он не предоставляет данных об идентификации личности или профиле аккаунта. Клиентское приложение обеспечивает стабильную запись, политику хранения, расписание обновлений и бизнес-решение вокруг каждого наблюдения.