Por qué es importante realizar un seguimiento de las versiones del núcleo de la plataforma

Qué es el «núcleo de la plataforma» y por qué las versiones son críticas

Por «núcleo» se entienden los dominios donde no se perdonan errores: monedero y ledger, apuestas/liquidación de rondas, taquilla (depósitos/pagos), identificación (KYC/AML/RG), contratos con proveedores de juegos y facturación/reporting.

Cualquier actualización aquí afecta el dinero, la regulación, la confianza. Por lo tanto, las versiones del núcleo no son "número en el paquete. json", y una herramienta de gestión del cambio y la responsabilidad.

Por qué realizar un seguimiento de las versiones

1. Gestión del riesgo del dinero. Sabemos claramente qué código se ha calculado en qué ronda/pago: elimina las disputas y acelera la resolución de incidentes.

2. Compatibilidad de integraciones. Los proveedores de juegos/pagos están vinculados a contratos. Versión = garantía de que los campos, los estados y las reglas de negocio coinciden.

3. Cumplimiento y auditoría. El regulador exige la reproducibilidad: «qué build, qué circuito, qué control». La versión es el ancla de la base de pruebas.

4. Lanzamientos rápidos sin downtime. La versionización permite liberar cambios compatibles y enrollar de forma canaria.

5. Gestión de incidentes. Rollback/roll-forward son simples cuando hay artefactos tegiados, migraciones y una matriz de compatibilidad.

6. Transparencia para comandos de productos. Cuando «el contrato es estable a X.Y», los frentes/marketing/analítica planean sin sorpresas.

Directiva de versión (SemVer para kernel)

Usamos SemVer 'MAJOR. MINOR. PATCH '+ «revisión del esquema» y «versión del contrato de eventos»:

PATCH (x.y. Z) - correcciones sin cambiar la API/esquemas/lógica de cálculo. Rollout es rápido, rollback es trivial.
MINOR (x.Y.z) - extensiones compatibles: nuevos campos «nullable», nuevos eventos, banderas. Migraciones «expand-only».
MAJOR (X.y. z) - cambios rompedores: eliminación de campos/eventos, cambio de reglas de cálculo, nuevos invariantes de ledger.

Fijamos adicionalmente:

'schemaVer' (BD/ledger/directorios), 'aproxVer' (eventos de bus y webhooks), 'calcVer' (motor de reglas de cálculo/bonus).

💡 Regla: una dirección en la versión. O «expandimos sin romper» o «rompemos con la sombra». La mezcla es el camino a los incidentes.

Contratos e interoperabilidad inversa

Contratos para consumidores externos e internos

API/webhooks/eventos: versionamos la URL ('/v2/... '), el título (' X-Contract-Version '), el campo' schemaVer 'en la carga útil.

Eventos de bus: campo 'eventVer', denegación de silent-breaking (cambios en el tipo de campo, significado de estado).

DB: migraciones de estilo expand → migrate → contract.

Puede agregar, cambiar - con cuidado, eliminar - con «sombra»

Agregar campos: sólo nullable/c por defecto.

El cambio de sentido es sólo en MAJOR con la publicación paralela del campo «viejo» ('_ legacy') para el período de transición.

La eliminación es después del deprechate y la telemetría «quién más lee lo viejo».

Migraciones de esquemas y datos

Expand: añadir una columna/índice, introducir un nuevo evento - sin tocar los lectores existentes.

Migrar: rellenar/volver a calcular los valores en el fondo (batch/online), incluir la entrada doble (dual-write) en la nueva ubicación.

Contrato: traducir lectores, eliminar legacy-rama en el próximo MAJOR.

Herramientas: migraciones bajo feature-flag, tablas de sombras, DDL en línea, invariantes a nivel DB (check-constraints) y dominio.

Versionar cálculos: dinero, apuestas, bonos

Fija por separado 'calcVer', la versión de la lógica del cálculo monetario (apuesta/hold/settle/VOID, reglas de bonificación y apuesta).

En cada 'round. settled`, `payout. completed`, `bonus. issued' graba 'calcVer'.

