Esquemas de dados e sua evolução

1) Por que é uma plataforma iGaming

Confiabilidade: alterações de dados não quebram relatórios, API e modelos.
Velocidade Fiech: Adicionamos campos com segurança (KYC/RG/PSP) sem parar striptease.
Regulação: rastreabilidade e reprodução (auditoria/lineagem, DSAR, Legal Hold).
Custo: Minimizamos as «transfusões» e o downthyme dos backphils.

2) Tipos de circuito e onde eles vivem

Eventos: 'payments. deposit_accepted`, `game. round_finished`.
OLTP/PDL: tabelas normalizadas (KYC, contas, limites).
DWH/Vitrines (Gold): Máquinas denormalizadas sob BI/ML.
Função Store: Redes de fich online/offline com garantias de coerência.
Contratos de parceiros externos PSP, provedores de jogos, fontes de marketing.

Notações de Avro/Protobuf, JSON Schema, SQL DDL, Parket schema (lake).

3) Compatibilidade (núcleo da evolução)

Backward-compatível: Novos projetores → consoadores antigos (adicionaram o campo c default/nullable).
Forward-compatível: Os antigos vendedores → novos conceituadores (o novo leitor ignora os demais).
Full-compatível: ambos (destino desejável para eventos).
Breaking-changes: renomear/remover campo, mudar de tipo/semântica, alterar chave/partitioning.

Regra 1: eventos evoluímos por adição, não por alteração.
Regra 2: Remover - apenas na versão MAIOR do esquema após o período de depredação.

4) Versões e políticas semânticas

`MAJOR. MINOR. PATCH 'para cada esquema/vitrine/fich set.

MAJOR - incompatível (nova topic/tabela/fich set, dual-run).
MENOR - compatível (novos campos nullable/default, novos valores enum).
PATCH - Editar descrições/limites/comentários.

O ciclo de vida do campo é 'experimental → ativo → deprecated → removed' (com datas e proprietário).

5) Registro de esquemas e contratos de dados

Schema Registry: armazena versões, compatibilidade, evolução e proprietários.
Data Contract: capta + SLO qualidade + privacidade (consulte Validação de dados).

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) Patternos de migração

6. 1 Eventos (striptease)

Adificável-only: Adicione campos com default/nullable; os velhos consórcios não quebram.
Extensões enum: novos símbolos são considerados MINOR e os consoadores são obrigados a ter um ramo 'else/unknown'.
Migração MAJOR: novo topic 'payments. deposit_accepted. v2 ', dual-write, shadow-reads, depois alterna os consoadores.

6. 2 DWH/vitrines

Tabelas Blue-Green: 'gold. revenue _ v2 'ao lado de' v1 '; materializamos, cruzamos, alteramos o BI.
Backfill: réplicas por snapshot + idempotent merge (chaves/versões).
SCD: tipo 2 para atributos que mudam lentamente (limites, KYC, status VIP).

6. 3 Feature Store

Dual-serve: O antigo fich set é servido paralelamente ao novo; O modelo é mantido através de um roteador.
Coerência point-in-time: a evolução não deve quebrar os joynos PITA (timestamp/granulosidade inalterada em MENOR).

7) Mudança taxonomia (folha de cheque)

• adicionar 'nullable/default' ao campo;
• extensão enum (com 'unknown' - ramo no consumidor);
• adição de índice/comentário/descrição fora da luz.

• mudança de escala/unidade (por exemplo, amount em centavos de → na moeda principal) - apenas em MAJOR;
• transferência de guia/árbitro - através de uma camada de representação.

• renomear ou remover um campo;
• alterar o tipo/formato/chave/partition;
• mudança de semântica (por exemplo, «bônus _ amount» de «atribuído» → «descartado»).

8) Liners de circuito e testes de compatibilidade

Schema-lint: estilo de nome ('snake _ case'), rótulos obrigatórios ('owner', 'doc', 'pii'), formato de data/moeda.
Compat-testes: Verificando a nova versão contra o registro (backward/forward/full).
Consumer-contracto-testes: cada serviço fornece um «exemplo de carga útil» e expectativa; Vamos para a CI quando mudarmos de esquema.
Golden-datasets: conjunto de exemplos reais e «maléficos» (novos enum, campos vazios/tardios, valores de soma limite).

9) Guias, enum e localização

Reference-data (países/moedas/PSP/provedores): versões individuais e atualizações SLA; Não entrar no código de eventos.
Local/fuso horário: armazene UTC em eventos + local explícito para apresentação.
Regras de jurisdição: bandeiras de idade, restrições de promoção - como guias com datas de validade.

10) Multiplicidade/Multiplicagem e PII

Confinamento tenante: 'brand', 'country', 'license' - campos obrigatórios com enum; Routing por eles.
Política PII ao nível do esquema: marcando os campos 'pii = true', aplicando máscaras/torneamento; nos eventos, apenas os tokens.
DSAR: disponibilidade de 'fonte _ id/trace _ id' para remover/pesquisar; Legal Hold nas migrações MAJOR.

11) Versionização de DDL e Lake

Migrações DDL: migrações declaratórias (Liquibase/Flyway/dbt), armazenamento em VCS, revezamento pelo dono do domínio.
Formatos em Lake: Avro/Parquet - Registramos a evolução dos campos; O MAJOR é uma nova tabela/caminho '.../v2/'.
Partitioning: alteração de partituras (por exemplo, 'date'→'date,brand') - somente através do MAJOR e de uma gravação dupla.

12) Exemplos de iGaming

12. 1 PSP expandiu métodos

Adicionado 'method =' MEFETE 'ao enum.
MENOR lança o esquema 'deposit _ aceited v1. 8. 0`; os consórcios que não conhecem o MEFETE enviam para o ramo 'unknown _ method'.

