Release v4928.1.4.2 stable

docs/CLIENTFLOW_V4917_RECONCILIATION_CROSS_SOURCE_GROUPING.md

@@ -0,0 +1,38 @@
+# ClientFlow v4.9.17 — Reconciliation Cross-Source Grouping
+
+Esta versão corrige um problema na Reconciliação em que evidências do mesmo processo apareciam separadas quando cada sistema fornecia identificadores diferentes.
+
+## Problema
+
+Exemplo real:
+
+- Jasmin tem orçamento para `ACZCO BRAGA ENERGY, LDA` com NIF `517249200`.
+- Odoo tem venda `S00279` para `ACZCO BRAGA ENERGY, LDA`, mas sem NIF.
+
+Antes, a Reconciliação podia mostrar o orçamento como processo candidato com `1 evidência` e a venda Odoo apenas como sugestão/elemento separado.
+
+## Correção
+
+A construção de processos candidatos passa a usar todos os sinais de identidade disponíveis no item:
+
+- NIF
+- email
+- nome fiscal normalizado
+
+Se uma evidência Jasmin tem NIF + nome e uma evidência Odoo tem o mesmo nome, ambas são agrupadas no mesmo processo candidato. O NIF continua a ser a chave de maior confiança do grupo.
+
+## Resultado esperado
+
+O caso deve aparecer como um único processo:
+
+- Orçamento Jasmin encontrado
+- Venda/encomenda Odoo encontrada
+- Linhas/produtos Odoo importados
+- Entrega Odoo concluída, se existir
+- Fatura por emitir, se `invoice_status = to invoice`
+
+A ação sugerida deve ser coerente com o estado mais avançado: por exemplo, `SEND_INVOICE` quando existe venda/entrega Odoo por faturar.
+
+## Segurança
+
+A versão não liga automaticamente nada. Continua a ser necessário o operador confirmar a ligação ou reconstrução.