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