You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
243 lines
8.5 KiB
Markdown
243 lines
8.5 KiB
Markdown
# 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
|
|
|
|
|