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