Почему важно отслеживать версии ядра платформы

Что такое «ядро платформы» и почему версии критичны

Под «ядром» понимаем домены, где ошибкам не прощают: кошелёк и леджер, ставки/расчёт раундов, касса (депозиты/выплаты), идентификация (KYC/AML/RG), контракты с игровыми провайдерами и биллинг/отчётность.

Любое обновление здесь влияет на деньги, регуляторику, доверие. Поэтому версии ядра — это не «номер в package.json», а инструмент управления изменениями и ответственностью.

Зачем отслеживать версии

1. Управление риском денег. Чётко знаем, какой код рассчитался по какому раунду/выплате — снимает споры и ускоряет разбор инцидентов.

2. Совместимость интеграций. Провайдеры игр/платежей завязаны на контракты. Версия = гарант того, что поля, статусы и бизнес-правила совпадают.

3. Комплаенс и аудит. Регулятор требует воспроизводимости: «какой build, какая схема, какой контроль». Версия — якорь доказательной базы.

4. Быстрые релизы без даунтайма. Версионирование позволяет выпускать совместимые изменения и раскатывать канареечно.

5. Инцидент-менеджмент. Rollback/roll-forward просты, когда есть тегированные артефакты, миграции и матрица совместимости.

6. Прозрачность для продуктовых команд. Когда «контракт стабилен до X.Y», фронты/маркетинг/аналитика планируют без сюрпризов.

Политика версий (SemVer для ядра)

Используем SemVer `MAJOR.MINOR.PATCH` + «ревизию схемы» и «версию контракта событий»:

PATCH (x.y.Z) — исправления без изменения API/схем/логики расчёта. Rollout быстрый, rollback тривиален.
MINOR (x.Y.z) — совместимые расширения: новые поля «nullable», новые события, флаги. Миграции «expand-only».
MAJOR (X.y.z) — ломающие изменения: удаление полей/событий, смена правил расчёта, новых инвариантов леджера.

Дополнительно фиксируем:

`schemaVer` (БД/леджер/каталоги), `contractVer` (события шины и вебхуки), `calcVer` (движок расчёта/бонусных правил).

💡 Правило: одно направление в релизе. Либо «расширяем без ломки», либо «ломаем с тенью». Смешение — путь к инцидентам.

Контракты и обратная совместимость

Договоры для внешних и внутренних потребителей

API/вебхуки/события: версионируем URL (`/v2/…`), заголовок (`X-Contract-Version`), поле `schemaVer` в полезной нагрузке.

События в шине: поле `eventVer`, запрет silent-breaking (изменения типа поля, смысла статусов).

БД: миграции в стиле expand → migrate → contract.

Добавлять можно, менять — осторожно, удалять — с «тенью»

Добавление полей — только nullable/с дефолтом.

Смена смысла — лишь в MAJOR с параллельной публикацией «старого» поля (`_legacy`) на переходный период.

Удаление — после депрекейта и телеметрии «кто ещё читает старое».

Миграции схем и данных

Expand: добавить колонку/индекс, ввести новое событие — без касания существующих читателей.

Migrate: заполнить/пересчитать значения в фоне (batch/online), включить двойную запись (dual-write) в новое место.

Contract: перевести читателей, убрать legacy-ветку в следующем MAJOR.

Инструменты: миграции под feature-flag, shadow-таблицы, онлайн-DDL, инварианты на уровне БД (check-constraints) и домена.

Версионирование расчётов: деньги, ставки, бонусы

Отдельно фиксируйте `calcVer` — версию логики денежного расчёта (ставка/hold/settle/VOID, правила бонусов и отыгрыша).

В каждый `round.settled`, `payout.completed`, `bonus.issued` записывайте `calcVer`.

При споре можно воспроизвести расчёт именно той логикой, что действовала в момент события.

Переключение `calcVer` делайте канареечно по проценту трафика/региону/категории игр.

Observability для версионности