En una disputa, se puede reproducir el cálculo con la lógica exacta que estaba vigente en el momento del evento.

Cambiar 'calcVer' hacer canario por porcentaje de tráfico/región/categoría de juegos.

Observabilidad para versionabilidad

Etiquetas en el trais: 'buildId', 'gitSha', 'semver', 'schemaVer', 'aproxVer', 'calcVer' en todos los spans críticos (apuesta, settle, payout).

Dashboards por versiones: errores, latencia, fin delta en el corte de versiones.

Alertas a la «deriva de la versión»: cuando una parte de los consumidores de neumáticos lee el esquema equivocado.

Seguridad y cumplimiento

Los artefactos versionados (imágenes, migraciones) están firmados; se almacenan en un registro/bucket inmutable.

DR/auditoría: se puede levantar el entorno «como estaba en la fecha T» (imagen, migración a la versión, snapshots de la DB).

Las revisiones de las reglas AML/RG/KYT son también versiones (policyVer) y registros de su aplicación.

Procedimientos de lanzamiento

1. Contrato-rugido: lista de cambios marcados con 'PATCH/MINOR/MAJOR', impacto en los consumidores externos/internos.

2. Pruebas de backwards-compat: verificaciones de clientes/eventos antiguos (pruebas de contrato).

3. rollout canario: 1-5% del tráfico; métricas de p95, errores, discrepancias financieras.

4. Telemetría de uso legacy: quién más escucha 'v1', qué campos se leen - plan de deprechate.

5. Paquete Comm: lo que cambia cuando end-of-life de versiones antiguas es cómo migrar.

Matrices de compatibilidad típicas (ejemplo)

Componente	Cliente (min. versión)	Servidor	Estado
`wallet-api`	1. 7	2. 3	OK (MINOR)
`bets-webhook`	1. 4	2. 0	OK, legacy-field 'odds _ legacy' hasta 2026-01-31
`ledger-schema`	–	3. 1	Requiere una migración 'expand' antes de la versión 3. 2
`events. contract`	1. x	2. x	Dual-publish antes de apagar 'v1'

Ejemplos de contratos

Evento de bus con versión:

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"
}

NAT con la versión del contrato:


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

Anti-patterny

Cambios «silenciosos»: cambiar los tipos/significados de los campos sin MAJOR y deprechate.

Mezclar la migración de datos y la lógica del dinero en un solo lanzamiento sin dual-write.

Banderas globales en lugar de versiones (no es posible recuperar «lo que estaba en vigor entonces»).

Falta de pruebas contractuales y catálogo de esquemas.

Eliminar legacy sin telemetría de uso - socios/dashboards se rompen.

Un solo número «en algún lugar de la wiki» sin artefactos/firmas - no es reproducible.

Lista de verificación de la disciplina de versiones del núcleo

Normas

Familia de versiones: 'semver', 'schemaVer', 'contractVer', 'calcVer', 'policyVer'.
Directorio de datos/esquemas (data catalog) con historial y propietarios.

Contratos

Endpoints/eventos versionados, header/campo de versión.
Procedimiento de depreciación con fechas y telemetría de uso.

Migraciones

Expand→Migrate→Contract, dual-write, онлайн-DDL.
Tablas de sombras e invariantes a nivel DB.

Versiones

Rollout canario, matriz de compatibilidad, plan rollback.
Imágenes/migraciones firmadas, artefactos inmutables.

Observability

Etiquetas de versión en trais/logs/métricas.
Dashboards de error/latencia/fin-delta según versiones.

Cumplimiento/DR

Alzamiento reproducible del entorno «en la fecha T».
Registros de aplicación de policyVer (AML/RG/KYT).

La versionalidad del núcleo es el «seguro» del dinero y el ritmo de desarrollo del producto. Con ella, la plataforma evoluciona previsiblemente: las nuevas posibilidades salen sin averías, las finanzas siguen siendo reproducibles, las integraciones - compatibles, las auditorías - tranquilas. Haga que las versiones formen parte del proceso (contratos, migraciones, telemetría, lanzamientos) - y su backend resistirá años de cambios sin pérdidas para P&L y reputación.