# Contratos Compartilhados E Hierarquia De Acesso Este documento define os primeiros contratos compartilhados entre `orquestrador-product` e `orquestrador-admin`, com foco especial na hierarquia de acesso do runtime administrativo. ## Objetivo Criar uma base comum para: - autenticacao e autorizacao administrativa - publicacao de tools do `admin` para o `product` - leitura operacional segura do `admin` sobre o `product` - configuracao funcional governada entre `admin` e `product` - evolucao independente dos dois servicos sem acoplamento indevido ## Hierarquia inicial de acesso Os papeis administrativos ficam centralizados em `shared/contracts/access_control.py`. Hierarquia: 1. `colaborador` 2. `diretor` ### `colaborador` Responsavel por operacao interna de acompanhamento e cadastro inicial de tools. Permissoes iniciais: - `view_system` - `view_reports` - `view_audit_logs` - `manage_tool_drafts` ### `diretor` Responsavel por configuracao, aprovacao, publicacao e gestao de acesso interno. Permissoes iniciais: - todas as de `colaborador` - `review_tool_generations` - `publish_tools` - `manage_settings` - `manage_staff_accounts` ## Regras de desenho 1. Os papeis nascem em contrato compartilhado para que `admin` e `product` falem a mesma lingua. 2. O `product` nao usa essa hierarquia para atendimento ao cliente final. 3. O `admin` usa essa hierarquia para autenticacao, autorizacao e auditoria. 4. Toda evolucao deve ser additive-first para nao bloquear deploy independente. ## Contrato de publicacao de tool O contrato inicial fica em `shared/contracts/tool_publication.py`. Ele cobre: - `ServiceName` - `ToolLifecycleStatus` - `ToolParameterType` - `ToolParameterContract` - `PublishedToolContract` - `ToolPublicationEnvelope` ## Contrato de leitura operacional do produto O contrato inicial fica em `shared/contracts/product_operational_data.py`. Ele cobre: - datasets operacionais que o `admin` pode consultar do `product` - dominios atuais: `inventory`, `sales`, `review`, `rental`, `conversation`, `integration` - granularidade inicial de leitura por registro e por agregado - campos liberados para relatorio e operacao - campos bloqueados quando carregam identidade do cliente, texto livre ou segredos operacionais - estrategia de leitura por `admin_read_model`, consistencia eventual e leitura sem query direta do painel no banco operacional do produto - estrategia de materializacao inicial por `etl_incremental`, persistida em `snapshot_table` e exposta ao painel por `dedicated_view` ### Regra de permissao A leitura desses datasets nasce sob `view_reports`. Isso significa: - `colaborador` pode consultar relatorios e snapshots operacionais - `diretor` herda essa leitura - a permissao nao autoriza escrita nem governanca sobre tabelas operacionais ### Regra de minimizacao Mesmo quando um dataset do produto entra na fronteira compartilhada, o `admin` nao recebe automaticamente todos os seus campos. A fronteira correta eh: - expor indicadores operacionais, ids tecnicos e chaves publicas necessarias ao relatorio - bloquear `cpf`, `email`, `external_id`, payloads brutos, mensagens livres e identificadores sensiveis - preferir agregados quando o mesmo objetivo nao exigir leitura linha a linha ### Regra de isolamento do hot path As consultas administrativas de relatorio nao devem ser executadas diretamente sobre as tabelas operacionais do produto a partir de uma request web do painel. A fronteira correta eh: - o `product` escreve estado operacional - uma camada assincrona de `etl_incremental` materializa snapshots sanitizados no admin - o painel e as APIs administrativas consultam `dedicated_view` construidas sobre esses snapshots - nenhuma view administrativa pode apontar diretamente para tabelas live do `product` ## Contrato de configuracao funcional governada O contrato inicial fica em `shared/contracts/system_functional_configuration.py`. Ele cobre: - quais configuracoes funcionais o `admin` pode consultar do sistema - quais configuracoes podem ser alteradas apenas por `diretor` - a separacao entre runtime de atendimento e runtime de geracao de tools - a diferenca entre estado governado no `admin` e estado efetivo publicado no `product` - a proibicao de alterar segredos, infra e tabelas operacionais a partir do painel ### Superficies iniciais declaradas As primeiras configuracoes funcionais compartilhadas sao: - `allowed_model_catalog` - `atendimento_runtime_profile` - `tool_generation_runtime_profile` - `bot_behavior_policy` - `channel_operation_policy` - `published_runtime_state` ### Regra de permissao A leitura dessas configuracoes nasce sob `view_system`. Isso significa: - `colaborador` pode consultar configuracoes efetivas, catalogos homologados e estado publicado - `diretor` herda essa leitura - apenas `diretor` pode alterar configuracoes governadas, usando `manage_settings` ### Regra de governanca A fronteira correta eh: - `diretor` altera apenas configuracoes funcionais governadas - toda alteracao nasce como estado administrativo versionado - o `product` consome apenas configuracao publicada e aprovada - o painel nao altera segredos, variaveis de ambiente, credenciais, schema operacional ou comportamento interno sem governanca ### Regra de separacao entre modelos A escolha de modelo do bot de atendimento e a escolha de modelo para geracao de tools nao devem compartilhar a mesma chave de configuracao. A fronteira correta eh: - `atendimento_runtime_profile` governa o modelo que responde ao cliente final - `tool_generation_runtime_profile` governa o modelo usado para gerar e validar tools - cada perfil pode evoluir, ser auditado e ser publicado em ritmos diferentes ## Contrato de governanca do bot O contrato inicial fica em `shared/contracts/bot_governed_configuration.py`. Ele cobre, em nivel de campo, quais configuracoes do bot de atendimento ficam sob governanca administrativa. As primeiras superficies governadas sao: - selecao de modelo do bot: `provider`, `model_name` - geracao de resposta: `temperature`, `max_output_tokens`, `prompt_profile_ref` - uso de tools: `tool_policy_ref`, `max_tool_calls_per_turn`, `confirmation_policy` - fallback e handoff: `fallback_mode`, `handoff_enabled`, `handoff_intents` - operacao por canal: `enabled`, `maintenance_mode`, `default_route`, `operation_window_ref` ### Regra de permissao A leitura dessas configuracoes continua sob `view_system`. A alteracao governada continua restrita a `diretor`, com `manage_settings`. ### Regra de fronteira Esse contrato deixa explicito que: - runtime de geracao de tools nao entra como configuracao do bot de atendimento - o painel governa referencias e politicas funcionais, nao segredos nem infraestrutura - nenhuma configuracao do bot e aplicada por escrita direta no banco ou runtime live do `product` - toda mudanca passa por publicacao versionada e auditavel ## Contrato de separacao entre runtimes de modelo O contrato inicial fica em `shared/contracts/model_runtime_separation.py`. Ele cobre: - os alvos `atendimento` e `tool_generation` - a `config_key` de cada runtime - o servico consumidor de cada perfil de modelo - a exigencia de publicacao e rollback independentes - a proibicao de propagacao implicita entre os dois runtimes ### Regra de fronteira Esse contrato deixa explicito que: - o runtime de atendimento e consumido pelo `product` - o runtime de geracao e consumido pelo `admin` - trocar um perfil nao troca automaticamente o outro - os dois podem compartilhar um provedor homologado, mas nao compartilham estado de configuracao ## Como isso sera usado depois ### No `orquestrador-admin` - criar `StaffAccount` - associar `StaffAccount.role` - controlar acesso a UI, as rotas e a aprovacao de tools - emitir `ToolPublicationEnvelope` quando uma tool for publicada - construir relatorios usando apenas datasets declarados no contrato compartilhado - consultar read models administrativos em vez de tabelas live do produto - governar configuracoes funcionais sem escrever diretamente no banco operacional do `product` ### No `orquestrador-product` - consumir apenas tools publicadas - validar status e versao do contrato recebido - expor fronteiras seguras para sincronizacao incremental dos datasets permitidos ao `admin` - consumir apenas configuracoes funcionais publicadas e aprovadas - evitar dependencia do runtime do admin no hot path ## Proximos passos naturais - criar rotas administrativas para relatorios - criar rotas administrativas para configuracao funcional do sistema - estruturar snapshots e views de vendas, arrecadacao e operacao - manter a escrita administrativa fora das tabelas operacionais do produto