Schemi di dati e la loro evoluzione

1) Perché questa piattaforma iGaming

Affidabilità: le modifiche ai dati non compromettono report, API e modelli.
Velocità Fich: aggiungiamo i campi in modo sicuro (KYC/RG/PSP) senza interrompere gli strip.
Regolazione: tracciabilità e riproduzione (audited/lineage, DSAR, Legale Hold).
Il costo è di ridurre al minimo le trasfusioni e i downtime di backfile.

2) Tipi di schemi e dove vivono

Eventi: 'payments. deposit_accepted`, `game. round_finished`.
OLTP/DDL - Tabelle normalizzate (KYC, account, limiti).
DWH/vetrine (Gold): unità denormalizzate sotto BI/ML.
Feature Store: reti fich in linea/offline con garanzia di coerenza.
Contratti di partner esterni: PSP, provider di giochi, fonti di marketing.

Notazioni: Avro/Protobuf, JSON Schema, SQL DDL (DWH), Parket schema (lake).

3) Compatibilità (core dell'evoluzione)

Backward-compatibile - I nuovi produttori utilizzano le vecchie consolle (aggiunti il campo c default/nullable).
Forward-compatibile: i vecchi costruttori stanno nuovi (il nuovo lettore ignora il superfluo).
Full-compatibile: entrambi (obiettivo desiderato per gli eventi).
Breaking-changes - Rinomina o rimuove un campo, cambia tipo/semantica, modifica chiave/partitioning.

Regola 1: gli eventi si evolvono attraverso l'aggiunta, non attraverso la modifica.
Regola 2 - Elimina solo la versione MAGGIORE dello schema dopo il periodo di deprecazione.

4) Versioni e criteri semantici

`MAJOR. MINOR. PATCH'per ogni schema/vetrina/fich set.

MAJOR - incompatibile (nuova topic/tabella/fich set, dual-run).
MINOR - Compatibile (nuovi campi nullable/default, nuovi valori enum).
PATCH - Modifica descrizioni/limiti/commenti.

Il ciclo di vita del campo è 'experimental' active 'deprecated' removed '(data e proprietario).

5) Registro degli schemi e dei contratti dei dati

Schema Registry memorizza versioni, compatibilità, evoluzione e proprietari.
Data Contract: registra lo schema + SLO qualità + privacy (vedere Convalida dati).

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) Pattern migrazioni

6. 1 Eventi (striam)

Additive-only - Aggiungi campi con default/nullable; I vecchi concittadini non si rompono.
Estensioni enum - I nuovi caratteri sono considerati MINOR e i concimatori devono avere un ramo else/unknown.
MIGRAZIONE MAGGIORE: nuova topica'payments. deposit_accepted. v2 ', dual-write, shadow-reads, poi cambio di notebook.

6. 2 DWH/vetrine

Tabelle Blue-Green: 'gold. revenue _ v2 'accanto à v1'; materializziamo, incrociamo, spostiamo la BI.
Backfill: repliche per snap + idempotent merge (chiavi/versioni).
SCD: tipo 2 per attributi che cambiano lentamente (limiti, KYC, stati VIP).

6. 3 Feature Store

Dual-serve: il vecchio fich set viene servito parallelamente al nuovo; il modello viene servito attraverso il router.
Point-in-time coerenza: l'evoluzione non deve rompere i gioielli PITA (timestamp/granularietà invariata a MINOR).

7) Tassonomia modifiche (assegno-foglio)

• aggiunta dì nullable/default ',
• estensione enum (con unknown)
• aggiunta di un indice/commento/descrizione non visibile.

• Cambiare scala/unità (ad esempio, amount in centesimi di → nella valuta principale) solo in MAJOR;
• spostamento della guida/guida attraverso un livello di visualizzazione.

• rinominare o eliminare un campo
• Modifica del tipo/formato/chiave/partition;
• cambio di semantica (ad esempio, «bonus _ amount» da «addebitato» «cancellato»).

8) Schemi Linter e test di compatibilità

Schema-lint: stile dei nomi ('snake _ case'), etichette obbligatorie ('owner', 'doc', 'pii'), formato delle date/valute.
Compat-test - Verifica la nuova versione anti-registro (backward/forward/full).
Consumer-contract-test: ogni servizio fornisce «un esempio di carico utile» e di attesa; Controlliamo l'ICI quando cambiano schema.
Golden-datasets è un insieme di esempi reali e «cattivi» (nuovi enum, campi vuoti/successivi, importi limite).

9) Guide, enum e localizzazione

Reference-data (paesi/valute/PSP/provider): versioni separate e SLA aggiornamenti; Non entrare nel codice degli eventi.
Locale/fuso orario - Memorizza UTC negli eventi + locale esplicito per la presentazione.
Regole di giurisdizione: bandiere per l'età, restrizioni promozionali come manuali con date di validità.

10) Multibrand/Multigiurisdizioni e PII

Isolamento tenante: «brand», «country», «license» - campi obbligatori con enum; Routing su di loro.
Criteri PII a livello di schema: contrassegniamo i campi «pii = true», applichiamo maschere/tornitura; solo token negli eventi.
DSAR: disponibilità dì source _ id/trace _ id 'per l'eliminazione/ricerca; Legale Hold sulle migrazioni MAGGIORI.

11) Versioning DDL e Lake

Migrazioni DDL - Migrazioni dichiarative (Liquibase/Flyway/dbt), archiviazione in VCS, invecchiato dal proprietario del dominio.
Formati in Lake: Avro/Parket - Registriamo l'evoluzione dei campi; MAGGIORE - nuova tabella/percorso '.../v2/'.
Partitioning - Modifica delle partiture (ad esempio «date'→'date,brand») solo tramite MAJOR e doppio record.

12) Esempi di iGaming

12. 1 PSP ha esteso i metodi

Aggiunto "method =" MEFETE "all'enum.
MINOR rilascio schema "deposit _ accetted v1. 8. 0`; I notebook che non conoscono MEFETE inviano un ramo a unknown _ method.

