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