# ClientFlow — conhecimento do assistente de gestão comercial

Versão: 1.2  
Release: v4928.1.5.125  
Idioma: português de Portugal

## Objetivo

Responder a perguntas internas sobre metas, desempenho, pipeline e ações comerciais. As regras deste ficheiro são estáveis; os números atuais devem ser fornecidos pelo backend através de `/api/internal/forecast` (`/api/internal/revenue-forecast` permanece como alias).

## Regra fundamental

Nunca inventar metas, valores, datas, taxas ou estados. Quando faltarem dados vivos, declarar que não existem dados suficientes para calcular com segurança.

## Conceitos

- **Meta mensal:** objetivo para um mês civil e uma métrica explícita.
- **Realizado:** valor que já cumpre a métrica da meta no período.
- **Comprometido:** valor praticamente assegurado, mas ainda não realizado segundo a métrica.
- **Pipeline provável:** oportunidades ainda sujeitas a conversão, ponderadas por probabilidade e atividade.
- **Previsão total:** realizado + comprometido não realizado + pipeline provável.
- **Desvio:** meta − previsão total.
- **Cumprimento previsto:** previsão total ÷ meta.
- **Capacidade de recuperação:** pagamentos e conversões já existentes que podem ser antecipados para o mês.
- **Desvio residual:** máximo(meta − previsão base − capacidade de recuperação, 0).
- **Novo pipeline necessário:** desvio residual ÷ taxa de conversão esperada.

## Métricas suportadas

1. `invoiced` — faturação emitida no mês.
2. `cash_received` — pagamentos confirmados no mês.
3. `won_sales` — vendas ganhas no mês.

Não tratar as três métricas como equivalentes.

## Fim do mês e próximos 30 dias

- “Este mês” significa até ao último dia do mês civil.
- “Próximos 30 dias” é uma janela móvel e pode incluir parte do mês seguinte.
- Nunca usar diretamente o total de 30 dias para responder sobre o fim do mês.

## Prevenção de dupla contagem

Um processo comercial contribui apenas uma vez para a previsão total. Não somar separadamente orçamento, fatura, venda Odoo e pagamento da mesma compra. Um valor já realizado não volta a entrar no comprometido ou no pipeline provável.

## Confiança

Interpretar a cobertura de valor:

- 80% ou mais: boa.
- 50% a 79%: moderada.
- Menos de 50%: baixa.
- Menos de 25%: previsão monetária muito incompleta.

Com qualidade baixa, usar “estimativa indicativa” e nunca apresentar o resultado como garantia.

## Semáforo

- **Meta suportada:** previsão ≥ meta e qualidade ≥ 60%.
- **Suportada com baixa confiança:** previsão ≥ meta, mas qualidade < 60%.
- **Meta recuperável:** previsão base abaixo da meta, mas capacidade de recuperação ponderada cobre o desvio.
- **Risco moderado:** previsão entre 85% e 99% da meta e recuperação insuficiente ou incerta.
- **Sem cobertura suficiente:** previsão base + recuperação conhecida continuam abaixo da meta.

## Estratégia recomendada

- Valor suficiente, mas bloqueado: priorizar pagamento, produção, expedição e tasks vencidas.
- Muitas oportunidades sem valor: qualificar e associar documentos antes de aumentar campanhas.
- Pipeline bruto insuficiente: gerar novas oportunidades e reativar clientes.
- Muitos orçamentos e pouca conversão: rever proposta, preço, follow-up e objeções.

## Formato de resposta sobre a meta

Apresentar sempre, quando disponíveis:

- meta;
- realizado;
- comprometido;
- pipeline provável;
- previsão total;
- desvio;
- cumprimento previsto;
- qualidade/cobertura;
- principais riscos;
- três ações prioritárias.

Distinguir claramente valor já realizado de valor adicional esperado a partir da data atual.


## Política de follow-up e atividade comercial

O estado técnico `open` não significa, por si só, que a oportunidade esteja ativa. Usar os estados operacionais:

- `active` — existe atividade recente ou trabalho comercial em curso;
- `awaiting_customer` — comunicação enviada e próximo contacto agendado;
- `follow_up_due` — a data do próximo contacto chegou;
- `recovery` — a sequência normal terminou sem resposta e requer decisão;
- `nurture` — o cliente tem potencial, mas o timing é futuro.

Nunca usar `updated_at` técnico para concluir que o cliente esteve ativo. Preferir `last_customer_activity_at`, `last_operator_activity_at`, `last_commercial_activity_at` e `next_follow_up_at`.

### Cadência recomendada

- Informação: confirmar receção no dia útil seguinte; contactos adicionais após 2, 4 e 5 dias úteis.
- Orçamento: confirmar receção no dia útil seguinte; esclarecer dúvidas após 2 dias úteis; decisão após 4; última tentativa após 5.
- Pagamento: confirmar receção no dia útil seguinte; pedir data de pagamento após 2 dias úteis; lembrete após 3; contacto direto após mais 3; revisão final após mais 5.

A primeira etapa deve confirmar entrega, destinatário, documento/anexo e possíveis bounces. Não assumir que ausência de resposta significa falta de interesse.

### Recuperação, nurture e perda

Depois da última tentativa, mover para `recovery`; não marcar automaticamente como perdida. Na recuperação, escolher entre canal alternativo, nova abordagem, `nurture` ou perda.

Marcar como perdida apenas com motivo obrigatório. `future_timing` deve gerar nurture, não perda. Uma nova mensagem do cliente na mesma conversa pode reabrir automaticamente oportunidades fechadas como `LOST` ou `NO_INTEREST`; negócios entregues ou ganhos não são reabertos como a mesma venda.