Inteligência comercial

🛂 Permissões: intelligence.view, intelligence.manage, intelligence.whatsapp 🔒 Plano: requer commercial_intelligence_enabled. Disparo automático por WhatsApp requer adicionalmente whatsapp_outbound_enabled. 📍 Caminho: Visão Geral → Inteligência Comercial

A inteligência comercial transforma a base de pedidos em ações. Ela combina três motores:

1. Health Score (RFM) — segmentação dos clientes.
2. Recomendações — cross-sell e reposição.
3. Alertas e Tarefas — fila de ações para o vendedor (com gatilho opcional pelo WhatsApp).

Quando o módulo "liga"

A primeira execução acontece logo após o plano ser ativado, sobre os pedidos já existentes. A partir daí, rodam diariamente workers que recalculam:

• Scores RFM dos clientes.
• Ciclos de compra por (cliente × produto).
• Pares de produtos comprados juntos (market basket).
• Alertas e tarefas novos.

Configurações do tenant

Em Inteligência Comercial → Configurações (permissão intelligence.manage):

Campo	Default	Descrição
Mín. de pedidos para detectar ciclo	3	Quantos pedidos um cliente precisa ter para o sistema estimar o ciclo.
Mín. de compras de um produto para ciclo	2	Quantas vezes o cliente precisa ter comprado o mesmo produto para o ciclo daquele item ser calculado.
Período de análise (dias)	180	Janela retroativa usada nos cálculos.
WhatsApp automático	desligado	Se ligado, o sistema dispara mensagens proativas com os templates definidos.

Health Score e segmentos (RFM)

Cada cliente recebe três notas (1–5):

• Recency — quão recente foi a última compra.
• Frequency — frequência de pedidos.
• Monetary — valor total gasto.

E um health_score 0–100 + segmento:

Segmento	Tradução prática
champion	Melhores clientes — compram muito, gastam muito, recente.
loyal	Fiéis.
potential_loyalist	Tem cara de fiel — incentive.
new_customer	Recém-chegado.
promising	Promissor — investiu pouco, mas tem potencial.
needs_attention	Esfriando.
about_to_sleep	Prestes a dormir.
at_risk	Em risco.
cant_lose	Cliente importante esfriando — não pode perder.
hibernating	Adormecido.
lost	Provavelmente perdido.

A tela mostra a distribuição por segmento e permite filtrar a base.

Recomendações

Cross-sell

Pares (A, B) de produtos com alta co-ocorrência (lift). Quando um cliente compra A, o sistema gera uma recomendação para B.

Reposição

Calculada por (cliente, produto): se o cliente costuma pedir a cada N dias e está se aproximando, gera recomendação de reposição.

Ambas têm um score (0–100). Estados:

Status	Significado
active	Disponível para acionar.
sent	Já foi enviada uma mensagem.
dismissed	Descartada.
converted	Cliente comprou após a recomendação.

Alertas

Tipos automáticos:

• purchase_overdue — Cliente atrasou em relação ao ciclo.
• abandoned_cart — Carrinho abandonado.
• ticket_decrease — Ticket médio caiu vs. histórico.
• cross_sell_opportunity — Match com produto complementar.
• segment_downgrade — Cliente caiu de segmento.
• reactivation_opportunity — Cliente lost / hibernating dando sinal de vida.

Cada alerta tem prioridade (1–5), mensagem, dedup_key (1 alerta por tipo por cliente por semana).

Status: pending → acknowledged → acted_on (ou dismissed).

Tarefas (SalesTasks)

A partir de um alerta, o sistema cria (ou o vendedor cria manualmente) uma tarefa:

Campo	Descrição
Tipo	follow_up, reactivation, upsell, cross_sell, check_in, custom.
Atribuída a	Vendedor responsável.
Prazo	Data limite.
Notas de resultado	Preenchidas após executar.

Tarefas aparecem na fila do vendedor — ele acciona, registra o resultado e fecha.

WhatsApp proativo

Templates configuráveis em Inteligência Comercial → WhatsApp (permissão intelligence.whatsapp).

Tipos de template:

• replenishment — reposição.
• cross_sell
• reactivation
• general
• follow_up
• custom

Cada template tem corpo (com placeholders como {nome}, {produto}).

Triggers de disparo:

• manual — vendedor envia da fila de tarefas.
• auto_cycle — automático quando o ciclo de reposição estiver no ponto e auto_whatsapp_enabled = true.
• task_action — disparado ao executar uma tarefa.

Mensagens enviadas ficam em WhatsAppOutboundMessage com status: pending → sent → delivered → read (ou failed).

Pré-requisito para qualquer disparo: número WhatsApp conectado (WhatsApp).

Como ativar passo a passo

1. Confirme o plano — commercial_intelligence_enabled = true (peça upgrade se preciso).
2. Acesse Visão Geral → Inteligência Comercial.
3. Em Configurações, valide os parâmetros padrão (min_orders, analysis_period_days).
4. Aguarde o primeiro batch rodar (até 24h após ativação).
5. Explore as abas:
   • Visão Geral — distribuição por segmento, KPIs.
   • Clientes — tabela com score e segmento.
   • Recomendações — fila de cross-sell e reposição.
   • Alertas — alertas pendentes.
   • Tarefas — fila de ações.
   • WhatsApp — templates e histórico de mensagens.
6. (Opcional) Configure templates e habilite WhatsApp automático.

Boas práticas

• Comece com WhatsApp automático desligado — opere algumas semanas só com tarefas manuais para entender o volume.
• Crie templates curtos e personalizados — o cliente sente quando é texto enlatado.
• Revise tarefas semanalmente com a equipe — alimenta o RFM com sinais reais.
• Use o filtro por segmento para campanhas (ex.: cupom específico para at_risk).
• O período de análise padrão (180 dias) cobre a maioria dos negócios; aumente para sazonais (anual).
• Antes de enviar campanha em massa pelo WhatsApp, faça teste A/B com pequena amostra — abuso queima o número.