clientflow_backend/CLIENTFLOW_SALES_MANAGEMENT_KNOWLEDGE_v1_2.md

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.