Release v4928.1.4.2 stable

docs/CLIENTFLOW_V4920_MULTI_PURCHASE_RECONCILIATION.md

@@ -0,0 +1,81 @@
+# 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
+```