Import ClientFlow production v4928.1.5.132.4

RELEASE_NOTES_v4928_1_5_122_STABILIZATION_FORECAST.md

@@ -0,0 +1,108 @@
+# 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:
+
+```bash
+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:
+
+```text
+valor ponderado = valor da oportunidade × probabilidade da fase × fator de atividade
+```
+
+Fontes de valor, por prioridade:
+
+1. documento Jasmin atual/principal;
+2. linhas da oportunidade;
+3. `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
+
+```bash
+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
+```