Import ClientFlow production v4928.1.5.132.4

CLIENTFLOW_SALES_MANAGEMENT_KNOWLEDGE_v1_2.md

@@ -0,0 +1,114 @@
+# 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.