Pourquoi il est important de suivre les versions du noyau de la plate-forme

Qu'est-ce que le « noyau de la plate-forme » et pourquoi les versions sont critiques

Par « noyau », on entend les domaines où les erreurs ne sont pas pardonnées : portefeuille et ledger, taux/calcul des rounds, caisse (dépôts/paiements), identification (KYC/AML/RG), contrats avec les fournisseurs de jeux et facturation/déclaration.

Toute mise à jour ici affecte l'argent, la réglementation, la confiance. C'est pourquoi les versions du noyau ne sont pas un "numéro dans le paquet. json", et un outil de gestion du changement et de la responsabilité.

Pourquoi suivre les versions

1. Gérer le risque de l'argent. Nous savons clairement quel code a été calculé sur quel tour/paiement - enlève les différends et accélère l'analyse des incidents.

2. Compatibilité des intégrations. Les fournisseurs de jeux/paiements sont liés par des contrats. Version = garant que les champs, les statuts et les règles commerciales correspondent.

3. Conformité et audit. Le régulateur exige la reproductibilité : « quel build, quel schéma, quel contrôle ». La version est l'ancre de la base de données.

4. Sorties rapides sans downtime. Le versioning permet de publier des modifications compatibles et de les dérouler canariquement.

5. L'incident de gestion. Rollback/roll-forward est simple lorsqu'il y a des artefacts, des migrations et une matrice de compatibilité.

6. Transparence pour les équipes de produits. Lorsque le « contrat est stable jusqu'à X.Y », les fronts/marketing/analytique sont prévus sans surprise.

Stratégie de version (BouVer pour le noyau)

Nous utilisons SamVer 'MAJOR. MINOR. PATCH' + « révision du schéma » et « version du contrat d'événements » :

PATCH (x.y. Z) - corrections sans modification des API/schémas/logique de calcul. Rollout est rapide, rollback est trivial.
MINOR (x.Y.z) - extensions compatibles : nouveaux champs « nullable », nouveaux événements, drapeaux. Migration expand-only.
MAJOR (X.y. z) - modifications cassantes : suppression des champs/événements, changement des règles de calcul, nouveaux invariants du ledger.

En outre, nous fixons :

« schemaVer » (OBD/ledger/catalogues), « contractVer » (événements de bus et webhooks), « calcVer » (moteur de calcul/règles de bonus).

💡 Règle : une direction dans la version. Soit « on dilate sans casser », soit « on brise avec l'ombre ». Le mélange est le chemin des incidents.

Contrats et rétrocompatibilité

Contrats pour les consommateurs extérieurs et nationaux

API/webhooks/événements : versionnons l'URL ('/v2/... '), l'en-tête (' X-Contract-Version '), le champ' schemaVer 'dans la charge utile.

Événements dans le bus : champ 'eventVer', interdiction du silent-breaking (modifications du type de champ, signification des statuts).

OBD : migration dans le style expand → migrate → contract.

Vous pouvez ajouter, changer - soigneusement, supprimer - avec « ombre »

L'ajout de champs n'est qu'un défaut nullable/c.

Le changement de sens n'est que dans MAJOR avec la publication parallèle de l'ancien champ ('_ legacy') pour une période de transition.

Suppression - après le deprecate et la télémétrie « qui lit l'ancien ».

Migration de schémas et de données

Expand : ajouter une colonne/index, entrer un nouvel événement - sans toucher aux lecteurs existants.

Migrate : remplir/recalculer les valeurs en arrière-plan (batch/online), inclure un double enregistrement (dual-write) dans un nouvel emplacement.

Contrat : traduire les lecteurs, enlever la branche legacy dans le prochain MAJOR.

Outils : migrations sous feature-flag, tables shadow, DDL en ligne, invariants au niveau OBD (check-constraints) et domaine.

La versionation des calculs : argent, paris, bonus

Fixez séparément 'calcVer' - la version de la logique de calcul monétaire (pari/hold/settle/VOID, règles de bonus et de pari).

Chaque round. settled`, `payout. completed`, `bonus. issued 'écrire' calcVer '.

