orquestrador/docs/architecture/admin-report-materialization-strategy.md

Estrategia De Materializacao Dos Relatorios Administrativos

Objetivo

Escolher como os relatorios administrativos vao materializar o read model definido para a fase 4.

A decisao precisava fechar quatro alternativas candidatas:

• replica
• ETL
• snapshots
• views dedicadas

Decisao

A fase inicial de relatorios do orquestrador-admin vai usar a seguinte composicao:

1. etl_incremental como mecanismo de sincronizacao
2. snapshot_table no lado administrativo como persistencia de leitura
3. dedicated_view sobre os snapshots como superficie de consulta para APIs e UI
4. nenhuma replica operacional do banco do product para abrir dashboards administrativos

Em resumo:

• nao usar replica como mecanismo primario da fase inicial
• sim usar ETL incremental
• sim persistir snapshots sanitizados
• sim expor views dedicadas sobre esses snapshots

Por que nao comecar por replica

Replica isolaria menos do que parece. Ela ainda manteria o admin muito proximo do schema operacional live, incentivando query ad hoc, joins pesados e acoplamento ao desenho interno do product.

Tambem traria custo operacional cedo demais:

• infraestrutura adicional
• observabilidade de replicacao
• risco de leitura errada por atraso ou schema drift
• falsa sensacao de que qualquer tabela do produto pode virar dashboard

Para a fase inicial, replica aumenta a superficie tecnica sem resolver a necessidade principal, que eh governar exatamente o que sai do produto e como isso chega ao admin.

Por que ETL incremental

ETL incremental encaixa melhor no que ja decidimos para o sistema:

• preserva o hot path do atendimento
• permite sanitizacao e minimizacao antes do dado chegar ao admin
• suporta watermark, cursor e reprocessamento controlado
• facilita auditoria do ciclo de consolidacao
• prepara evolucao futura para jobs, workers ou pipelines por evento

O ETL aqui nao precisa nascer grande. Ele pode comecar como job incremental simples e evoluir sem quebrar o contrato do painel.

Por que snapshots

Snapshots sao a melhor base inicial de persistencia para relatorios administrativos porque:

• congelam um recorte coerente do dataset consolidado
• permitem metadados como generated_at, source_watermark e dataset_version
• reduzem risco de consultas inconsistentes durante sincronizacao
• simplificam retry, backfill e comparacao entre execucoes

Na pratica, os snapshots pertencem ao contexto administrativo, nao ao banco operacional do produto.

Por que views dedicadas

Views dedicadas ficam por cima dos snapshots para desacoplar a UI e as APIs do formato bruto de consolidacao.

Elas permitem:

• esconder colunas tecnicas de ETL
• estabilizar o contrato consumido pelos relatorios
• organizar uma view por caso de uso de negocio
• evoluir agregacoes e joins internos sem quebrar a tela

Regra importante:

• essas views sao dedicadas ao contexto administrativo
• elas nao apontam para tabelas live do produto
• elas leem apenas snapshots ja sanitizados

Fluxo alvo

product operational tables
        |
        v
etl_incremental boundary
        |
        v
admin snapshot tables
        |
        v
admin dedicated views
        |
        v
admin report routes and dashboard

Regras obrigatorias

1. O painel nunca consulta replica ou tabela live do produto durante request web.
2. O ETL incremental so exporta datasets e campos aprovados em contrato compartilhado.
3. Cada snapshot precisa carregar watermark e timestamp de geracao.
4. Cada view dedicada existe para um caso de uso de relatorio, nunca como espelho generico do schema operacional.
5. Escrita administrativa em tabela operacional do produto continua proibida.

Consequencias praticas para a fase 4

Com essa decisao, os proximos itens da fase ficam orientados assim:

• rotas administrativas de relatorio devem ler views dedicadas do admin
• relatorios de vendas, arrecadacao e operacao devem nascer sobre snapshots sanitizados
• a UI deve exibir frescor e estado da ultima consolidacao
• qualquer refresh manual conversa com a camada de sincronizacao, nao com o banco operacional live

Evolucao futura permitida

Se no futuro houver escala suficiente para replica, ela pode entrar como fonte de extra<72><61>o do ETL, e nao como backend direto do dashboard.

Ou seja:

• replica pode aparecer depois como detalhe de implementacao
• o contrato do painel continua o mesmo
• a fronteira principal segue sendo ETL -> snapshots -> views dedicadas