# Escopo De Configuracao Funcional Governada No Admin ## Objetivo Definir quais configuracoes funcionais o `orquestrador-admin` pode consultar e alterar sem transformar o painel em uma superficie de mudanca irrestrita do runtime do `orquestrador-product`. Esta etapa fixa a **fronteira funcional de configuracao**. As telas e rotas especificas da fase 4 vao consumir esse contrato depois. ## Decisao O `admin` pode consultar um conjunto governado de configuracoes funcionais do sistema. Dessas configuracoes, apenas o papel `diretor` pode alterar o estado desejado. O papel `colaborador` fica com leitura para acompanhamento operacional do sistema. A fronteira compartilhada inicial fica em `shared/contracts/system_functional_configuration.py`. O detalhamento especifico do que o painel governa no bot de atendimento fica em `docs/architecture/admin-bot-governed-configuration-scope.md`.`r`nA separacao entre o runtime de atendimento e o runtime de geracao de tools fica em `docs/architecture/admin-model-runtime-separation.md`. ## O que entra na fronteira administrativa As primeiras configuracoes funcionais aprovadas para o painel sao: 1. `allowed_model_catalog` 2. `atendimento_runtime_profile` 3. `tool_generation_runtime_profile` 4. `bot_behavior_policy` 5. `channel_operation_policy` 6. `published_runtime_state` ### 1. `allowed_model_catalog` Superficie somente leitura usada para o painel saber quais modelos estao homologados pela plataforma. Serve para: - montar listas de selecao na tela administrativa - impedir configuracao de modelo fora do catalogo permitido - diferenciar modelos liberados para atendimento e para geracao de tools Nao serve para: - cadastrar credenciais de provedor - alterar limites de infraestrutura - homologar modelo novo diretamente pela UI ### 2. `atendimento_runtime_profile` Configuracao funcional governada do modelo do bot que atende o cliente final. Inclui: - provedor selecionado - modelo selecionado - temperatura - limite de saida - referencia de prompt publicada - referencia de politica de tools Regra: - `colaborador` consulta - `diretor` altera ### 3. `tool_generation_runtime_profile` Configuracao funcional governada do modelo usado para gerar e validar novas tools. Inclui: - provedor selecionado - modelo selecionado - perfil de raciocinio - limite de saida - referencia de politica de validacao Regra obrigatoria: - esse perfil e separado do perfil de atendimento - trocar o modelo de geracao nao troca automaticamente o modelo do bot ### 4. `bot_behavior_policy` Politicas funcionais do fluxo do bot. Inclui: - modo de fallback - handoff para humano - intencoes que forcam escalonamento - limite de chamadas de tool por turno - politica de confirmacao para acao critica Essa configuracao existe para o painel governar o comportamento funcional do atendimento, e nao o codigo interno do orquestrador. ### 5. `channel_operation_policy` Politicas funcionais por canal. Inclui: - canal habilitado ou desabilitado - modo de manutencao - rota funcional padrao - referencia da janela operacional Essa superficie permite governar disponibilidade funcional sem dar acesso a infraestrutura bruta. ### 6. `published_runtime_state` Superficie somente leitura do estado efetivo publicado no `product`. Inclui: - escopo configurado - versao ativa - quem publicou - quando publicou - quando o produto aplicou a mudanca Serve para: - auditoria - transparencia na dashboard - comparacao entre estado desejado no admin e estado efetivo no produto ## O que fica fora da fronteira administrativa As seguintes superficies nao entram como configuracao funcional alteravel no painel: - segredos e credenciais de provedor - API keys - strings de conexao com banco - variaveis de ambiente de deploy - configuracao de autoscaling e infraestrutura - schema de banco operacional - payloads tecnicos internos de execucao - alteracao direta em tabelas operacionais do `product` ## Regras obrigatorias ### 1. Leitura ampla, escrita governada A leitura dessas configuracoes nasce sob `view_system`. Consequencia pratica: - `colaborador` pode consultar a configuracao funcional vigente - `diretor` tambem consulta - apenas `diretor` altera configuracoes governadas com `manage_settings` ### 2. Sem escrita direta no produto O painel administrativo nao escreve diretamente no runtime do `product` durante uma request de UI. A fronteira correta eh: - o `admin` registra estado funcional desejado - o estado e versionado, auditado e aprovado - o `product` consome apenas configuracao publicada ### 3. Separacao entre atendimento e geracao de tools Os dois runtimes precisam continuar independentes. Portanto: - o modelo do atendimento vive em `atendimento_runtime_profile` - o modelo de geracao vive em `tool_generation_runtime_profile` - cada perfil pode ter rollout, auditoria e fallback proprios ### 4. Estado efetivo precisa ser observavel Toda configuracao governada precisa gerar uma superficie de consulta sobre o estado efetivo publicado no `product`. Consequencia pratica: - a dashboard administrativa consegue mostrar o que esta ativo de verdade - o sistema evita divergencia silenciosa entre desejo do admin e runtime do produto ## Consequencias positivas - permite escolher modelo do bot pelo painel sem expor segredos de infraestrutura - prepara a tela de configuracoes do sistema para `diretor` - mantem `colaborador` com visibilidade do fluxo do bot e do estado vigente - reforca a separacao entre governanca administrativa e hot path do atendimento - prepara versionamento e auditoria das configuracoes antes da integracao completa entre `admin` e `product` ## Proximos passos naturais - criar rotas administrativas para configuracao funcional do sistema - criar tela administrativa de configuracoes do sistema - criar superficie visual para estado publicado e versoes ativas - definir publicacao e consumo dessas configuracoes entre `admin` e `product`