Por que é importante monitorar versões do núcleo da plataforma

O que é «núcleo de plataforma» e por que as versões são críticas

Por «núcleo», compreendemos os domínios onde os erros não são perdoados: carteira e candeeiro, apostas/pagamentos de rodadas, caixa (depósitos/pagamentos), identificação (KYC/AML/RG), contratos com provedores de jogos e bilhete/relatório.

Qualquer atualização aqui afeta dinheiro, regulação, confiança. Por isso, as versões do núcleo não são "número no pacote. json", mas uma ferramenta de controle de mudanças e responsabilidade.

Por que monitorar versões

1. Gerenciamento de risco de dinheiro. Sabemos bem qual código foi calculado para a rodada/pagamento. Alivia as discussões e acelera os casos.

2. Compatibilidade de integração. Provedores de jogos/pagamentos estão amarrados em contratos. Versão = garante que campos, estatais e regras de negócios coincidem.

3. Complacência e auditoria. O regulador requer reprodutividade: «que build, que esquema, que controle». A versão é a âncora da base de provas.

4. Lançamentos rápidos sem downthame. A versionização permite que você produza alterações compatíveis e espalhe canhotos.

5. Gerenciamento de incidentes. Rollback/roll-forward é simples quando há artefatos tingidos, migração e matriz de compatibilidade.

6. Transparência para comandos de alimentos. Quando «contrato está estável para X.Y», frentes/marketing/analista planejam sem surpresas.

Política de versão (SemVer para núcleo)

Usamos «MAJOR». MINOR. PATCH '+ «revisão do esquema» e «versão do contrato de eventos»:

PATCH (x.y. Z) - correções sem alteração de API/padrão/lógica de cálculo. Rollout é rápido, rollback é trivial.
MENOR (x.Y.z) - Extensões compatíveis: novos campos «nullable», novos eventos, bandeiras. Migração «expand-only».
MAJOR (X.y. z) - Alterações de quebra: remoção de campos/eventos, alteração de regras de cálculo, novos invariantes.

Adicionalmente, registramos:

«schemaVer» (BD/ledger/diretório), «contractVer» (eventos de pneus e webhooks), «calcVer» (motor de cálculo/regras de bónus).

💡 Regra: uma direção no lançamento. Ou «expandir sem quebrar» ou «quebrar com sombra». A mistura é o caminho para os incidentes.

Contratos e compatibilidade invertida

Contratos para consumidores externos e internos

API/webhooks/eventos: versionando URL ('/v2/... '), cabeçalho (' X-Contracto-Versão '), campo' schemaVer 'em carga útil.

Eventos no pneu: campo 'eventVer', proibição de silent-breaking (alterações no tipo de campo, sentido de estado).

BD: Migração expand → migrate → contract.

Você pode adicionar, alterar com cuidado, remover com «sombra»

Adição de campos - somente nullable/c default.

A mudança de sentido é apenas o MAIOR, com a publicação paralela do «antigo» campo ('_ legacy') para o período de transição.

Remoção após depredação e telemetria «quem mais lê o antigo».

Migração de circuitos e dados

Expand: adicionar coluna/índice, digitar um novo evento - sem tocar nos leitores existentes.

Migrate: preencha/repasse os valores no fundo (batch/online) e inclua uma entrada dupla (dual-write) em um novo local.

Contract: Traduzir os leitores, remover o ramo legacy no próximo MAJOR.

Ferramentas: migrações de função-flag, tabelas shadow, DDL on-line, invariantes em nível BD (check-constraits) e domínio.

Versioning de contas: dinheiro, apostas, bónus

Registre separadamente 'calcVer' - uma versão da lógica do dinheiro (taxa/hold/setle/VOID, regras de bônus e saques).

Todos os 'round. settled`, `payout. completed`, `bonus. issued 'anote' calcVer '.

Na discussão, você pode reproduzir o cálculo exatamente com a lógica que operava no momento do evento.

Comutar 'calcVer' faça canarinho sobre a porcentagem de tráfego/região/categoria de jogos.

Observabilidade para versões

Tags em «buildId», «gitSha», «semver», «schemaVer», «contractVer», «calcVer» em todos os spans críticos (aposta, setle, payout).

Dashboards em versões, erros, latência, fins-delta em versões.

Alertas à deriva de versões, quando alguns consumidores de pneus lêem o padrão errado.

Segurança e Complacência

Artefatos versionizados (imagens, migrações) assinados; armazenados em registry/bucket inalterável.

Dr./auditoria: você pode levantar o ambiente «como estava na data T» (imagem, migração para versão, BD).

As revisões das regras AML/RG/KYT são versões (policyVer) e logs de aplicação.

Procedimentos de lançamento

1. Contrato-revezamento: lista de alterações marcadas como 'PATCH/MENOR/MAJOR', afetando os consumidores externos/internos.

2. Testes Backwards-compat: verificações em clientes/eventos antigos (testes contratuais).

3. Rollout canário: 1% a 5% do tráfego; métricas de p95, erros, divergências financeiras.

4. Telemetria de uso de legacy: Quem mais ouve 'v1', que campos são lidos - o plano de depredação.

5. Pacote de Kombi: O que muda quando o end-of-life das versões antigas como migrar.

Matrizes de compatibilidade típicas (exemplo)

Componente	Cliente (versão min)	Servidor	Estado
`wallet-api`	1. 7	2. 3	OK (MINOR)
`bets-webhook`	1. 4	2. 0	OK, legacy-campo 'odds _ legacy' até 2026-01-31
`ledger-schema`	–	3. 1	Requer migração 'expand' antes do lançamento 3. 2
`events. contract`	1. x	2. x	Dual-publish antes de desligar 'v1'

Exemplos de contratos

Evento de pneu com versão:

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

RESTC com a versão do contrato:


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

Anti-pattern

Alterações silenciosas: altere os tipos/significados de campos sem o MAJOR e o deprezado.

Misturar migração de dados e lógica de dinheiro em um único lançamento sem dual-write.

Bandeiras globais em vez de versões (não é possível restaurar «o que estava em vigor»).

Nenhum teste de contrato ou catálogo de esquema.

Remover legacy sem telemetria de uso - os parceiros/dashboards são quebrados.

Não é reproduzido um número único «em algum lugar wiki» sem artefatos ou assinaturas.

Folha de cheque da disciplina de versão do núcleo

Padrões

Família de versões: 'semver', 'schemaVer', 'contractVer', 'calcVer', 'policyVer'.
Diretório de dados/diagramas (data catalog) com histórico e proprietários.

Contratos

Endpoints/eventos versionizados, header/campo de versão.
Procedimento Deprecation com datas e telemetria de uso.

Migração

Expand→Migrate→Contract, dual-write, онлайн-DDL.
Tabelas shadow e invariantes em nível BD.

Lançamentos

Rollout canário, matriz de compatibilidade, plano rollback.
Imagens/migrações assinadas, artefatos imutáveis.

Observability

Marcas de formatação em trens/logs/métricas.
Dashboards de erro/latência/finn-delta em versões.

Complaens/DR

Elevação de ambiente reproduzida «na data T».
Logs de aplicação de policyVer (AML/RG/KYT).

A versão do núcleo é o «seguro» do dinheiro e o ritmo de desenvolvimento do produto. Com ela, a plataforma evolui previsivelmente, com novas oportunidades saindo sem falhas, as finanças permanecendo reproduzíveis, as integrações compatíveis, e as auditorias, calmas. Tornar as versões parte do processo (contratos, migrações, telemetria, lançamentos) - e seu backend aguenta anos de mudanças sem perdas para P&L e reputação.