# ClientFlow v4928.1.5.123 — Meta e desempenho comercial

Data: 2026-07-16

## Objetivo

Transformar a previsão comercial numa ferramenta de decisão para responder:

- quanto já conta para a meta;
- quanto está comprometido;
- quanto ainda depende de conversão;
- se a meta mensal está suportada;
- que ações devem ser executadas para reduzir o desvio.

## Funcionalidades

### Meta mensal persistente

Nova tabela aditiva `sales_targets`, criada automaticamente no arranque.

A meta é configurável por:

- mês;
- métrica;
- valor;
- moeda.

Métricas disponíveis:

- `invoiced` — faturação emitida;
- `cash_received` — pagamentos confirmados;
- `won_sales` — vendas ganhas.

### Separação sem dupla contagem

O dashboard distingue:

- realizado no mês;
- comprometido ainda não realizado;
- pipeline provável;
- valor já realizado noutro período.

Uma oportunidade já realizada para a métrica escolhida deixa de ser somada novamente no pipeline futuro.

### Horizonte correto

São apresentados separadamente:

- até ao fim do mês civil;
- próximos 30 dias adicionais;
- buckets 30/60/90 dias na API.

### Semáforo e desvio

Estados:

- meta suportada;
- suportada com baixa confiança;
- risco moderado;
- meta não suportada;
- meta não configurada.

A qualidade dos dados impede que uma previsão com baixa cobertura apareça como verde sem ressalvas.

### Diagnóstico e ações

O dashboard identifica:

- oportunidades sem valor;
- pagamentos pendentes;
- tasks vencidas;
- concentração da previsão;
- desvio para a meta;
- novo pipeline estimado necessário.

Também produz uma lista das 10 ações com maior impacto.

### Cenários

- conservador;
- provável;
- otimista.

### Probabilidades mais estáveis

Taxas históricas deixam de substituir integralmente a probabilidade padrão com apenas oito casos. É aplicada suavização entre histórico e prior da fase.

### Conhecimento para assistente OpenAI

Incluído:

`app/business_knowledge/sales_management_knowledge.md`

O ficheiro define conceitos, prevenção de dupla contagem, interpretação da qualidade e formato recomendado de respostas. Os números vivos devem vir da API interna.

## Rotas

UI:

- `/finance/forecast`
- `/financeiro/previsao`

Guardar meta:

- `POST /finance/forecast/target`

API:

- `GET /api/internal/revenue-forecast?month=2026-07&metric=invoiced`

## Validação

```text
python -m compileall -q app scripts tests
483 passed
```

## Instalação

A release preserva `.env`, `.venv`, dados e logs quando aplicada pelo procedimento `rsync` usado nas versões anteriores.

Após instalar:

```bash
cd /mnt/ssd/home/plx/clientflow_backend
source .venv/bin/activate
python -m compileall -q app scripts tests
pytest -q
sudo systemctl restart clientflow-api
curl -I http://127.0.0.1:8020/finance/forecast
```

A tabela `sales_targets` é criada automaticamente no arranque.