12. 2 Provedor de jogos adicionou campos

No 'game. round _ finished 'adicionado' jackpot _ id '(nullable).
Vitrine 'gold. game _ rounds _ v3 'recebe MINOR; os relatórios antigos funcionam, os novos contam jackpots.

12. atributos RG 3

Vai de «self _ excluded» para «rg _ state» para «state _ state» «∈\none, limit, cooldown, self _ excluded)» - MAJOR, novo topic + dual-write + migração de vitrines e modelos.

13) Processo de evolução (da ideia à mudança)

1. Proposal (ADR): porquê mudar, tipo de compatibilidade, avaliação de risco e consumidores afetados.
2. Design e contrato: esquema de registro, semver, política de compatibilidade.
3. Testes: linters, compat, consumer-contracts, réplicas em golden-sets.
4. Implantação: dual-write/blue-green/shadow-reads; Alertas.
5. Cruzamento: balanços de negócios/invariantes (consulte Validação de dados).
6. Switch: Alterna os consumers/BI/ficci.
7. Deprecate: freeze padrão antigo, grace-period, remoção e arquivo.

14) Métricas e SLO da evolução

Sucess-rate migrações, tempo dual-run, proporção de eventos do novo formato, volume de backfill, lag/freshness.
Incidentes de compatibilidade (P1/P2), vitrines de qualidade após a mudança.
Costa: $/TB transfusão, $/hora dual-write, download do cluster.
Compliance: 0 vazamentos PII, SLA DSAR/Legal Hold cumprido.

15) Ferramentas e artefactos

15. 1 Política de compatibilidade (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 Passaporte de migração (modelo)

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 Nomes e tipos linter (regras)

'snake _ case', UTC timestams, DECIMAL (18,2) para somas, 'country' por ISO-3166-1 alpha-2, 'currency' por ISO-4217.
Nenhum 'free _ text' para campos enum; os guias são externos.

16) Mapa de trânsito de implementação

0-30 dias (MVP)

1. Incluir Schema Registry + policy compatibilidade para eventos-chave (payments, game _ rounds, user).
2. Linter/testes compat em CI; catálogo de proprietários e resenhas SLA.
3. Modelos ADR e passaporte de migração; folha de cheque MAJOR.

30 a 90 dias

1. Blue-Green para vitrines Gold; dual-write para temas críticos.
2. Consumer-contracto-testes para serviços básicos; golden-datasets.
3. Comprimidos e alertas de ajuste automáticos; relatórios de valor.

3-6 meses

1. Um único processo de deprecate/remove com grace-period; arquivamento e Legal Hold.
2. Geo/tenante-circuitos específicos e chaves de criptografia; Opções DP para mercados sensíveis.
3. Catálogo de semântica de campos (data dictionary) e diagramas lineage ao vivo.

17) RACI

Data Governance (A/R): padrões, registro, registo das migrações, de-publicação.
Domain Owners (R): sentido campos, guias, invariantes de negócios.
Data Platford (R): ferramentas de registro, testes compat, dual-run/backfill.
Segurança/DPO (A/R): Políticas PII, geo/tenant, DSAR/Legal Hold.
SRE/Observabilidade (C): alerts, SLO evolução, capacidade.
Produt/Finance (C): validação do KPI, janelas de mudança.

18) Anti-pattern

«Ajustando o campo de voo» sem versões ou dual-run.
Renomear em vez de adicionar um novo campo → falhas em massa.
Enum rígido sem o ramo 'unknown' → queda em novos valores.
Um guia único de código para todas as jurisdições.
Backphill sem idempotent-merge e balanços de cheque.
Logs com PII e sem trace _ id para pesquisa/DSAR.

19) Seções relacionadas

Validação de dados, Origem e Caminho de dados, Práticas de Ops, API Analistas e Métricas, Auditoria e Versões, Segurança de Dados e Criptografia, Controle de Acesso, MLOs: Operação de modelos.

Resultado

A evolução dos esquemas é um processo, não uma migração única: registro, versões e compatibilidade; dual-run e blue-green em vez de «alternadores à meia-noite»; testes de compatibilidade e invariantes de negócios em vez de boa sorte. Assim, os dados permanecem estáveis, os modelos previsíveis, os relatórios corretos e os reguladores calmos.