Release v4928.1.4.2 stable

docs/CLIENTFLOW_V46_CHATWOOT_WORKFLOW_HARDENING.md

@@ -0,0 +1,99 @@
+# ClientFlow v4.6 — Chatwoot Workflow Hardening
+
+## Objetivo
+
+Esta atualização não cria uma segunda inbox. O Chatwoot continua a ser a caixa de entrada e o ClientFlow passa a tratar melhor o trabalho que nasce das mensagens do Chatwoot.
+
+Fluxo alvo:
+
+```text
+Chatwoot → webhook → classificação → task/opportunity → Centro de trabalho → timeline
+```
+
+## Alterações principais
+
+### 1. `REVIEW_MANUALLY` passa a ser trabalho pendente
+
+Antes, decisões `REVIEW_MANUALLY` ficavam como `skipped`. Isto escondia mensagens que precisavam de operador.
+
+Agora:
+
+```text
+REVIEW_MANUALLY → route=rever → status=pending → priority=alta
+```
+
+### 2. `REMOVE_FROM_LIST` passa a ser operacional
+
+Antes podia ficar tratado como revisão/skip. Agora fica pendente e orientado para marketing:
+
+```text
+REMOVE_FROM_LIST → route=marketing → status=pending
+```
+
+### 3. Só spam e “sem ação” ficam `skipped`
+
+```text
+IGNORE_SPAM → skipped
+NO_ACTION → skipped
+```
+
+### 4. Centro de trabalho mostra contexto Chatwoot
+
+Os itens operacionais vindos do Chatwoot passam a trazer:
+
+```text
+source_system
+conversation_id
+contact_id
+request_text
+chatwoot_url
+```
+
+A UI mostra botão para abrir a conversa no Chatwoot quando `CHATWOOT_PUBLIC_URL`/`CHATWOOT_BASE_URL` e `CHATWOOT_ACCOUNT_ID` estão configurados.
+
+### 5. Comunicações deixam de ser navegação principal
+
+A rota técnica `/communications` continua disponível para diagnóstico, mas deixa de ser a inbox principal. O operador deve responder e gerir conversas no Chatwoot.
+
+### 6. Timeline para tasks associadas à oportunidade
+
+Quando uma task criada pelo Chatwoot está ligada a uma oportunidade, é registado evento de timeline `task_created`.
+
+### 7. Script para reabrir revisões antigas
+
+Para corrigir as tasks recentes que já ficaram `skipped` antes da v4.6:
+
+```bash
+PYTHONPATH=. python scripts/reopen_chatwoot_review_tasks.py --dry-run
+PYTHONPATH=. python scripts/reopen_chatwoot_review_tasks.py --days 7
+```
+
+Por defeito só olha para os últimos 7 dias.
+
+## Passos pós-instalação recomendados
+
+```bash
+cd /mnt/ssd/home/plx/clientflow_backend
+source .venv/bin/activate 2>/dev/null || true
+
+PYTHONPATH=. python -m compileall app scripts tests
+PYTHONPATH=. pytest -q
+
+PYTHONPATH=. python scripts/reopen_chatwoot_review_tasks.py --dry-run
+PYTHONPATH=. python scripts/reopen_chatwoot_review_tasks.py --days 7
+
+sudo systemctl restart clientflow-api
+sudo systemctl status clientflow-api --no-pager
+```
+
+## Validação funcional
+
+Verificar:
+
+```text
+/tasks?status=pending&route=rever
+/operations
+/opportunities
+```
+
+E confirmar que novas mensagens Chatwoot classificadas como revisão aparecem como pendentes.