En cas de différend, vous pouvez reproduire le calcul avec la logique qui était en vigueur au moment de l'événement.

Basculez 'calcVer' en fonction du pourcentage de trafic/région/catégorie de jeu.

Observability pour la versibilité

Les balises de la piste sont : 'buildId', 'gitSha', 'semver', 'schemaVer', 'contractVer', 'calcVer' dans tous les spins critiques (pari, settle, payout).

Dashboards selon les versions : erreurs, latence, fin delta dans la coupe des versions.

Alert sur la « dérive de la version » : quand une partie des consommateurs de pneus lit le mauvais schéma.

Sécurité et conformité

Les artefacts versionnés (images, migrations) sont signés ; sont stockés dans un registre/bucket immuable.

DR/audit : vous pouvez soulever l'environnement « comme à la date T » (image, migration vers la version, snapshots OBD).

Les révisions des règles AML/RG/KYT sont également des versions (policyVer) et des logs de leur application.

Procédures de sortie

1. Contrat-revue : liste des changements notés « PATCH/MINEUR/MAJEUR », impact sur les consommateurs externes/internes.

2. Tests backwards-compat : vérifications sur les anciens clients/événements (tests contractuels).

3. Rollout canarien : 1-5 % du trafic ; métriques par p95, erreurs, divergences financières.

4. Télémétrie de l'utilisation de la légende : qui d'autre écoute « v1 », quels champs sont lus - plan de déprécation.

5. Com-pack : ce qui change quand fin-of-life des anciennes versions, comment migrer.

Matrices types de compatibilité (exemple)

Composant	Client (min. version)	Serveur	État
`wallet-api`	1. 7	2. 3	OK (MINOR)
`bets-webhook`	1. 4	2. 0	OK, le champ legacy 'odds _ legacy' avant 2026-01-31
`ledger-schema`	–	3. 1	Nécessite la migration de 'expand' avant la sortie 3. 2
`events. contract`	1. x	2. x	Dual-publish avant d'éteindre 'v1'

Exemples de contrats

Événement de bus avec la version :

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 avec la version du contrat :


GET /v2/wallet/balance
X-Contract-Version: 2. 3

Anti-modèles

Changements « silencieux » : changer les types/sens des champs sans MAJEUR et deprecate.

Mélanger la migration de données et la logique de l'argent dans une seule version sans dual-write.

Drapeaux globaux au lieu de versions (impossible de restaurer « ce qui était en vigueur à l'époque »).

Absence de tests contractuels et de catalogue de schémas.

Supprimer legacy sans télémétrie d'utilisation - les partenaires/dashboards sont cassés.

Le numéro unique « quelque part dans le wiki » sans artefacts/signatures n'est pas reproductible.

Chèque de discipline des versions du noyau

Normes

Famille de versions : 'semver', 'schemaVer', 'contractVer', 'calcVer', 'policyVer'.
Catalogue de données/schémas (data catalogue) avec historique et propriétaires.

Contrats

Endpoints/événements versionnés, header/champ de version.
Procédure de deprection avec dates et télémétrie d'utilisation.

Migrations

Expand→Migrate→Contract, dual-write, онлайн-DDL.
Tables shadow et invariants au niveau OBD.

Versions

Rollout canarien, matrice de compatibilité, plan de rollback.
Images signées/migrations, artefacts immuables.

Observability

Balises de version dans la trace/logs/métriques.
Dashboards d'erreur/latence/fin-delta selon les versions.

Conformité/DR

Reproduit par l'élévation de l'environnement "à la date T'.
Logs d'application de policyVer (AML/RG/KYT).

La versionalité du noyau est une « assurance » de l'argent et le rythme de développement du produit. Avec elle, la plate-forme évolue de manière prévisible : de nouvelles opportunités sortent sans panne, la finance reste reproductible, les intégrations sont compatibles, l'audit est calme. Faites en sorte que les versions fassent partie du processus (contrats, migrations, télémétrie, versions) - et votre backend résistera à des années de changements sans perte pour P&L et réputation.