Версионирование и обновления

Одна потребность: платформа и приложения должны иметь чёткую политику версий (API, конфигурация домена, клиент), обратную совместимость или миграции при обновлении, и управляемый процесс обновления для клиентов (окна обновления, откат).

Зачем это нужно (мировой опыт)

• Semantic Versioning (SemVer): мажор/минор/патч — стандарт для библиотек и API; клиенты понимают, чего ждать при обновлении.
• API versioning: REST (путь, заголовок, query) и GraphQL (deprecation, новые поля без ломания старых) позволяют не ломать существующих потребителей при развитии.
• Enterprise: окна обновления (maintenance window), откат на предыдущую версию при проблемах, release notes и матрица совместимости «клиент X — сервер Y».
• Low-Code (Mendix, OutSystems): версии приложений и платформы, перенос конфигурации между средами, совместимость рантайма и конфигурации.

Текущее состояние

• В домене есть сущность Version (снимки конфигурации); в админке — виджет «Версии», сохранение и восстановление снимков. Это версионирование конфигурации внутри одного инстанса.
• В приложении задаются __APP_VERSION__, VITE_VERSION, VITE_GIT_SHA (vite.config) — версия фронта при сборке.
• Нет явного контракта версий API (например, /api/v1/ и политика «v1 поддерживается N месяцев после выхода v2»).
• Нет документированной политики обновления платформы для заказчиков: как часто выходят обновления, как применять, как откатиться, что ломается при мажорном обновлении.

Что сделать

1. Версионирование API

• Ввести версию в путь или заголовок (например, GET /api/v1/...). Все новые breaking-изменения — в новой версии (v2); в v1 — только обратно совместимые изменения и deprecation с предупреждением.
• Документировать срок поддержки старых версий и план миграции (как перейти с v1 на v2).

2. Версионирование конфигурации домена

• Снимки (Version) уже есть; зафиксировать формат версии снимка (например, семантическая версия или монотонный номер) и совместимость: «рантайм версии X умеет загружать снимки формата Y». При несовместимости — миграция при импорте или явная ошибка с подсказкой.
• При экспорте/импорте между средами указывать версию формата; при необходимости — скрипты миграции со старого формата на новый.

3. Версионирование клиента (фронт)

• Текущая сборка уже вшивает версию; показывать её в UI (подвал, настройки, «О приложении») и при необходимости отправлять в заголовках запросов (X-Client-Version) для логирования и совместимости на бэкенде.
• При несовместимости «сервер требует клиент не ниже X» — показывать сообщение «Требуется обновление приложения» и ссылку на обновление/перезагрузку.

4. Политика обновлений для заказчиков

• Release notes: что изменилось в каждой версии (фичи, исправления, breaking changes), как мигрировать.
• Окна обновления: рекомендация или обязательность обновления в maintenance window; уведомление пользователей заранее.
• Откат: процедура отката на предыдущую версию (бэкенд + фронт) при критичном баге после деплоя; бэкапы перед обновлением.
• Матрица совместимости: какие версии клиента работают с какими версиями сервера; поддержка N последних минорных версий.

Риски и ограничения

• Поддержка нескольких версий API увеличивает объём кода и тестов на бэкенде; нужен чёткий срок жизни старых версий. Откат после деплоя требует совместимости данных и конфигурации (см. Backup_Restore_Policies).

Вывод

• Версионирование API (v1, v2) с обратной совместимостью и deprecation.
• Версионирование формата конфигурации домена и снимков; миграции при несовместимости.
• Версия клиента в сборке и в запросах; сообщение при несовместимости с сервером.
• Документированная политика обновлений: release notes, окна обновления, откат, матрица совместимости.