Теги в трейсе: `buildId`, `gitSha`, `semver`, `schemaVer`, `contractVer`, `calcVer` во всех критичных спэнах (ставка, settle, payout).

Дашборды по версиям: ошибки, латентность, фин-дельты в разрезе версий.

Алерты на «версионный дрейф»: когда часть потребителей шины читает не ту схему.

Безопасность и комплаенс

Версионированные артефакты (образы, миграции) подписаны; хранятся в неизменяемом registry/bucket.

DR/аудит: можно поднять окружение «как было в дату T» (образ, миграции до версии, снапшоты БД).

Ревизии правил AML/RG/KYT — это тоже версии (policyVer) и логи их применения.

Процедуры релизов

1. Контракт-ревью: список изменений с пометкой `PATCH/MINOR/MAJOR`, влияние на внешних/внутренних потребителей.

2. Backwards-compat тесты: проверки на старых клиентах/событиях (контрактные тесты).

3. Канареечный rollout: 1–5% трафика; метрики по p95, ошибкам, финансовым расхождениям.

4. Телеметрия использования legacy: кто ещё слушает `v1`, какие поля читаются — план депрекейта.

5. Комм-пакет: что меняется, когда end-of-life старых версий, как мигрировать.

Типовые матрицы совместимости (пример)

Компонент	Клиент (мин. версия)	Сервер	Состояние
`wallet-api`	1.7	2.3	OK (MINOR)
`bets-webhook`	1.4	2.0	OK, legacy-поле `odds_legacy` до 2026-01-31
`ledger-schema`	–	3.1	Требует миграцию `expand` до релиза 3.2
`events.contract`	1.x	2.x	Dual-publish до выключения `v1`

Примеры контрактов

Событие шины с версией:

json
{
"event": "round.settled",  "eventVer": "2.4",  "schemaVer": "ledger-3.1",  "calcVer": "wallet-7.2",  "roundId": "R-2025-10-17-PRAGM-12",  "bets": [{"betId":"b_9f2","stake":"5.00","payout":"180.00","outcome":"WIN"}],  "ts": "2025-10-17T14:23:12.031Z",  "traceId": "tr_5f1"
}

REST c версией контракта:


GET /v2/wallet/balance
X-Contract-Version: 2.3

Анти-паттерны

«Тихие» изменения: менять типы/смыслы полей без MAJOR и депрекейта.

Смешивать миграцию данных и логику денег в одном релизе без dual-write.

Глобальные флаги вместо версий (невозможно восстановить, «что действовало тогда»).

Отсутствие контрактных тестов и каталога схем.

Удалять legacy без телеметрии использования — ломаются партнёры/дашборды.

Единый номер «где-то в вики» без артефактов/подписей — не воспроизводимо.

Чек-лист дисциплины версий ядра

Стандарты

Семейство версий: `semver`, `schemaVer`, `contractVer`, `calcVer`, `policyVer`.
Каталог данных/схем (data catalog) с историей и владельцами.

Контракты

Версионированные эндпоинты/события, header/поле версии.
Deprecation-процедура с датами и телеметрией использования.

Миграции

Expand→Migrate→Contract, dual-write, онлайн-DDL.
Shadow-таблицы и инварианты на уровне БД.

Релизы

Канареечный rollout, матрица совместимости, rollback-план.
Подписанные образы/миграции, неизменяемые артефакты.

Observability

Теги версий в трейсе/логах/метриках.
Дашборды ошибок/латентности/фин-дельт по версиям.

Комплаенс/DR

Воспроизводимый подъём окружения «на дату T».
Логи применения policyVer (AML/RG/KYT).

Версионность ядра — это «страховка» денег и темп развития продукта. С ней платформа предсказуемо эволюционирует: новые возможности выходят без поломок, финансы остаются воспроизводимыми, интеграции — совместимыми, аудит — спокойным. Сделайте версии частью процесса (контракты, миграции, телеметрия, релизы) — и ваш бэкенд выдержит годы изменений без потерь для P&L и репутации.