Como Funciona

Em uma frase

Todo dia, o sistema entra nos bancos de cada cliente, mede o consumo de cada métrica
configurada, guarda o resultado e manda para a API de billing externa.

As 4 etapas

1. Coletar (Ingestion)

Para cada Operation (cliente) ativa, o job de ingestão conecta na réplica do banco
daquele cliente e copia as linhas do dia para o banco analítico interno — uma
"fotografia" do que aconteceu naquele dia. Essa etapa roda em paralelo para todas as
Operations, para não esperar um cliente terminar antes de começar o próximo.

2. Consolidar (Consolidation)

Para cada Operation, o job de consolidação roda cada License (um template SQL
nomeado, ex.: "mensagens SMS enviadas no dia") sobre os dados coletados na etapa
anterior, e grava um registro de Consumption: quantidade, operação, licença e dia.

3. Sincronizar (Sync)

O job de sincronização varre os registros de Consumption ainda não enviados e os manda
em lotes para a API de billing externa. Falhas transitórias são reprocessadas
automaticamente; depois de um número máximo de tentativas, o registro vira
dead-letter e passa a exigir ação manual (reenfileirar).

4. Gerenciar

Todo o resto — cadastro de Operations, Licenses, Packages, Instances, disparo manual
de jobs, relatórios — é feito pela UI Angular interna, que fala com a API interna
(/api/**).

Diagrama (alto nível)

 Bancos dos clientes (réplicas)
        │
        ▼
 ┌───────────────┐     ┌───────────────────┐     ┌─────────────┐
 │  Coletar      │ ──▶ │  Consolidar       │ ──▶ │  Sincronizar│──▶ API de billing externa
 │  (Ingestion)  │     │  (roda Licenses)  │     │  (Sync)     │    (calcula preço, fatura)
 └───────────────┘     └───────────────────┘     └─────────────┘
        │                        │                       │
        └────────────────────────┴───────────────────────┘
                    Banco analítico (MySQL)
                registros append-only, nunca sobrescritos

Um princípio importante: append-only

Registros de consumo nunca são alterados (UPDATE) depois de gravados. Se um
número precisa ser corrigido, é inserido um novo registro e o antigo é marcado
como substituído — nunca apagado. Isso garante rastreabilidade total: dá pra saber
exatamente o que foi enviado para o billing e quando, mesmo depois de uma correção.

Como o sistema é disponibilizado

Roda como um único artefato (JAR) — backend Spring Boot com o frontend Angular
empacotado junto — acessível apenas via VPN interna, nunca exposto publicamente.

Ver também: Glossário de Domínio · Decisões de Arquitetura