# ClientFlow v4.9.20 — Multi-Purchase Reconciliation

## Objetivo

A reconciliação deixa de assumir que `um cliente fiscal = um processo`.

A regra passa a ser:

- **Cliente fiscal** identifica quem é a entidade: NIF, nome fiscal normalizado, email ou mapeamento externo confirmado.
- **Compra/processo** identifica o ciclo comercial específico: orçamento, venda, pró-forma, fatura, comprovativo, entrega ou histórico associado a essa compra.
- **Oportunidade** representa uma compra/processo concreto, não todo o histórico do cliente.

## Problema corrigido

Clientes com documentos soltos e várias compras podiam ser agrupados numa única timeline apenas porque partilhavam NIF ou nome fiscal.

Exemplo de risco:

- ACZCO BRAGA ENERGY, LDA / NIF 517249200
- ORC.ORC2026.154 / 638,60 €
- S00279 / 638,60 €
- ORC.ORC2026.160 / 190,00 €
- FA2026.80 histórica

Antes, estes itens podiam aparecer como um único processo candidato.

Agora a reconciliação faz duas passagens:

1. Agrupa por cliente fiscal.
2. Divide o cliente em compras/processos separados.

## Regras de separação por compra

São âncoras de compra:

- Venda Odoo (`odoo_sale_order`)
- Orçamento Jasmin (`jasmin_quotation`)
- Pró-forma Jasmin (`jasmin_proforma`)
- Fatura Jasmin (`jasmin_invoice`)

Duas âncoras só são fundidas no mesmo processo quando há evidência forte:

- mesma referência externa; ou
- tipos documentais diferentes com valor igual/aproximado e datas próximas; ou
- ponte Jasmin ↔ Odoo próxima quando o valor Jasmin não foi importado, mantendo vendas Odoo diferentes sempre separadas.

Duas vendas Odoo diferentes nunca são fundidas automaticamente.
Duas cotações Jasmin diferentes nunca são fundidas automaticamente só por terem o mesmo cliente.

## Itens soltos

Comprovativos, envios e outros itens sem âncora própria são atribuídos a uma compra apenas quando o match é inequívoco por valor/data/referência/produto.

Caso contrário, ficam como item/processo separado para revisão manual.

## UI

A página de Reconciliação passou a explicar explicitamente:

> O sistema agrupa primeiro por cliente fiscal e depois separa por compra/processo.

Nos cartões de processo, a chave passa a distinguir:

- Cliente fiscal: NIF / nome fiscal / email
- Compra/processo: S00279, ORC.ORC2026.154, FA2026.80, etc.

## Testes adicionados

- Duas vendas Odoo do mesmo cliente geram dois processos candidatos.
- Um orçamento Jasmin é atribuído à venda Odoo correta por valor/data.
- Duas cotações Jasmin do mesmo cliente ficam em dois processos diferentes.
- Cotação e fatura com mesmo valor e data próxima podem formar uma compra.
- Comprovativo é associado apenas quando o match com a venda é inequívoco.

## Validação

Suite completa:

```text
164 passed
```