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.
59 lines
3.3 KiB
Markdown
59 lines
3.3 KiB
Markdown
# 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
|