orquestrador/shared/contracts/README.md

Shared Contracts

Esta pasta existe para concentrar contratos e artefatos compartilhados entre:

• app/ (produto)
• admin_app/ (administrativo)

Ela nao deve receber regra de negocio do atendimento nem codigo acoplado ao hot path do produto.

Contratos iniciais

Nesta fase, os primeiros contratos compartilhados sao:

• access_control.py

  • define a hierarquia inicial de acesso interno
  • papeis: colaborador, diretor
  • colaborador consulta o fluxo operacional e cadastra novas tools em draft
  • diretor revisa, aprova, publica tools e cadastra novos colaboradores

• tool_publication.py

  • define o contrato minimo de publicacao de tools do admin para o product
  • inclui envelope de publicacao, status de ciclo de vida e schema de parametros

• product_operational_data.py

  • define quais datasets operacionais do product podem ser consultados pelo admin
  • explicita dominios, granularidade de leitura, campos permitidos e campos bloqueados
  • reforca que o acesso administrativo nasce como leitura orientada a relatorios
  • declara que a leitura deve acontecer por admin_read_model, com consistencia eventual e sem query direta do painel no banco operacional do produto
  • formaliza a materializacao inicial por etl_incremental em snapshot_table, servida por dedicated_view
  • deixa explicito que a fase inicial nao usa replica operacional do produto para abrir dashboards administrativos

• system_functional_configuration.py

  • define quais configuracoes funcionais o admin pode consultar e quais podem ser alteradas
  • separa o runtime do bot de atendimento do runtime de geracao de tools
  • estabelece catalogo homologado de modelos, politicas do bot, politicas de canal e estado efetivo publicado
  • reforca que apenas diretor altera configuracoes governadas com manage_settings
  • deixa explicito que o painel nao altera segredos, credenciais ou tabelas operacionais do produto

• bot_governed_configuration.py

  • detalha quais campos do bot ficam sob governanca administrativa
  • cobre selecao de modelo, geracao de resposta, uso de tools, fallback, handoff e operacao por canal
  • deixa explicito que a governanca do bot usa publicacao versionada e nao escrita direta no runtime do produto
  • reforca que runtime de geracao de tools nao e configuracao do bot de atendimento

• model_runtime_separation.py

  • formaliza que atendimento e geracao de tools usam perfis de modelo distintos
  • separa config key, catalogo alvo, publicacao e rollback entre os dois runtimes
  • deixa explicito que uma mudanca em um runtime nao propaga automaticamente para o outro

Regras

• shared/contracts deve guardar apenas contratos estaveis entre servicos
• nada aqui deve importar modulos internos de app/ ou admin_app/
• as mudancas devem ser additive-first para permitir deploy independente entre product e admin
• contratos de leitura operacional nao autorizam escrita administrativa nas tabelas do produto
• relatorios administrativos devem consumir read models assincronos, nunca scans pesados no hot path do atendimento
• views dedicadas de relatorio so podem ser construidas sobre snapshots sanitizados do admin, nunca sobre tabelas live do produto
• configuracoes funcionais governadas nao autorizam escrita direta no runtime do product durante request web do painel