You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
155 lines
5.3 KiB
Markdown
155 lines
5.3 KiB
Markdown
# Estrategia De Leitura De Relatorios Sem Acoplar O Hot Path
|
|
|
|
## Objetivo
|
|
|
|
Definir como o `orquestrador-admin` deve ler dados operacionais para relatorios sem transformar o `orquestrador-product` em backend sincrono de dashboard.
|
|
|
|
Esta etapa fixa a **topologia de leitura**.
|
|
A materializacao concreta dessa topologia foi definida em `docs/architecture/admin-report-materialization-strategy.md`.
|
|
|
|
## Decisao
|
|
|
|
Os relatorios administrativos devem ser servidos a partir de um **read model administrativo assincrono**.
|
|
|
|
Em outras palavras:
|
|
|
|
1. O `product` continua escrevendo o estado operacional primario.
|
|
2. Uma camada de sincronizacao fora do hot path materializa dados de leitura para relatorio.
|
|
3. O `admin` consulta apenas esse read model, nunca as tabelas operacionais live do `product` em uma request web do painel.
|
|
|
|
## Topologia alvo
|
|
|
|
```text
|
|
product operational writes
|
|
|
|
|
v
|
|
sync/export boundary outside hot path
|
|
|
|
|
v
|
|
admin reporting read model
|
|
|
|
|
v
|
|
admin report APIs and dashboard
|
|
```
|
|
|
|
## Regras obrigatorias
|
|
|
|
### 1. Sem query direta do painel no banco operacional do produto
|
|
|
|
Nao e permitido que uma rota web do painel administrativo execute consultas pesadas ou agregacoes diretamente nas tabelas operacionais do `product`.
|
|
|
|
Isso inclui:
|
|
|
|
- scans amplos em `orders`, `rental_contracts`, `rental_payments`, `conversation_turns`
|
|
- joins ad hoc para dashboard em tempo de request
|
|
- leituras que disputem lock, cache ou I/O com o atendimento
|
|
|
|
### 2. Leitura eventual, nao transacional
|
|
|
|
O painel administrativo deve operar com **consistencia eventual**.
|
|
|
|
Consequencia pratica:
|
|
|
|
- relatorios mostram o dado consolidado mais recente disponivel
|
|
- a UI deve exibir metadados de frescor, como `updated_at`, `generated_at` ou `source_watermark`
|
|
- o sistema nao promete refletir cada evento operacional no mesmo instante em que ele acontece
|
|
|
|
### 3. Materializacao fora do hot path
|
|
|
|
Toda consolidacao, enriquecimento, agregacao ou recorte temporal deve acontecer em processo assincrono.
|
|
|
|
Exemplos validos de processo assincrono:
|
|
|
|
- job agendado
|
|
- worker orientado a eventos
|
|
- pipeline incremental por cursor
|
|
- rotina batch com watermark
|
|
|
|
### 4. Read model proprio do admin
|
|
|
|
O `admin` deve ter sua propria superficie de leitura para relatorios.
|
|
|
|
Essa superficie pode morar:
|
|
|
|
- no banco administrativo
|
|
- em um schema analitico separado
|
|
- em tabelas materializadas especificas para relatorio
|
|
|
|
O importante nesta etapa nao e o lugar fisico, e sim a regra:
|
|
|
|
- a query do painel le um read model pronto
|
|
- a transformacao do dado acontece antes da request do usuario interno
|
|
|
|
### 5. Escrita administrativa continua proibida
|
|
|
|
A estrategia de leitura nao muda a fronteira de escrita.
|
|
|
|
Portanto:
|
|
|
|
- o `admin` nao escreve diretamente nas tabelas operacionais do `product`
|
|
- qualquer acao de governanca que altere operacao deve seguir fluxo proprio, versionado e auditavel
|
|
|
|
## Responsabilidades por servico
|
|
|
|
### `orquestrador-product`
|
|
|
|
Responsavel por:
|
|
|
|
- persistir o estado operacional primario
|
|
- manter ids tecnicos, timestamps e chaves publicas necessarias para reconciliacao
|
|
- expor uma fronteira segura para exportacao ou sincronizacao
|
|
- continuar respondendo ao atendimento sem depender do `admin`
|
|
|
|
### `orquestrador-admin`
|
|
|
|
Responsavel por:
|
|
|
|
- armazenar ou consultar o read model de relatorio
|
|
- servir rotas administrativas de relatorio
|
|
- informar frescor e origem do dado para a UI
|
|
- aplicar filtros e agregacoes sobre a superficie de leitura consolidada
|
|
|
|
## O que a UI deve assumir
|
|
|
|
As telas administrativas de relatorio devem nascer com a expectativa de dado consolidado e nao de espelho instantaneo do operacional.
|
|
|
|
Consequencia pratica:
|
|
|
|
- cada relatorio deve carregar carimbo de atualizacao
|
|
- um refresh manual dispara no maximo uma rotina de sincronizacao, nunca uma query pesada live no produto
|
|
- empty states e avisos de defasagem fazem parte do contrato visual
|
|
|
|
## Padrao de frescor inicial
|
|
|
|
Enquanto a implementacao completa nao chega, os datasets operacionais ficam classificados em metas de frescor no contrato compartilhado:
|
|
|
|
- `near_real_time` para vendas, revisoes e locacao
|
|
- `intra_hour` para estoque, telemetria e entregas de integracao
|
|
|
|
Essas metas servem para orientar UX, monitoracao e futuras implementacoes da sincronizacao.
|
|
Elas nao significam leitura live do banco operacional.
|
|
|
|
## O que fica explicitamente proibido
|
|
|
|
- dashboard administrativo consultando `product` por HTTP sincrono a cada abertura de pagina
|
|
- admin executando agregacao pesada em banco primario de atendimento durante request web
|
|
- relatorios dependendo de lock em tabela operacional para responder ao usuario interno
|
|
- uso de payload bruto e PII fora do contrato compartilhado de dados operacionais
|
|
|
|
## Consequencias positivas
|
|
|
|
- protege latencia do atendimento
|
|
- reduz risco de regressao operacional por carga analitica
|
|
- permite evoluir relatorios com independencia do runtime conversacional
|
|
- facilita observabilidade de frescor e falha da sincronizacao
|
|
- prepara o terreno para ETL incremental, snapshots sanitizados e views dedicadas sem quebrar o painel
|
|
|
|
## Decisao complementar ja tomada
|
|
|
|
A topologia acima agora foi materializada assim:
|
|
|
|
- `etl_incremental` como fronteira de sincronizacao
|
|
- `snapshot_table` no admin para persistencia de leitura
|
|
- `dedicated_view` sobre snapshots para servir APIs e dashboard
|
|
- sem replica operacional do banco do produto nesta fase
|