Esquemas de datos y su evolución

1) Por qué es una plataforma iGaming

Fiabilidad: los cambios en los datos no rompen los informes, las API y los modelos.
Velocidad fich: agregamos campos con seguridad (KYC/RG/PSP) sin detener los streams.
Regulación: trazabilidad y reproducibilidad (audit/lineage, DSAR, Legal Hold).
Costo: minimizamos los «desbordamientos» y el downtime de las backfills.

2) Tipos de esquemas y dónde viven

Eventos (streams): 'payments. deposit_accepted`, `game. round_finished`.
OLTP/DDL: tablas normalizadas (KYC, cuentas, límites).
DWH/vitrinas (Oro): unidades desnormalizadas bajo BI/ML.
Feature Store: juegos de fichas online/offline con garantías de coherencia.
Contratos de socios externos: PSP, proveedores de juegos, fuentes de marketing.

Notaciones: Avro/Protobuf (streams), JSON Schema (integraciones), SQL DDL (DWH), Parquet schema (lago).

3) Compatibilidad (núcleo de evolución)

Backward-compatible: nuevos productores → antiguos consumidores (añadido campo c predeterminado/nullable).
Forward-compatible: viejas productoras → nuevos consumidores (el nuevo lector ignora lo superfluo).
Full-compatible: ambos (objetivo deseable para eventos).
Breaking-changes: cambio de nombre/borrado de campo, cambio de tipo/semántica, cambio de clave/partitioning.

Regla 1: los eventos evolucionan a través de la adición, no a través del cambio.
Regla 2: eliminar - sólo en la versión MAJOR del esquema después del período de deprechate.

4) Versiones semánticas y políticas

