clientflow_backend/RELEASE_NOTES_v4926_4.md

ClientFlow v4926.4 — Email identity assisted enrichment

Objetivo

Integrar a extração de identidade de email no fluxo operacional de enriquecimento fiscal assistido, sem auto-aplicação agressiva.

Principais alterações

• Configuração separada para o modelo de email identity:
  • EMAIL_IDENTITY_LLM_MODEL
  • EMAIL_IDENTITY_LLM_FALLBACK_MODEL
  • EMAIL_IDENTITY_LLM_TIMEOUT_SECONDS
  • EMAIL_IDENTITY_LLM_MAX_BODY_CHARS
• Fallback automático no extractor:
  • tenta o modelo principal;
  • se o resultado ficar fraco/sem empresa em domínio empresarial, tenta o fallback.
• Nova revisão assistida de identidade:
  • email_identity_review_for_opportunity()
  • corre mesmo quando a oportunidade já tem cliente fiscal, para detetar conflitos.
• Novo enriquecimento assistido por identidade:
  • assist_email_identity_enrichment()
  • cria sugestões pendentes a partir da empresa extraída;
  • deteta conflito entre empresa mencionada no email e cliente fiscal já associado;
  • por defeito não auto-aplica.
• UI do detalhe da oportunidade:
  • bloco “Identidade extraída do email”;
  • mostra pessoa, empresas mencionadas, domínio, morada, telefones, evidências e modelo;
  • botão “Reextrair identidade”;
  • botão “Procurar cliente fiscal por identidade”.
• Batch validation:
  • aceita --fallback-model;
  • grava llm_model e fallback_used no CSV/JSONL.

Configuração recomendada

EMAIL_IDENTITY_EXTRACTION_ENABLED=true
EMAIL_IDENTITY_EXTRACTION_USE_LLM=true
EMAIL_IDENTITY_LLM_MODEL=qwen/qwen3-235b-a22b-2507
EMAIL_IDENTITY_LLM_FALLBACK_MODEL=qwen/qwen3-max
EMAIL_IDENTITY_LLM_TIMEOUT_SECONDS=20
EMAIL_IDENTITY_LLM_MAX_BODY_CHARS=3500

Testes

• python -m compileall -q app scripts
• pytest -q
• Resultado local: 188 passed