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

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

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