|
|
# 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
|
|
|
|
|
|
```text
|
|
|
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
|