# ClientFlow v4.9.1 — Operational Reconciliation & External Intake

Esta versão adiciona uma área de **Reconciliação** para organizar informação que existe fora do ClientFlow antes de a transformar em processo comercial.

## Objetivo

O ClientFlow passa a preparar informação solta de:

- documentos Jasmin criados fora do ClientFlow;
- faturas/orçamentos sem oportunidade;
- comprovativos de pagamento recebidos manualmente;
- pedidos vindos de WhatsApp, telefone, email direto ou presencial;
- futuras vendas Odoo sem oportunidade.

A regra principal é:

```text
Sincronizar/detetar automaticamente.
Criar candidato de reconciliação.
Operador confirma ligar, criar oportunidade ou ignorar.
```

## O que mudou

### Nova página

```text
/reconciliation
/reconciliacao
```

A página mostra:

- itens abertos de reconciliação;
- documentos sem ligação;
- comprovativos por associar;
- ações para criar oportunidade, ligar oportunidade existente ou ignorar.

### Novas tabelas aditivas

A versão cria schema adicional no arranque:

```text
reconciliation_items
payment_proofs
```

É uma alteração aditiva: não remove nem altera dados existentes.

### Entrada manual externa

A página permite registar pedidos vindos de canais fora do Chatwoot:

```text
WhatsApp
Telefone
Email direto
Presencial
Outro
```

Ao registar, o sistema cria:

- oportunidade;
- task com a próxima ação;
- evento de timeline.

Não cria IDs falsos de Chatwoot.

### Comprovativos de pagamento

Um comprovativo pode ser guardado e ligado a uma oportunidade.

Importante:

```text
Comprovativo recebido não confirma pagamento.
```

Quando está ligado a uma oportunidade, cria task `CONFIRM_PAYMENT` para validação humana.

### Sincronização local

Script novo:

```bash
PYTHONPATH=. python scripts/sync_reconciliation_candidates.py
```

Ele procura documentos Jasmin locais em `commercial_documents` sem `opportunity_id` e cria candidatos de reconciliação.

## Fluxo operacional recomendado

```text
Documento/Comprovativo/Pedido externo
        ↓
Reconciliação
        ↓
Operador decide:
  - ligar a oportunidade existente
  - criar oportunidade
  - ignorar
        ↓
ClientFlow cria/atualiza oportunidade e task
```

## O que esta versão não faz

- Não confirma pagamentos automaticamente.
- Não emite faturas automaticamente.
- Não apaga nem substitui documentos Jasmin.
- Não fecha oportunidades sozinha.
- Não usa LLM para reorganizar sem confirmação humana.

## Validação

```bash
PYTHONPATH=. python -m compileall app scripts tests
PYTHONPATH=. pytest -q
```

## Rollback

O código pode ser revertido normalmente. As tabelas novas são aditivas e podem ficar sem afetar o fluxo antigo.