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