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