Release v4928.1.4.2 stable

docs/CLIENTFLOW_V4925_FISCAL_ENRICHMENT_WORKER.md

@@ -0,0 +1,98 @@
+# ClientFlow v4.9.25 — Fiscal Enrichment Worker
+
+Esta versão adiciona uma camada autónoma antes da reconciliação:
+
+```text
+Oportunidades abertas sem cliente fiscal
+→ enriquecimento fiscal por NIF/email/domínio/nome
+→ sugestão ou auto-associação segura
+→ sincronização Jasmin/Odoo
+→ reconciliação por cliente fiscal + processo de compra
+```
+
+## Objetivo
+
+Melhorar a ligação entre oportunidades internas, Jasmin e Odoo evitando que a
+reconciliação dependa de nomes de contacto ou texto livre.
+
+## Configuração
+
+Adicionar ao `.env` quando a API externa estiver disponível:
+
+```env
+EXTERNAL_COMPANY_LOOKUP_ENABLED=true
+EXTERNAL_COMPANY_LOOKUP_BASE_URL=http://127.0.0.1:8000
+EXTERNAL_COMPANY_LOOKUP_API_KEY=...
+EXTERNAL_COMPANY_LOOKUP_TIMEOUT=10
+EXTERNAL_COMPANY_LOOKUP_AUTO_THRESHOLD=95
+```
+
+## Novas tabelas
+
+```text
+external_company_cache
+fiscal_customer_suggestions
+fiscal_enrichment_runs
+```
+
+A cache evita chamadas repetidas à API externa. As sugestões guardam a decisão
+pendente/aceite/rejeitada. Os runs permitem auditoria do worker periódico.
+
+## Worker
+
+```bash
+python scripts/enrich_fiscal_customers.py --incremental --limit 100
+```
+
+Para apenas criar sugestões sem auto-associação:
+
+```bash
+python scripts/enrich_fiscal_customers.py --incremental --no-auto-apply
+```
+
+## Pipeline completo
+
+```bash
+python scripts/run_reconciliation_pipeline.py --days 7 --limit 100
+```
+
+Ordem:
+
+```text
+1. enriquecer oportunidades sem cliente fiscal
+2. seed de clientes fiscais Jasmin/Odoo
+3. sincronizar documentos/vendas/envios
+4. mostrar processos candidatos na reconciliação
+```
+
+## UI
+
+Na página de Reconciliação foi adicionado:
+
+```text
+[Enriquecer oportunidades]
+```
+
+Na ficha de oportunidade foi adicionado:
+
+```text
+Sugestões fiscais
+[Enriquecer cliente fiscal]
+[Associar]
+[Rejeitar]
+```
+
+## Regra de auto-associação
+
+A auto-associação só acontece se:
+
+```text
+- oportunidade ainda não tem cliente fiscal
+- API devolve NIF + nome fiscal
+- confiança >= threshold
+- match_type forte: nif_exato, contacto_email_exato, email_principal_exato,
+  email_exato_empresa_inferida, email_principal_dominio, website_dominio
+- não existe conflito com cliente fiscal já associado
+```
+
+Outros casos ficam como sugestão para operador.