Переименование полей и статусов: правила и шаги, чтобы изменения разошлись по UI, API и базе согласованно, без поломок и путаницы в данных.
Переименование полей и статусов кажется простой правкой: поменяли слово и пошли дальше. Но имя почти никогда не живет в одном месте. В итоге меняется только то, что видно в интерфейсе, а «внутри» остаются старые ключи, правила и зависимости.
Хаос начинается там, где название поля или значение статуса служит опорой для других частей продукта. Чаще всего ломаются отчеты и выгрузки (ожидают старые столбцы), фильтры и сортировки, интеграции и вебхуки, условия в бизнес-логике и уведомлениях, а также логи и метрики, которые потом трудно сопоставить.
Важно различать две вещи: смену подписи для пользователя и смену ключа в данных. Например, в интерфейсе можно показать «Оплачен», а в базе и API хранить paid. Если вы меняете только подпись, это косметика. Если меняете ключ (paid -> settled), это уже изменение контракта. Его нужно протянуть через UI, API, базу, документацию и тесты.
«Согласованно» значит, что в один и тот же момент времени вся система понимает одно и то же. Один статус не должен называться по-разному в разных слоях, а старые и новые имена не должны смешиваться в данных. Если вы делаете изменения с помощью ИИ, это особенно критично: он быстро обновит много мест, но без правил легко создаст два параллельных варианта. Поэтому переименование лучше вести как маленький проект: сначала явно решить, что меняем (подпись или ключ), затем составить полный список мест, где это имя живет.
Переименование почти никогда не про «красоту». Оно влияет на базу, API, интерфейс, отчеты и привычки команды. До первого коммита полезно договориться о нескольких вещах.
Сначала зафиксируйте цель и границы. Что именно вы улучшаете: читаемость для команды, единый словарь между бизнесом и разработкой, устранение двусмысленности, совпадение с термином в договоре. Формулировка должна быть конкретной: status = paid -> status = payment_received, чтобы отличать от paid_by_bonus. Когда цели нет, переименование превращается в бесконечную правку.
Дальше разделите изменения по риску. Одно дело - переименовать подпись в UI, другое - изменить поле в базе и контракт API. Для практики достаточно двух групп:
Назначьте владельца решения и точку финального согласования. Один человек (или пара «бизнес + техлид») должен отвечать за итоговый словарь. Иначе появится несколько «правильных» вариантов, и система снова расползется.
И последнее: решите заранее, будет ли временная поддержка старых названий. Например, API может принимать старое поле и новое параллельно 1-2 релиза, а UI показывать новое имя сразу. Если совместимости не будет, зафиксируйте дату отключения старого и список клиентов, которых нужно предупредить. Это решение определяет план работ и проверки перед релизом.
Перед переименованием нужно понять, где именно встречаются поля и статусы. Иначе вы переименуете одно место, а в другом останется старое имя, и ошибки всплывут уже у пользователей.
Начните с поверхности: откройте все экраны, где участвует поле или статус. Это не только бейдж, но и логика вроде «показывать кнопку оплаты только для Draft». Проверьте карточки, списки, формы создания, фильтры, таблицы, массовые действия и уведомления.
Затем спускайтесь в бекенд. Ищите не только название в схеме и в коде, но и места, где оно участвует в правилах: условия, вычисления, агрегации, права доступа, фоновые задачи. Отдельная зона риска - запросы к базе, которые строятся строками, и аналитические представления.
Не забудьте про интеграции. Старое имя может жить в импорте и экспорте, вебхуках, внешних отчетах и BI, а также в документации для партнеров. Даже если у вас нет публичного API, внутренние скрипты и автозагрузки данных тоже являются клиентами.
Полезно сразу разделять «как показываем» и «как храним». Пользовательская подпись может меняться почти без последствий, а ключ (имя поля, enum, код статуса) обычно требует совместимости.
Чтобы не расползаться в деталях, соберите короткую карту в одном месте:
Проблемы в переименованиях начинаются не с миграций, а с того, что у команды нет общего словаря. Один пишет «клиент», другой - «покупатель», третий - «контрагент». ИИ может обновить много мест, но если смысл плавает, он будет «чинить» одно и ломать другое.
Договоритесь о базовых словах: как называются сущности (User, Order, Invoice), роли (author, assignee), действия (approve, cancel). Рабочее правило простое: одно понятие - одно слово - один перевод.
Если приложение на русском, а ключи в коде на английском, зафиксируйте пары: «Сделка = deal», «Статус = status», «Исполнитель = assignee». Это снижает спорные зоны и делает переименование предсказуемым.
Для ключей выберите один стиль и не смешивайте:
order_status) или camelCase (orderStatus).customer_id лучше, чем cid, и лучше, чем customerIdentifierInSystem.Со статусами важнее смысл. Держите правило «одно значение - один смысл» и не плодите дублей вроде done и completed, если они означают одно и то же. Избегайте размытых значений: «прочее» быстро превращается в свалку, а «в работе» часто скрывает разные этапы.
Лучше разбить на конкретные состояния, которые можно объяснить одной фразой. Например, вместо «в работе» используйте pending_review (ждет проверки) и in_progress (выполняется). Тогда при следующем переименовании проще проверить границы, а не угадывать по контексту.
Переименование стоит воспринимать как маленький релиз, а не как «поправили пару слов». Тогда появляется понятный порядок: что меняем, где, как проверяем и как откатываем.
Обычно есть два варианта.
Мягкая замена подходит, когда у вас уже есть пользователи, интеграции или мобильное приложение в сторе. Вы вводите новое имя и временно поддерживаете старое через алиас или совместимость (например, в API принимаете оба поля, а отдаете одно).
Жесткая замена уместна в раннем проекте или когда вы точно контролируете всех клиентов. Вы меняете везде сразу и удаляете старое имя без периода совместимости.
До любых правок заведите таблицу «старое -> новое» отдельно для полей и для статусов. Для статусов важно описывать смысл, а не только слово: чем отличается, когда устанавливается, какие переходы разрешены.
Пример записи: order_state: PAID -> payment_status: SUCCESS + заметка «ставится после подтверждения от платежки». Такая карта помогает и при массовых правках, и при проверке результата.
Часто безопаснее идти так: данные -> API -> UI. Сначала миграции и преобразование данных, затем совместимость на границе (API), и только потом формы, фильтры и тексты в интерфейсе.
Иногда удобнее начать с UI: добавить отображение нового названия как второго варианта, а затем менять данные. Ключевое правило одно: в любой момент времени система должна понимать, что делать со старым и новым.
Заранее решите, что именно откатываем: миграцию схемы, данные, контракт API или тексты в UI. Для отката удобно иметь понятный шаг назад: вернуть алиасы, восстановить старые поля, пересчитать статусы обратно.
Переименование проходит быстрее, когда вы сначала фиксируете замысел, а затем отдаете ИИ механическую часть: поиск, замены и согласование слоев.
Допустим, статус paid вы хотите переименовать в payment_received, а поле phone - в contact_phone. Ошибка обычно не в самой замене, а в том, что где-то останется старое имя: в форме, в ответе API, в проверках на бэкенде или в обработчике на фронте.
Рабочий порядок действий выглядит так:
Чтобы ИИ не угадывал, давайте ему короткое ТЗ: старые и новые имена, допустимые значения статусов, а также пример одного запроса и ответа API «до» и «после». Это резко снижает риск неполного или противоречивого переименования.
Не каждое «переименование» требует трогать базу. Если меняется только текст для людей (подпись в форме, заголовок столбца, название статуса в интерфейсе), часто достаточно UI и переводов. Но если новое имя должно жить в API, в выгрузках или в логике, без миграции легко получить путаницу.
Самый безопасный путь при переименовании колонки - сделать так, чтобы данные существовали в двух местах на время перехода. Прямое RENAME COLUMN быстрое, но опасно, если зависимостей много и нет уверенности, что все обновилось.
Обычно работает такой порядок: добавляете новую колонку, копируете данные (иногда с временной синхронизацией), обновляете код на чтение и запись, а старую колонку удаляете только после проверок и релиза.
Со статусами похожая история, только вы меняете не колонку, а значения внутри. Например, было new, стало draft, или вы разделили done на done и archived. Тогда миграция должна перевести существующие записи по правилам. Заранее опишите таблицу соответствий и что делать с редкими или «неожиданными» значениями.
Где чаще всего забывают обновить: индексы, представления, триггеры, отчеты, фоновые задачи и ручные SQL-скрипты. Если статус участвует в фильтрах или индексах, смена значений без обновления этих мест даст странные выборки.
Чтобы не ломать исторические данные, полезно сохранять исходные значения в отдельном поле или журнале. Для совместимости можно оставлять чтение старого формата (например, маппить старые статусы в новые при выдаче данных). Тогда вы сможете открыть старые записи и понять, что именно имелось в виду на момент создания.
При переименовании чаще всего «падает» не база, а клиент. В UI завязано много мелочей: валидация формы, маски ввода, правила обязательности, фильтры, сортировки, подписи и подсказки. Если поле было phone, а стало contact_phone, старый экран может перестать сохранять данные или начнет показывать пустые значения.
В API ломаются сериализация и десериализация, DTO и контракты, автогенерация документации, иногда кеши на стороне клиента. Особенно неприятно, когда статус меняется не только по названию, но и по смыслу (например, PAID разделили на PAID и REFUNDED).
Самый безопасный переход - временно поддерживать совместимость. На практике это выглядит так: в ответах отдаете новое поле и на время дублируете старое; в запросах принимаете оба варианта и приводите к одному внутреннему; для статусов держите таблицу соответствий; изменения фиксируете в описаниях контрактов и тестах; добавляете логирование, сколько запросов еще приходит со старым форматом.
Отдельно продумайте «неизвестный статус». Старые клиенты должны уметь показать нейтральное состояние без падения экрана. Например, если появился ARCHIVED, старый клиент может трактовать его как «Скрыто» и запрещать редактирование.
После переименования поле или статус часто ломается не там, где вы меняли код, а там, где имя было зашито в правила, фильтры, отчеты или тексты. Поэтому лучше начать с короткого набора проверок, который почти всегда ловит главные проблемы.
Пройдите путь, который делает большинство людей каждый день: создание записи (новое поле сохраняется), редактирование (ничего не «обнуляется»), поиск и фильтры (дают ожидаемые результаты), экспорт (выгрузка содержит правильные названия и значения).
Статусы опасны тем, что правила часто сравнивают значения как строки. Проверьте ограничения и переходы: что можно сделать из какого статуса, что запрещено, какие обязательные поля требуются.
Простой пример: было «На проверке», стало «Проверка». В коде мог остаться запрет вида status == 'На проверке'. В интерфейсе все выглядит нормально, но правило перестает работать.
Проверьте места, где статусы группируются и считаются: дашборды, отчеты по воронке, суммы по «успешным» статусам, SLA. Частая ошибка: часть данных попадает в «Другие», потому что группировка ждет старое значение.
Убедитесь, что письма, пуши, сообщения и логи показывают корректные названия и не подставляют пустые значения. Важно также сохранить ключи, по которым вы ищете инциденты.
Самая частая путаница начинается, когда меняют только то, что видно человеку: обновили подпись в интерфейсе, а ключ поля (в базе, API или JSON) оставили старым. Или наоборот: сменили ключ, а UI еще показывает прежнее. В итоге интеграции падают, а пользователи видят одно название, но данные уходят под другим.
Вторая ловушка - статусы. Кажется, что это просто слово, но за ним стоят переходы, уведомления, фильтры, отчеты и права доступа. Если переименовать статус и не обновить все места, где он сравнивается как строка, часть процессов начнет вести себя странно: задача «зависает» между этапами или становится невидимой для нужной роли.
Часто переименование делают частично: UI поправили, а экспорт в CSV, шаблоны писем, вебхуки или мобильный экран забыли. Снаружи все красиво, но данные на выходе остаются со старой схемой.
Короткий список типовых сбоев:
Пример: вы меняете статус «На проверке» на «Проверка». Если в правилах доступов осталось условие status == "На проверке", менеджеры внезапно теряют доступ к карточкам.
Перед выпуском полезно убедиться, что вы не «починили одно место и забыли про три других». Лучше потратить 15 минут на проверку, чем сутки на разбор инцидента.
Проверьте:
NULL «по умолчанию».После релиза проверьте не только «открылось ли», но и сигналы, которые быстро показывают проблему: ошибки 4xx/5xx на методах с этим полем/статусом, ключевые пользовательские сценарии (создание, изменение, поиск, экспорт), метрики (конверсии, успешные платежи, скорость ответов), частоту обращений со старым именем, а также данные на предмет «двойных» значений и неожиданных пустот.
Представьте CRM, где в карточке сделки есть поле «Клиент». Со временем стало ясно, что чаще это не человек, а юрлицо, и поле решили переименовать в «Компания». Параллельно статус «В работе» оказался слишком расплывчатым, и его разделили на два: «На согласовании» и «Выполняется». Такой кейс легко ломает отчеты и интеграции, если делать на бегу.
Сначала собрали карту влияния: не просто «где в коде встречается слово», а где оно важно для бизнеса. Прошли путь пользователя от списка сделок до счета и отметили все места, где отображается название или работает логика по статусу. Условная карта выглядела так: UI (список сделок, карточка, быстрый поиск, фильтры, два отчета продаж), API (эндпоинт создания и вебхук для бухгалтерии), данные (правила автоматизации и шаблоны уведомлений), документы (печатная форма договора).
Дальше сделали миграцию статусов. В базе оставили старое значение как техническое на время перехода, а для существующих записей применили правило: если у сделки есть активная задача согласования, то «В работе» -> «На согласовании», иначе -> «Выполняется». Это сильно сократило ручную правку.
Чтобы выпуск прошел спокойно, на 1-2 релиза добавили временную совместимость: API принимал и старые, и новые значения, а в логах помечал запросы со старым статусом.
В первый час после выкладки проверили создание и редактирование сделки в UI, два ключевых отчета (цифры и фильтры), входящие вебхуки (нет ли всплеска 4xx/5xx), выборку сделок, которые остались с «В работе» (должно быть близко к нулю), и уведомления (корректно ли подставляется «Компания»).
Чтобы переименования не превращались в разовые подвиги, относитесь к ним как к обычной части разработки. Закрепите словарь терминов и правила именования прямо в проекте. Тогда переименование будет не спором в чате, а задачей с понятными критериями готовности.
Планируйте изменения малыми порциями. Одно поле или один статус за раз проще проверить, откатить и донести до команды, чем большой ком правок, где трудно понять, что именно сломалось.
Полезная привычка после каждого переименования:
Если вы ведете разработку в TakProsto, удобно использовать планирование и snapshots: сначала описываете правила переименования, потом быстро проверяете, что изменения прошли согласованно в UI и API, и при необходимости откатываетесь. Сам сервис доступен как takprosto.ai (важно заранее договориться в команде, какие ключи меняются, а где меняется только подпись).
Подпись — это текст, который видит пользователь, и его обычно можно менять без последствий. Ключ — это то, что хранится в данных и уходит через API, например paid или contact_phone. Если меняется ключ, вы меняете контракт: нужно обновить БД, API, код, тесты и места, где ключ сравнивается или используется в отчетах.
Если поле или статус участвует в интеграциях, выгрузках, отчетах, правилах автоматизации или публичном API — это почти всегда рискованное изменение. Если меняется только текст на экране и он не влияет на данные и контракт, это обычно безопасно. Сомневаетесь — считайте это сменой контракта и планируйте совместимость.
Сначала определите, какие слои затрагиваются: UI, API, база, отчеты, интеграции, уведомления. Затем составьте карту «где встречается имя» и таблицу соответствий «старое → новое» для полей и отдельно для статусов. После этого выберите стратегию: поддержка старого формата на время или замена везде сразу.
Мягкая замена нужна, когда есть внешние клиенты, мобильные приложения или интеграции, которые нельзя обновить мгновенно. Жесткая замена подходит, когда вы контролируете всех потребителей данных и готовы обновить всё одним релизом. По умолчанию безопаснее мягкая замена с понятной датой отключения старого формата.
Обычно вы на время принимаете оба варианта в запросах и приводите их к одному внутреннему формату. В ответах отдаете новый формат, а старый дублируете только на переходный период, чтобы клиенты не падали. Важно логировать обращения к устаревшим полям и заранее договориться, когда старое будет отключено.
Сначала зафиксируйте смысл каждого статуса одной фразой, а не только новое слово. Затем сделайте явный маппинг старых значений в новые и примените его в миграции данных и на границе API. Если появляется новый статус, старые клиенты должны уметь показать нейтральное состояние без ошибок и без опасных действий.
Для переименования колонки безопаснее временно держать данные в двух местах: добавить новую колонку, перенести значения и переключить код на чтение/запись в новую. Старую колонку удаляют только после релиза и проверки. Прямой RENAME COLUMN быстрый, но часто ломает зависимости, которые сложно заметить заранее.
Сначала пройдите основные пользовательские сценарии: создать запись, отредактировать, найти через фильтры, выгрузить данные. Затем проверьте бизнес-правила, где статус сравнивается как строка, и аналитические группировки, которые ожидают старые значения. В конце посмотрите уведомления и логи, чтобы там не появились пустые подстановки и несопоставимые события.
План отката должен быть готов до релиза: что возвращаете и как быстро, особенно для схемы БД и контрактов API. В TakProsto удобно делать снимок состояния перед массовыми правками и откатываться, если нашли расхождения между слоями. Откат проще, когда вы использовали переходный период и не удаляли старые имена сразу.
Дайте ИИ короткое ТЗ: старое и новое имя, список статусов, правила маппинга и пример запросов/ответов «до/после». Попросите его не просто заменить строки, а вернуть список файлов и мест, где внесены изменения, чтобы вы могли сверить карту влияния. В TakProsto полезно сначала включить режим планирования, а затем применять правки по слоям, чтобы не получить два параллельных варианта в данных и интерфейсе.