Чому важливо відстежувати версії ядра платформи

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

Під «ядром» розуміємо домени, де помилкам не прощають: гаманець і леджер, ставки/розрахунок раундів, каса (депозити/виплати), ідентифікація (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/c дефолтом.

Зміна сенсу - лише в 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 і репутації.