Lead Source Intelligence — canais, atribuição e inteligência de origem

Objetivo

Responder, com os números do próprio funil, quais canais geram mais vendas, mais receita, melhores clientes, melhor ROI, menor CAC e maior retenção — e quais campanhas merecem mais investimento. O motor é puro e determinístico (src/origens/metricas.ts); a IA (fonte_analista) só interpreta o snapshot e nunca inventa número. O desenho está em docs/radar/lead-source-intelligence.md.

Fluxo

1. Carregar (carregarEntrada): leads da janela (30/90/180/365 dias) e do período anterior de mesma duração, toques (lead_fontes), eventos de resposta e de ganho, clientes, contratos assinados, custos (canal_custos), ICP do perfil e integrações em erro.
2. Calcular (calcularOrigens): por canal (primeiro toque) e por campanha — leads, qualificados, propostas, fechamentos, receita atribuída pelo modelo de atribuição, custo, conversão, CAC, ROI, LTV, retenção, churn, payback, tempo de resposta e de fechamento, tendência, Channel Health Score e Source Quality Score; comparação entre canais; insights por regra; anomalias; recomendações de orçamento; forecast 30/60/90; série diária.
3. Mostrar (/radar/origens): cabeçalho com os totais, filtros de período e de modelo, anomalias, recomendações, tabela por canal, campanhas, gráfico, Revenue Attribution, comparação, forecast, insights/alertas (regra e IA, com dispensar), pergunta à IA, leitura do analista, configuração da atribuição e registro de custos.
4. Persistir (cron diário, flag lead_intelligence): canal_metricas (snapshot por dia × canal × campanha), origem_previsoes, origem_insights (deduplicados pela chave; os da regra que deixam de valer ficam resolvido; anomalias altas geram origem_anomalia).
5. Analisar (cron semanal ou "Analisar agora"): fonte_analista lê o snapshot e devolve leitura, insights e recomendações validados; fallback por regra; insights da IA gravados com chave ia:.
6. Perguntar: a regra responde ("mais receita", "mais clientes", "melhor ROI", "menor CAC", "mais fiéis", "campanha", "parceiros", "onde investir", "deteriorando"); fora da regra, o modelo responde só com o snapshot.

Regras de negócio

• Receita = contratos assinados dos clientes que nasceram dos leads (fallback contratado_total); custo = registrado (manual) ou importado; sem custo, CAC/ROI/payback ficam em branco.
• Atribuição: first touch, last touch, linear, por posição (40/20/40; padrão) e orientado por dados (proporcional à conversão de cada canal); modelo e janela padrão por organização; troca ad hoc pela URL.
• Primeiro toque define canal/campanha do lead e as contagens; a receita segue o modelo; leads sem toque (antes da
• ganham um toque sintético pelo canal legado.
• Canal com menos de 3 leads: Health e Quality limitados a 50 e sem recomendação além de "colete mais dados".
• Health (0–100): quantidade 15, conversão 25, receita 20, tempo de fechamento 10, retenção 15, expansão 5, churn 10. Quality (0–100): fit com ICP 30, fechamento 25, retenção 15, engajamento 10, receita 15, indicações 5.
• Recomendações: interromper (custo, 0 fechamentos, < 3 leads) · reduzir (ROI < 0) · aumentar (ROI ≥ 100% e Health ≥ 60) · escalar (sem custo convertendo acima da média, ou crescendo ≥ 30% com ROI positivo) · manter.
• Anomalias com ≥ 28 dias de série: canal parado, queda abrupta (< 60% da média anterior), queda de conversão, investimento sem retorno, campanha sem retorno, integração inoperante.
• A IA: canais só do snapshot, números só do snapshot, ações só do vocabulário; senão, regra.
• Fora do plano (Essencial) a tela responde 402 e aponta Métricas.

Casos de uso

• "Qual canal gera mais receita?" — a regra responde com o canal e o valor atribuído, sem chamar o modelo.
• Decidir o orçamento do mês: registra os custos por canal, lê as recomendações e a comparação (menor CAC, maior ROI, menor payback).
• Campanha que parou de render: anomalia "campanha sem retorno" e recomendação "reduzir"; o canal aparece em queda.
• Parceiros: o canal parceiro lista os códigos dos parceiros como campanhas com receita atribuída.
• Relatório ao conselho: JSON de /radar/origens (porCanal, porCampanha, previsões) alimenta a suíte executiva.

Telas

• /radar/origens?dias=&modelo= (+ JSON por Accept: application/json ou /dados.json); /radar/origens/canal/<canal>?campanha=; POSTs config, custos, perguntar, analisar, insight/<id>; /lead-intelligence (atalho).
• Trilho: item "Origens" no grupo Inteligência; o dashboard do Integration Hub mostra o resumo de 30 dias.

Permissões

• origens.ler (todo papel: master, owner, admin, manager, sales, operation, financial, viewer); origens.configurar (owner, admin, manager, financial: modelo de atribuição e custos); origens.perguntar (owner, admin, manager: perguntas e "Analisar agora"). Nos papéis legados, leitura e financeiro só consultam.
• Flag lead_intelligence: Profissional, Escala, interno e teste.

Perguntas frequentes

• Por que o CAC está em branco? Nenhum custo registrado para o canal na competência; registre em "Custos por canal".
• Por que a retenção está em branco? Nenhum cliente do canal tem 90 dias de casa ainda.
• O forecast diz "insuficiente". Menos de 5 leads ou menos de 7 dias de série; com 28 dias e 10 leads entra a tendência com sazonalidade.
• A leitura da IA diz "por regra". O modelo não respondeu ou devolveu número fora do snapshot; a regra entrou.
• Posso mudar o modelo só para uma análise? Sim, pela URL (?modelo=last_touch); o padrão fica na configuração.