# 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.