`MAJOR. MINOR. PATCH 'para cada circuito/escaparate/set de fichas.

MAJOR - Incompatible (nuevo topic/table/fich set, dual-run).
MINOR - compatible (nuevos campos nullable/default, nuevos valores enum).
PATCH - Editar descripciones/límites/comentarios.

Ciclo de vida del campo: 'experimental → active → deprecated → removed' (con fechas y propietario).

5) Registro de esquemas y contratos de datos

Registro Schema: almacena versiones, compatibilidad, evolución y propietarios.
Contrato de datos: captura el esquema + calidad SLO + privacidad (ver «Validación de datos»).

json
{
"type":"record","name":"deposit_accepted","namespace":"payments",
"fields":[
{"name":"event_id","type":"string"},
{"name":"occurred_at","type":{"type":"long","logicalType":"timestamp-micros"}},
{"name":"user_id","type":"string"},
{"name":"brand","type":"string"},
{"name":"country","type":"string"},
{"name":"psp","type":"string"},
{"name":"method","type":"string"},
{"name":"amount","type":{"type":"bytes","logicalType":"decimal","precision":18,"scale":2}},
{"name":"currency","type":{"type":"enum","name":"Currency","symbols":["EUR","USD","TRY","BRL"]}},
{"name":"risk_score","type":["null","int"],"default":null},       // MINOR+
{"name":"kyc_level","type":["null",{"type":"enum","name":"Kyc","symbols":["L0","L1","L2","L3"]}],"default":null}
],
"compatibility":"FULL","owner":"team-payments"
}

6) Patrones de migración

6. 1 Eventos (streams)

Additive-only: agregamos campos con default/nullable; los viejos consumidores no se rompen.
Enum-extensiones: los nuevos caracteres son considerados MINOR, los consumers están obligados a tener una rama 'else/unknown'.
Migración MAJOR: nuevos pagos topic. deposit_accepted. v2 ', dual-write, shadow-reads, luego switching consumers.

6. 2 DWH/escaparates

Tablas Azul-Verde: 'oro. revenue_v2' junto a 'v1'; materializamos, probamos, cambiamos BI.
Backfill: relay por snapshots + idempotent merge (por llaves/versiones).
SCD: tipo 2 para atributos de cambio lento (límites, KYC, estados VIP).

6. 3 Feature Store

Dual-serve: el viejo set de fichas se mantiene paralelo al nuevo; el modelo se mantiene a través de un router.
Coherencia punto-en-tiempo: la evolución no debe romper las joyas PITA (timestamp/granularidad sin cambios en MINOR).

7) Taxonomía de cambios (lista de verificación)

• agregar 'nullable/default' del campo;
• extensión enum (con la rama 'unknown' en el consumidor);
• agregar un índice/comentario/descripciones no clave.

• cambio de escala/unidades (por ejemplo, amount en centavos → en la moneda principal) - sólo en MAJOR;
• transferencia de referencia/referencia - a través de la capa de representación.

• cambiar el nombre/eliminar el campo;
• cambiar el tipo/formato/clave/partition;
• cambio de semántica (por ejemplo, 'bonus _ amount' de 'cargado' → 'cargado').

8) Linters de circuitos y pruebas de compatibilidad

Schema-lint: estilo de nombre ('snake _ case'), etiquetas obligatorias ('owner', 'doc', 'pii'), formato de fecha/moneda.
Compat-tests: verificamos la nueva versión contra el registro (backward/forward/full).
Consumer-contract-tests: cada servicio suministra un «ejemplo de carga útil» y espera; corremos a CI cuando cambie el circuito.
Golden-datasets: conjunto de ejemplos reales y «malignos» (nuevos enum, campos vacíos/tardíos, valores límite de sumas).

9) Manuales, enum y localización

Referencia-datos (países/monedas/PSP/proveedores): versiones separadas y actualizaciones SLA; no coser en el código de eventos.
Zona horaria/local: almacenar UTC en eventos + local explícito para la presentación.
Reglas de las jurisdicciones: banderas de edad, restricciones promocionales - en forma de guías con fechas de validez.

10) Multimarca/Multidisciplinar y PII

Aislamiento tenante: 'brand', 'country', 'license' son campos obligatorios con enum; routing por ellos.
Política PII a nivel de esquema: marcamos los campos 'pii = true', aplicamos máscaras/tokenización; en eventos - sólo tokens.
DSAR: tener 'source _ id/trace _ id' para eliminar/buscar; Legal Hold en migraciones MAJOR.

11) Versionar DDL y Lake

Migraciones DDL: migraciones declarativas (Liquibase/Flyway/dbt), almacenamiento en VCS, rugido por el propietario del dominio.
Formatos en Lake: Avro/Parquet - Registramos la evolución de los campos; con MAJOR es la nueva tabla/ruta '.../v2/'.
Partitioning: cambio de lotes (por ejemplo, 'date'→'date,brand') - sólo a través de MAJOR y doble registro.

12) Ejemplos de iGaming

12. 1 PSP amplió métodos

Añadido 'method = «MEFETE»' al enum.
Versión MINOR del diagrama 'deposits _ accepted v1. 8. 0`; los consumidores que no conocen MEFETE envían una rama a 'unknown _ method'.

12. 2 Proveedor de juegos agregó campos

En 'game. round_finished' ha añadido 'jackpot _ id' (nullable).
Escaparate de oro. game_rounds_v3' recibe MINOR; los informes antiguos funcionan, los nuevos cuentan jackpots.

12. 3 atributos RG

Transición de booleano 'self _ excluded' a status 'rg _ state ∈ {none, limit, cooldown, self_excluded}' - MAJOR, nuevo topic + dual-write + migración de escaparates y modelos.

13) Proceso de evolución (desde la idea hasta el cambio)

1. Proposal (ADR): por qué cambiamos, el tipo de interoperabilidad, la evaluación del riesgo y los consumidores afectados.
2. Diseño y contrato: esquema en el registro, semver, política de compatibilidad.
3. Pruebas: linters, compat, consumer-contracts, replay en sets de oro.
4. Implementación: dual-write/blue-green/shadow-reads; alertas.
5. Conciliación: balances comerciales/invariantes (ver «Validación de datos»).
6. Switch: cambiamos los consumers/BI/fiches.
7. Deprecate: freeze del esquema antiguo, grace-period, borrar y archivar.

14) Métricas y SLO de la evolución