12. 2 Il provider di giochi ha aggiunto campi

W'game. round _ finished 'aggiunto' jackpot _ id '(nullable).
La vetrina gold. game _ rounds _ v3 'riceve MINOR; I vecchi rapporti funzionano, i nuovi contano i jackpot.

12. 3 attributi RG

Passa dallo stato'rg _ state '{none, limit, cooldown, self _ excluded}' a MAGGIORE, nuovo topic + dual-write + migrazione di vetrine e modelli.

13) Processo di evoluzione (dall'idea al cambio)

1. Proposal (ADR): perché cambiare, tipo di compatibilità, valutazione dei rischi e dei consumatori interessati?
2. Design e contratto: schema di registro, semver, criteri di compatibilità.
3. I test sono linters, compat, consumer-contracts, repliche sul golden-set.
4. Installazione: dual-write/blue-green/shadow-reads; Gli alert.
5. Bilanci aziendali/invarianti (vedere Convalida dati).
6. Switch: alterniamo i consumatori/BI/fici.
7. Deprecate: freeze del vecchio schema, grace-perid, rimozione e archivio.

14) Metriche e SLO dell'evoluzione

Success-rate migrazioni, tempo dual-run, percentuale di eventi nuovo formato, volume backfill, lag/freshness.
Incidenti di compatibilità (P1/P2), vetrine di qualità dopo il cambio.
Cost: $/TB trasfusionale, $/ora dual-write, caricamento cluster.
Compliance: 0 fuoriuscite PII, SLA DSAR/Legale Hold sono state rispettate.

15) Strumenti e manufatti

15. 1 Criterio di compatibilità (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 Passaporto migrazione (modello)

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 Nomi e tipi linter (regole)

«snake _ case», UTC timestamps, DECIMAL (18,2) per gli importi, «country» per ISO-3166-1 alpha-2, «currency» per ISO-4217.
Nessun «free _ text» per i campi enum; Le guide sono esterne.

16) Road map di implementazione

0-30 giorni (MVP)

1. Abilita Schema Registry + policy per gli eventi chiave (payments, game _ rounds, user).
2. Linter/test compat in CI; catalogo dei proprietari e recensioni SLA.
3. Modelli ADR e passaporto migrazioni; foglio di assegno MAGGIORE.

30-90 giorni

1. Blue-Green per le vetrine Gold; dual-write per i temi critici.
2. Consumer-contract-test per i servizi di base; golden-datasets.
3. Comprimi e alert digitali automatici durante i cambi; rapporti di costo.

3-6 mesi

1. Un unico processo di deprecate/remove con grace-perid; archiviazione e Legale Hold.
2. Schemi specifici Geo/Tenant e chiavi di crittografia Opzioni DOP per i mercati sensibili.
3. Directory dei campi semantici (data dictionary) e diagrammi lineage vivi.

17) RACI

Data Governance (A/R) - Standard, registro, rigenerazione delle migrazioni, de-pubblicazione.
Domain Owners (R) - Il significato dei campi, le guide, gli invarianti aziendali.
Data Platform (R) - Strumenti di registro, test compat, dual-run/backfill.
Sicurezza/DPO (A/R): Criteri PII, geo/tenant, DSAR/Legale Hold.
SRE/Osservabilità (C): alert, SLO evoluzioni, capacity.
Product/Finance (C) - Convalida KPI, finestre di commutazione.

18) Anti-pattern

Modifica campo in volo senza versione e dual-run.
Rinominare invece di aggiungere un nuovo campo è un guasto di massa.
Un enum rigido senza un ramo «unknown» è una caduta con nuovi valori.
Un'unica guida in codice per tutte le giurisdizioni.
Backfill senza idempotent-merge e bilanci di assegno.
Fogli con PII e senza trace _ id per la ricerca/DSAR.

19) Partizioni correlate

Convalida dei dati, Origine e percorso dei dati, EP, API di analisi e metriche, Verifiche e versioni, Sicurezza dei dati e crittografia, Controllo degli accessi, MLops: utilizzo dei modelli.

Totale

L'evoluzione degli schemi è un processo, non una migrazione singola: registro, versioni e compatibilità dual-run e blue-green invece di «interruttori a mezzanotte»; test di compatibilità e invarianti aziendali invece di buona fortuna. Così i dati restano stabili, i modelli prevedibili, i rapporti corretti e i regolatori calmi.