orquestrador/docs/architecture/admin-operational-data-scope.md

# Escopo De Dados Operacionais Do Product Visiveis No Admin

## Objetivo

Definir, de forma explicita, quais dados operacionais do `orquestrador-product` podem ser consultados pelo `orquestrador-admin` na fase inicial de relatorios e configuracao.

Esta definicao cobre o **que** o admin pode ler.
A estrategia de leitura desses dados sem acoplar o hot path do atendimento fica detalhada em `docs/architecture/admin-report-reading-strategy.md`.
A materializacao concreta desses relatorios fica detalhada em `docs/architecture/admin-report-materialization-strategy.md`.

## Principios obrigatorios

1. O `product` continua sendo a fonte operacional primaria.
2. O `admin` nasce com acesso de leitura orientado a relatorios, nunca como escritor direto dessas tabelas.
3. O hot path do atendimento nao deve depender de consulta online ao `admin`.
4. Dados de identidade do cliente final, texto livre e segredos operacionais nao entram automaticamente na fronteira administrativa.
5. Sempre que um indicador puder ser atendido por agregado, o agregado deve ser preferido a leitura detalhada.

## Datasets permitidos nesta fase

O contrato compartilhado correspondente fica em `shared/contracts/product_operational_data.py`.

### 1. Estoque comercial

Fonte atual:

- `vehicles`

Uso administrativo esperado:

- disponibilidade comercial
- distribuicao por categoria
- faixa de preco
- entrada de novos itens no estoque

Campos permitidos:

- `id`
- `modelo`
- `categoria`
- `preco`
- `created_at`

### 2. Pedidos de venda

Fonte atual:

- `orders`

Uso administrativo esperado:

- volume de pedidos
- pedidos ativos e cancelados
- ticket medio
- cancelamentos por periodo

Campos permitidos:

- `numero_pedido`
- `vehicle_id`
- `modelo_veiculo`
- `valor_veiculo`
- `status`
- `motivo_cancelamento`
- `data_cancelamento`
- `created_at`
- `updated_at`

Campos bloqueados:

- `user_id`
- `cpf`

### 3. Agenda de revisoes

Fonte atual:

- `review_schedules`

Uso administrativo esperado:

- ocupacao de slots
- revisoes agendadas por periodo
- taxa de cancelamento
- fila operacional da oficina

Campos permitidos:

- `protocolo`
- `placa`
- `data_hora`
- `status`
- `created_at`

Campos bloqueados:

- `user_id`

### 4. Frota de locacao

Fonte atual:

- `rental_vehicles`

Uso administrativo esperado:

- disponibilidade da frota
- status operacional por categoria
- tarifa diaria vigente

Campos permitidos:

- `id`
- `placa`
- `modelo`
- `categoria`
- `ano`
- `valor_diaria`
- `status`
- `created_at`

### 5. Contratos de locacao

Fonte atual:

- `rental_contracts`

Uso administrativo esperado:

- contratos ativos e encerrados
- devolucoes em atraso
- receita prevista versus receita final
- ocupacao da frota no tempo

Campos permitidos:

- `contrato_numero`
- `rental_vehicle_id`
- `placa`
- `modelo_veiculo`
- `categoria`
- `data_inicio`
- `data_fim_prevista`
- `data_devolucao`
- `valor_diaria`
- `valor_previsto`
- `valor_final`
- `status`
- `created_at`
- `updated_at`

Campos bloqueados:

- `user_id`
- `cpf`
- `observacoes`

### 6. Pagamentos de locacao

Fonte atual:

- `rental_payments`

Uso administrativo esperado:

- arrecadacao por periodo
- pagamentos conciliados por contrato
- inadimplencia operacional

Campos permitidos:

- `protocolo`
- `contrato_numero`
- `placa`
- `valor`
- `data_pagamento`
- `created_at`

Campos bloqueados:

- `user_id`
- `rental_contract_id`
- `favorecido`
- `identificador_comprovante`
- `observacoes`

### 7. Telemetria conversacional

Fonte atual:

- `conversation_turns`

Uso administrativo esperado:

- volume de atendimento
- latencia por turno
- distribuicao por dominio
- uso de tools
- falhas operacionais por status

Campos permitidos:

- `request_id`
- `conversation_id`
- `channel`
- `turn_status`
- `intent`
- `domain`
- `action`
- `tool_name`
- `elapsed_ms`
- `started_at`
- `completed_at`

Campos bloqueados:

- `user_id`
- `external_id`
- `username`
- `user_message`
- `assistant_response`
- `tool_arguments`
- `error_detail`

### 8. Entregas de integracao

Fonte atual:

- `integration_deliveries`

Uso administrativo esperado:

- taxa de sucesso por provedor
- volume de eventos entregues
- entregas pendentes ou com falha
- tentativas de reenvio

Campos permitidos:

- `route_id`
- `event_type`
- `provider`
- `status`
- `attempts`
- `dispatched_at`
- `created_at`
- `updated_at`

Campos bloqueados:

- `payload_json`
- `recipient_email`
- `recipient_name`
- `rendered_subject`
- `rendered_body`
- `provider_message_id`
- `last_error`

## Fontes fora do escopo administrativo nesta fase

O admin **nao** deve consultar diretamente, nesta fase:

- `customers`
- `users`
- stores de estado conversacional de hot path
- payloads brutos de tools e mensagens do usuario
- comprovantes e identificadores sensiveis de pagamento
- configuracoes internas de provedor e credenciais

## Regra de autorizacao

A leitura desses dados nasce amarrada a `view_reports`.

Consequencia pratica:

- `colaborador` pode consultar os dados operacionais liberados para relatorio
- `diretor` herda essa leitura e acumula as etapas de aprovacao e configuracao
- permissao adicional sera exigida apenas quando a consulta implicar governanca, aprovacao ou configuracao

## Decisao tomada nesta etapa

O `admin` pode consultar apenas datasets operacionais explicitamente declarados em contrato compartilhado e sempre em modo somente leitura.

A fronteira inicial favorece relatorios de:

- vendas
- arrecadacao
- operacao
- telemetria de atendimento
- entregas de integracao

## Decisao de materializacao relacionada

Para esses datasets, a fase inicial escolhe:

- `etl_incremental` como estrategia de sincronizacao
- `snapshot_table` no lado administrativo como persistencia de leitura
- `dedicated_view` sobre os snapshots como superficie de consulta para APIs e UI
- nenhuma replica operacional do banco do produto no dashboard administrativo