Один телефон может попасть в базу как 8 999..., +7 999..., 7999... или строка со скобками. Если просто удалить все символы кроме цифр, можно неверно определить страну, потерять добавочный номер и объединить разные контакты.

Нормализация требует контекста страны и проверенной библиотеки с метаданными нумерации. В базе полезно хранить нормализованное значение E.164 для поиска, исходный ввод для разбора спорных случаев и добавочный номер отдельным полем.

Что проверить в первую очередь

Сначала зафиксируйте наблюдаемое поведение и не меняйте сразу несколько настроек. Важны точное время сбоя, адрес или сценарий, ожидаемый результат и последнее известное рабочее состояние. Так можно отличить причину от случайного совпадения и сохранить возможность быстрого отката.

  • Соберите реальные форматы ввода по странам и источникам: сайт, импорт, CRM, API.
  • Проверьте, есть ли отдельное поле страны или надежный контекст региона.
  • Найдите места, где номер форматируется повторно перед записью или отправкой.
  • Оцените дубли, которые отличаются только пробелами, префиксом 8/+7 или знаками.

Почему возникает проблема

У подобных сбоев редко бывает одна универсальная причина. На итог одновременно влияют конфигурация приложения, окружение, данные, кеш, права и внешние сервисы. Проверка должна идти от внешнего симптома к конкретному уровню, на котором впервые появляется неверное состояние.

  • Код удаляет символы и добавляет один фиксированный код страны ко всем номерам.
  • Тип поля в базе числовой, поэтому теряется плюс, ведущие нули и точное представление.
  • Frontend и backend используют разные правила и метаданные.
  • Добавочный номер смешивается с основным или обрезается.
  • Импорт считает значение из Excel числом и переводит его в научную запись.

Пошаговая диагностика

Диагностику проводите на копии или в контролируемое время. Перед изменениями сохраните конфигурацию, данные и журналы. Каждый шаг должен отвечать на один вопрос и оставлять измеримый результат: код ответа, запись в логе, состояние процесса, значение поля или воспроизводимый тест.

  • Для выборки сравните raw input, country, normalized phone и результат отправки в SMS/CRM.
  • Проверьте короткие, международные, ведущие нули и номера с extension.
  • Найдите все точки записи и убедитесь, что нормализация выполняется один раз на границе.
  • Проверьте collation и уникальный индекс нормализованного строкового поля.
  • Разберите ошибки внешних сервисов: invalid, unreachable и unsupported — разные состояния.

Какую модель телефона хранить

Формат отображения и формат идентификации не должны быть одним полем, которое постоянно переписывается.

  • phone_e164 хранит международный формат строкой с плюсом.
  • phone_raw сохраняет исходный ввод на ограниченный срок, если это нужно для поддержки.
  • phone_country фиксирует выбранную страну или источник контекста.
  • phone_extension хранится отдельно и не участвует в SMS.
  • Статус подтверждения и время OTP относятся к номеру, но не меняют его формат.

Как исправить проблему

Исправление лучше разбить на небольшие обратимые изменения. После каждого шага повторяйте исходный сценарий и проверяйте соседние функции. Если правка касается данных, сначала выполните ее на ограниченной выборке и сохраните журнал затронутых записей.

  • Используйте актуальную библиотеку libphonenumber на сервере как источник истины.
  • Передавайте выбранную страну явно и не угадывайте ее только по длине.
  • Храните номер в VARCHAR, нормализуйте до проверки уникальности и записи.
  • Старые данные исправляйте пакетно с отчетом ambiguous/invalid, не угадывая спорные номера.
  • Синхронизируйте CRM и SMS через одно нормализованное поле и отдельный display formatter.

Безопасный порядок внедрения

  • Сохраните резервную копию затрагиваемых файлов, базы и конфигурации, а также заранее опишите способ отката.
  • Воспроизведите сбой на тестовой записи, учетной записи или отдельном окружении без реальных платежей и рассылок.
  • Вносите по одному логическому изменению, фиксируя его в системе контроля версий или журнале работ.
  • Не отключайте права, проверку входных данных и защитные механизмы только ради исчезновения сообщения об ошибке.
  • После выкладки контролируйте логи, метрики и ключевой пользовательский сценарий, а не только открытие одной страницы.

Как проверить результат

Успешный разовый тест еще не доказывает исправление. Нужны повторный запуск, крайние случаи и проверка после очистки кеша, перезапуска процесса или новой сессии. Для критичных сценариев полезно сохранить автоматический тест или хотя бы короткий регрессионный чек-лист.

  • Один номер в разных допустимых форматах дает одинаковый E.164.
  • Номера разных стран не получают российский код автоматически.
  • Добавочный номер сохраняется отдельно и не уходит в SMS API.
  • Миграционный отчет показывает исправленные, спорные и недействительные записи без тихой потери.

Типичные ошибки при исправлении

  • Хранить телефон в BIGINT и терять знак плюс и ведущие нули.
  • Проверять только регулярным выражением на количество цифр.
  • Автоматически заменять первую 8 на +7 для всех стран и источников.
  • Удалять исходные значения до разбора неоднозначных записей.

Как предотвратить повторение

Профилактика строится вокруг наблюдаемости и воспроизводимости: понятных конфигураций, контролируемых релизов, журналов без секретов и тестов на реальные сценарии. Важно не просто убрать текущий симптом, а сделать следующий похожий сбой заметным раньше пользователя.

  • Зафиксируйте единый серверный нормализатор для всех каналов записи.
  • Пишите тесты на реальные страны, extension и ошибочные форматы.
  • Обновляйте метаданные библиотеки нумерации контролируемо.
  • Отслеживайте долю invalid/ambiguous по источникам и исправляйте форму или импорт.

Что подготовить для разбора

  • Краткое описание ожидаемого и фактического поведения без паролей, токенов и персональных данных.
  • Точное время и последовательность действий, после которых появляется проблема.
  • Версии приложения, окружения и зависимостей, а также перечень последних изменений.
  • Фрагменты журналов с контекстом до и после ошибки; секреты в них необходимо скрыть.
  • Описание уже выполненных проверок и способ безопасно повторить проблему.

Частые вопросы

Можно ли определить страну только по номеру?

Если введен полный международный номер, обычно да. Для локального номера нужен контекст страны, иначе несколько интерпретаций могут быть допустимы.

E.164 гарантирует, что номер существует?

Нет. Он подтверждает допустимую структуру. Реальное владение проверяется звонком или одноразовым кодом.

Когда нужна помощь специалиста

Если номера сохраняются в разных форматах, создают дубли или не принимаются SMS/CRM, я могу выстроить единый нормализатор, безопасно разобрать старую базу и синхронизировать правила формы, backend и интеграций.