Tasa de éxito de las migraciones, tiempo de ejecución dual, proporción de eventos de nuevo formato, volumen de backfill, lag/freshness.
Incidentes de compatibilidad (P1/P2), calidad del escaparate después del cambio.
Costo: $/TB desbordamiento, $/hora dual-escritura, descarga del clúster.
Compliance: 0 PII fugas, SLA DSAR/Legal Hold se cumplen.

15) Herramientas y artefactos

15. 1 Política de compatibilidad (registro)

yaml schema: payments. deposit_accepted compatibility: FULL default_nulls: true enums:
currency: {allow_new_symbols: true, require_consumer_unknown_branch: true}
pii: false owners: ["team-payments"]
reviewers: ["data-governance","security-dpo"]

15. 2 Pasaporte de migración (plantilla)

yaml change_id: MIG-2025-041 scope: game. round_finished -> v3 type: MAJOR plan:
dual_write: true shadow_reads: consumers: ["gold-rounds","rg-models"]
backfill: {from: "2025-01-01", mode: "idempotent-merge"}
validation:
invariants: ["sum_bets = sum_wins + margin + bonuses"]
freshness_delta_p95_max: "PT5M"
switch_criteria:
error_rate_max: 0. 1%
kpi_diff_pp_max: 0. 5 deprecate_after: "2025-12-31"

15. 3 Linter de nombres y tipos (reglas)

'snake _ case', tiempos UTC, DECIMAL (18,2) por sumas, 'country' por ISO-3166-1 alpha-2, 'currency' por ISO-4217.
Sin 'free _ text' para campos enum; Los manuales son externos.

16) Hoja de ruta para la implementación

0-30 días (MVP)

1. Habilitar la compatibilidad de Schema Registry + policy para eventos clave (payments, game_rounds, user).
2. Pruebas de linterna/compat en CI; Catálogo de propietarios y reseñas de SLA.
3. Plantillas de ADR y pasaporte de migración; lista de verificación MAJOR.

30-90 días

1. Azul-Verde para escaparates de oro; dual-write para temas críticos.
2. Consumer-contract-tests para servicios básicos; golden-datasets.
3. Conciliaciones y alertas de diff automáticas durante los cambios; informes de valor.

3-6 meses

1. Un único proceso de deprecate/remove con grace-period; archiving y Legal Hold.
2. Circuitos geo/tenant específicos y claves de cifrado; Opciones DP para mercados sensibles.
3. Directorio de semántica de campos (data dictionary) y diagramas de lineage en vivo.

17) RACI

Data Governance (A/R): normas, registro, rugido de migraciones, de publicación.
Domain Owners (R): significado de los campos, guías, invariantes de negocios.
Plataforma de datos (R): herramientas de registro, pruebas compat, dual-run/backfills.
Seguridad/DPO (A/R): Políticas PII, geo/tenant, DSAR/Legal Hold.
SRE/Observabilidad (C): alertas, SLO de las evoluciones, capacity.
Producto/Finanzas (C): validación de KPI, ventanas de conmutación.

18) Anti-patrones

«Editar el campo sobre la marcha» sin versiones y dual-run.
Cambiar el nombre en lugar de agregar un nuevo campo → roturas masivas.
Enum rígido sin rama 'unknown' → caídas en los nuevos valores.
Manual único «en código» para todas las jurisdicciones.
Backfill sin idempotent-merge y balances de cheque.
Registros con PII y sin trace_id para buscar/DSAR.

19) Secciones relacionadas

Validación de datos, Origen y ruta de datos, Prácticas de DataOps, API de análisis y métricas, Auditoría y versionabilidad, Seguridad de datos y cifrado, Control de acceso, MLOps: explotación de modelos.

Resultado

La evolución de los esquemas es un proceso, no una migración única: registro, versiones y compatibilidad; dual-run y blue-green en lugar de «interruptores a medianoche»; pruebas de compatibilidad e invariantes empresariales en lugar de suerte. Así que los datos se mantienen estables, los modelos son predecibles, los informes son correctos y los reguladores están tranquilos.