ClientFlow v4928.1.5.122 — Stabilization & Revenue Forecast

Data: 2026-07-14

Objetivo

Consolidar a versão remota após os hotfixes v4928.1.5.x, corrigir regressões de workflow observadas em produção e introduzir uma previsão comercial auditável de 30/60/90 dias.

Correções

Orçamento enviado sem documento associado

Uma task SEND_QUOTE concluída passa a contar como evidência de que o orçamento foi enviado, independentemente de o documento Jasmin já estar associado.

Nestes casos, a próxima ação passa a ser:

RECONCILE_DOCUMENTS
Associar orçamento enviado

O motor deixa de sugerir CREATE_JASMIN_QUOTE, evitando orçamentos duplicados.

Follow-ups alinhados com a fase

SEND_PROFORMA passa a agendar FOLLOW_UP_PAYMENT.
Em WAITING_PAYMENT, FOLLOW_UP_QUOTE e FOLLOW_UP_PROFORMA são convertidos em FOLLOW_UP_PAYMENT.
Follow-ups de orçamento são encerrados quando existe uma task mais avançada, como SEND_INVOICE, CONFIRM_PAYMENT, PREPARE_ORDER ou CREATE_SHIPMENT.
O agendador bloqueia novas cascatas de orçamento quando a oportunidade já avançou para fatura, pagamento ou operação.

Script de auditoria/reparação:

python scripts/repair_stale_followups.py
python scripts/repair_stale_followups.py --apply

O script é dry-run por defeito e não envia mensagens.

Proteção do enriquecimento fiscal

Um resultado externo com match_type=nif_exato deixa de ser autoaplicado quando o nome empresarial devolvido contradiz o nome empresarial presente na fonte operacional.

confiança máxima: 70%;
source_name_conflict=true no payload da sugestão;
autoaplicação bloqueada;
decisão fica disponível para revisão manual.

Segurança de produção

Em prod, production e staging:

CLIENTFLOW_ADMIN_TOKEN é obrigatório;
UI admin e API interna falham fechadas se a autenticação não estiver configurada;
admin_token por query string é desativado;
lookup externo ativo exige EXTERNAL_COMPANY_LOOKUP_API_KEY.

Configuração e testes

restaurado .env.example sem segredos;
suíte final: 476 testes passados;
compileall sem erros.

Previsão comercial de receitas

Novos endpoints:

/finance/forecast
/financeiro/previsao
GET /api/internal/revenue-forecast?limit=1000

Modelo:

valor ponderado = valor da oportunidade × probabilidade da fase × fator de atividade

Fontes de valor, por prioridade:

documento Jasmin atual/principal;
linhas da oportunidade;
opportunities.value_amount.

A probabilidade usa taxas históricas quando existem pelo menos oito oportunidades resolvidas que passaram pela fase. Sem amostra suficiente, usa probabilidades explícitas por fase.

O fator de atividade considera:

recência da oportunidade;
tasks vencidas;
tasks concluídas recentemente;
conflitos fiscais/identidade.

A página apresenta pipeline bruto e ponderado em:

até 30 dias;
31–60 dias;
61–90 dias;
mais de 90 dias.

Esta funcionalidade é uma previsão comercial. Não representa receita contabilística, faturação reconhecida ou tesouraria.

Aplicação recomendada

python -m compileall -q app scripts tests
pytest -q
python scripts/repair_stale_followups.py
python scripts/repair_stale_followups.py --apply
sudo systemctl restart clientflow-api

3.3 KiB Raw Permalink Blame History Unescape Escape