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