Import ClientFlow production v4928.1.5.132.4

docs/CLIENTFLOW_V4928_1_4_9_REPLY_ASSISTANT.md

@@ -0,0 +1,119 @@
+# ClientFlow v4928.1.4.9 — Opportunity Reply Assistant
+
+## Objetivo
+
+Reduzir o atrito entre ClientFlow e Chatwoot. O operador passa a gerar e enviar mensagens comerciais a partir da tarefa, usando modelos e anexos já ligados à oportunidade.
+
+O Chatwoot continua a ser o canal técnico de envio, mas o ClientFlow passa a ser o cockpit operacional.
+
+## O que foi adicionado
+
+### Modelos de mensagem
+
+Novo catálogo em `app/message_templates.py`:
+
+- `SEND_INFO_EQUIPMENT_LIST`
+- `SEND_PRICE_LIST`
+- `SEND_QUOTE`
+- `SEND_PROFORMA`
+- `SEND_INVOICE`
+- `REQUEST_FISCAL_DATA`
+- `REQUEST_PAYMENT_PROOF`
+- `CONFIRM_PAYMENT_RECEIVED`
+- `FOLLOW_UP_QUOTE`
+
+Os modelos são determinísticos e editáveis antes do envio.
+
+### Serviço de resposta
+
+Novo serviço `app/reply_assistant_service.py`:
+
+- carrega tarefa, oportunidade e documentos associados;
+- escolhe modelo por ação;
+- gera rascunho editável;
+- valida prontidão antes de enviar;
+- bloqueia anexos que não pertencem à oportunidade;
+- envia mensagem pública no Chatwoot;
+- regista comunicação outbound;
+- regista evento na timeline;
+- pode concluir a tarefa após envio.
+
+### UI na tarefa
+
+A página da tarefa ganhou o bloco **Resposta ao cliente**:
+
+- seletor de modelo;
+- seleção de anexos da oportunidade;
+- botão **Gerar rascunho**;
+- textarea editável;
+- botão **Enviar**;
+- botão **Enviar e concluir tarefa**.
+
+### Chatwoot
+
+`app/chatwoot_client.py` ganhou:
+
+- `send_public_message()`;
+- `send_public_message_with_attachments()`.
+
+O envio continua protegido por:
+
+```env
+CHATWOOT_WRITE_ENABLED=true
+CHATWOOT_BASE_URL=...
+CHATWOOT_ACCOUNT_ID=...
+CHATWOOT_API_TOKEN=...
+```
+
+### Auditoria
+
+Foi adicionada a tabela `message_drafts` para guardar rascunhos gerados e estado do envio.
+
+Cada envio cria também um registo em `communications` com:
+
+- `direction = outbound`;
+- `source_system = chatwoot`;
+- `conversation_id`;
+- `task_id`;
+- `opportunity_id`;
+- `metadata.template_code`;
+- `metadata.attachments`;
+- `metadata.chatwoot_result`.
+
+### Timeline
+
+Ao enviar uma mensagem, o ClientFlow cria um evento `reply_sent` na timeline da oportunidade.
+
+## Regras de segurança
+
+- Um documento só pode ser anexado se pertence à mesma oportunidade da tarefa.
+- Envio de documentos fiscais exige cliente fiscal minimamente preenchido.
+- Documentos sem `external_id` não são anexados automaticamente.
+- Nesta versão, PDF automático está limitado a documentos Jasmin suportados pelo serviço existente: `quotation` e `invoice`.
+- O LLM não é usado para decidir preço, documento ou anexo.
+
+## LLM
+
+Foi adicionada a opção:
+
+```env
+CLIENTFLOW_REPLY_LLM_ENABLED=false
+```
+
+Nesta versão fica desativada. A arquitetura fica preparada para uma versão seguinte onde o LLM apenas adapte o texto, mantendo oportunidade/documentos como fonte de verdade.
+
+## Endpoints novos
+
+```http
+POST /tasks/{task_id}/reply-draft
+POST /tasks/{task_id}/send-reply
+```
+
+## Rollback
+
+A alteração é aditiva. Para rollback funcional:
+
+1. manter `CHATWOOT_WRITE_ENABLED=false` para bloquear envio;
+2. remover/ignorar o bloco UI de resposta;
+3. a tabela `message_drafts` pode permanecer sem afetar o fluxo antigo.
+