orquestrador/docs/architecture/admin-functional-configuration-scope.md

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.rnA 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