Import ClientFlow production v4928.1.5.132.4

RELEASE_NOTES_v4928_1_5_34.md

@@ -0,0 +1,58 @@
+# ClientFlow v4928.1.5.34 — Communication Composer + SQL safety foundation
+
+Atualização conservadora focada em reduzir erros de rascunho/LLM e começar a padronizar SQL seguro.
+
+## Principais melhorias
+
+### 1. Communication Composer
+- O painel de resposta passa a pedir um **objetivo explícito** antes de gerar rascunho:
+  - Enviar informação/lista de equipamentos
+  - Enviar orçamento
+  - Enviar pró-forma
+  - Enviar fatura
+  - Confirmar pagamento/follow-up
+- O operador pode escrever **instruções adicionais para a IA** antes da geração.
+- Os documentos/anexos da oportunidade ficam disponíveis no Composer antes de chamar IA, não apenas depois do rascunho.
+- A instrução do operador é guardada em `message_drafts.operator_instruction`.
+- O objetivo escolhido e os documentos selecionados ficam persistidos em `message_drafts.metadata.communication_objective`.
+
+### 2. Guardrails de rascunho para faturas
+- Para `SEND_INVOICE`, o validador bloqueia rascunhos que:
+  - dizem que a fatura ainda será emitida;
+  - pedem comprovativo de pagamento indevidamente;
+  - tratam uma fatura emitida como pró-forma/pagamento pendente.
+- Quando uma fatura está selecionada, o sistema recomenda mencionar que segue em anexo.
+- O prompt OpenAI/file_search recebe `objetivo_operador` e `instrucao_operador`, para impedir que a IA reinterprete o próximo passo.
+
+### 3. Base SQL safety
+- Novo `app/db_helpers.py` com helpers para serialização JSONB segura.
+- Updates internos de estado de draft enviados/falhados passam a usar `metadata || CAST(:metadata_patch AS JSONB)` em vez de `jsonb_build_object` com binds soltos.
+- Novo script read-only `scripts/audit_sql_safety.py` para encontrar padrões SQL frágeis:
+  - `jsonb_build_object(... :param ...)`
+  - `:param IS NULL` sem cast
+  - `ANY(:lista)` sem tipo explícito
+  - concatenação JSONB sem `CAST(:metadata_patch AS JSONB)`
+
+### 4. Auditoria profunda incluída no pacote
+- Incluído `scripts/audit_deep_system.py` com correção de serialização `Decimal`/datas/UUID.
+
+## Segurança operacional
+- Não envia mensagens automaticamente.
+- Não altera tasks, oportunidades ou clientes existentes.
+- Não executa reparações automáticas.
+- A nova auditoria SQL é apenas diagnóstico.
+
+## Validação
+- `python -m compileall -q app scripts tests`
+- `python -m pytest -q`
+- Resultado local: `312 passed`
+
+## Comandos úteis pós-instalação
+
+```bash
+python scripts/audit_system_health.py; echo "EXIT_CODE=$?"
+python scripts/audit_deep_system.py --window-hours 72 --sample-limit 25; echo "EXIT_CODE=$?"
+python scripts/audit_sql_safety.py; echo "EXIT_CODE=$?"
+```
+
+Nota: `audit_sql_safety.py` pode devolver `EXIT_CODE=1` quando encontra padrões a rever. Isso é esperado nesta fase e não significa falha de runtime.