99 lines
2.2 KiB
Markdown
99 lines
2.2 KiB
Markdown
# 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.
|