# 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