Leads

Objetivo

O Lead é a empresa que procurou a Witbiz e ainda não é Cliente. Este documento descreve como ele entra na Radhr AI, como anda pelos Estágios, quem é o dono, o que a IA faz por ele (Próxima ação, Score, Leads parecidos) e o que o Consultor faz na Home Hoje e no Lead Workspace. A conversão em Cliente aparece aqui só como gatilho; o detalhe está em funcional/clientes. A Triagem e a Pré-proposta estão em funcional/diagnosticos; a Proposta, em funcional/propostas.

Fluxo

1. Captação. O Lead nasce por um de quatro caminhos:
2. Chat do site (POST /api/chat): o Agente SDR cria o lead quando o visitante diz o nome, já em em_triagem (evento lead_criado).
3. Formulário curto do widget (POST /api/contato): nome, e-mail, empresa, mensagem e consentimento. Cria o lead em novo ou completa o existente; registra contato_site, avisa o dono por e-mail e pede a Próxima ação.
4. Link de captação: o widget lê ?ref= (indicação), ?evento= (evento) ou ?origem= / utm_source e guarda no navegador; a Origem vale para o chat e para o formulário.
5. Lead manual em /radar/leads/novo (indicação, LinkedIn, evento, workshop). Só o nome é obrigatório.
6. Triagem. No chat, o Agente SDR preenche a ficha, marca qualificado e gera a Pré-proposta (ver funcional/diagnosticos). O agente fala como a organização dona do site: nome, saudação e perfil de IA dela (ver ia/organization-intelligence).
7. Handoff. Ao fim do fluxo ou em caso sensível, o lead vai a handoff, ganha dono pela Vertical e os Consultores recebem e-mail. Dispara a cadeia handoff: leitura do site → vetor → resumo → Próxima ação.
8. Trabalho do Consultor. A Home Hoje (/radar/) mostra o que fazer; o Lead Workspace (/radar/lead/:id) concentra ficha, conversa, diagnóstico, propostas e linha do tempo.
9. Acompanhamento. Tarefas com prazo, Próxima ação com rascunho, Score e aviso de silêncio de 48 h mantêm o lead andando. Reunião marcada muda o estágio para reuniao_agendada.
10. Proposta. O envio da Proposta leva o lead a proposta_enviada (ver funcional/propostas).
11. Fechamento. Com a proposta aceita e o e-mail do contato, o botão "Converter em cliente" fecha o lead como ganho. Perda é marcada à mão como perdido. Lead fechado vira referência para Leads parecidos.

Regras de negócio

• **Origem parceiro (ADR-0014):** lead que chegou pelo link de um parceiro do Partner Program (/?ref=<código>, reconhecido pelo formato P + 7 caracteres) ou registrado pelo portal do parceiro; fica atribuído ao parceiro em parceiro_indicacoes e o estágio do lead (qualificado, handoff, reunião, proposta → qualificada; perdido → perdida) é espelhado nessa indicação. O parceiro nunca vê a triagem. Detalhes em funcional/parceiros.

• Um lead por e-mail. Chat, formulário e lead manual procuram o e-mail antes de criar. No chat, o lead provisório da conversa é fundido no existente (conversas, eventos, pré-propostas e rascunhos passam para ele) e fica o evento lead_reaproveitado. — src/agente.ts, src/contato.ts, src/radar/leads.ts
• Quem volta reabre o ciclo. Lead ganho ou perdido que volta a conversar no chat retorna a em_triagem; em andamento, mantém o estágio. — src/agente.ts
• A Origem do link nunca sobrescreve. Só vale enquanto o lead não tem origem; ?evento=<nome> guarda o nome do evento em "indicado por"; um valor fora do vocabulário (ex.: ?origem=instagram) vira outro com o texto em "indicado por". — src/agente.ts (origemDoLink), public/assets/chat.js
• Formulário exige consentimento LGPD e e-mail válido; sem isso, recusa. — src/contato.ts
• Limite por IP no chat e no formulário: 20 por minuto e 200 por dia. A conversa do chat encerra em 30 mensagens do visitante e passa para um Consultor. — src/limite.ts, src/agente.ts
• Estágios: novo → em_triagem → qualificado → handoff → reuniao_agendada → proposta_enviada → ganho | perdido. O agente só promove em_triagem → qualificado e leva a handoff; reunião marcada e envio de proposta avançam sozinhos, sem voltar um estágio já passado. — src/agente.ts, src/agenda.ts, src/propostas.ts
• **Seletor de estágio segue a máquina lead.** Na página do lead, o seletor oferece o estágio atual e só os destinos que src/estados.ts permite a partir dele. Uma transição fora da máquina, se chegar, é recusada com o motivo. Por exemplo, de novo não se vai direto para ganho, e ganho/perdido só reabrem para em_triagem. A ação mudar_estagio do Copiloto usa a mesma regra. Cada troca registra estagio_alterado com de, para e por, espelha a Oportunidade e, ao fechar (ganho/perdido), gera o vetor para Leads parecidos. A gravação é condicional ao estágio lido: se outra pessoa mudou o estágio no meio, a troca volta com o motivo em vez de sobrescrever. As transições automáticas do fluxo seguem fora da máquina: reunião marcada, envio de proposta e conversão registram estagio_alterado com automatico: true; a triagem do SDR registra os próprios eventos (qualificado, handoff). — src/estagio.ts (mudarEstagioLead), src/radar/lead.ts
• Dono no Handoff pela Vertical: growth → consultor da vertical Growth; tech, ambos ou vazio → Tech. Só atribui se o lead ainda não tem dono. Na Witbiz, o e-mail de handoff vai para Tech e/ou Growth conforme a Vertical. Em outra organização, vai ao dono do lead ou, sem dono com e-mail, aos admins dela, nunca à Witbiz. — src/agente.ts, src/db.ts (consultorParaVertical, emailsDeAviso)
• Indicação do consultor no chat. Na Witbiz, o SDR indica Alberto (tecnologia, dados, IA) ou Carolina (growth, campanhas) com o link de agenda de cada um. Em outra organização, diz que um consultor dela continua a conversa e pede o melhor dia e horário; não cita nomes nem links de agenda (a Radhr AI escolhe o dono pela Vertical). — src/agente.ts (montarSistema)
• Dono muda à mão na ficha (inclusive "sem dono"), com evento dono_alterado. — src/radar/lead.ts
• Próxima ação: vocabulário fechado (enviar e-mail, WhatsApp, ligar, propor horário, ajustar a Pré-proposta, gerar a Proposta, aguardar, marcar como perdido). Só para leads abertos; não gera outra sozinha se há uma pendente com menos de 6 h; entrada igual (hash) não chama o modelo de novo. Nasce no fim da triagem, no formulário, na abertura da Pré-proposta ou da Proposta, no silêncio, depois do detalhamento e do aceite; o Consultor pode pedir outra. O desfecho fica registrado (executada, editada, dispensada). — src/proxima-acao.ts
• A IA fala como a organização. Resumo e Próxima ação recebem a identidade e o perfil de IA da organização (resumo do negócio, cliente ideal, playbook, objeções, tom, vocabulário, instruções); a Próxima ação usa as condições comerciais do perfil (parcelas, desconto à vista, validade), e o rascunho sem dono é assinado como "Consultor de <organização>". A versão do perfil entra no hash: publicar um perfil novo faz o resumo e a Próxima ação serem refeitos na próxima geração. Termo do vocabulário proibido do perfil que aparecer no título, assunto, rascunho ou porquê da Próxima ação é removido antes de chegar ao Consultor, com o evento vocabulario_proibido_removido. — src/resumo.ts, src/proxima-acao.ts, src/perfil/contexto.ts
• Score (só lead aberto): valor potencial = Valor de referência da última Pré-proposta; temperatura (frio/morno/quente) pelos sinais de 7 dias; probabilidade 0–100 por pontos explicados (momento, porte, urgência, orçamento × valor, cargo decisor, indicação, aberturas, clique, retorno, silêncio acima de 72 h). Tudo calculado pelo código. — src/scoring.ts
• Silêncio de 48 h: de hora em hora, lead em handoff ou proposta_enviada sem nenhum evento há 48 h gera silencio_48h, uma Próxima ação e e-mail ao dono. Não repete até surgir outro evento. — src/silencio.ts
• Tarefa: título e data obrigatórios; vence no fim do dia em Brasília; vencida ou de hoje vira cartão da Home. Todo e-mail enviado pela Radhr AI cria "Cobrar retorno" em 3 dias se o lead não tiver tarefa aberta; reunião marcada cria "Preparar reunião". — src/tarefas.ts, src/radar/lead.ts, src/agenda.ts
• E-mail pela Radhr AI (Lead Workspace) sai de contato@witbiz.com.br em nome do Consultor, com resposta para o e-mail dele, em qualquer organização. O enviar_email do Copiloto usa o remetente da organização: o remetente próprio, se estiver verificado e com o recurso ligado; senão, o da Witbiz. — src/radar/lead.ts, src/copiloto.ts, src/remetente.ts (enderecoDe)
• Escrita só em lead da organização. Qualquer ação na página do lead (POST /radar/lead/:id) confere antes que o lead existe na organização da sessão; um id de outra organização volta 404, sem gravar nada. — src/radar/lead.ts
• Leads parecidos: entre os fechados, pontua setor (3), momento (2), porte (1), vertical (1) e indicação (0,5), mínimo 2 pontos, até 3. Com VOYAGE_API_KEY e a migração 0011, usa embeddings e mostra "NN% parecido". — src/parecidos.ts, src/embeddings.ts
• Conversão só com proposta aceita (ou aceite registrado no mesmo ato) e e-mail do contato. — src/clientes.ts (faltaParaConverter)
• LGPD: exportar e anonimizar são só de admin; anonimizar é irreversível e mantém valores, estágios e a trilha com [removido a pedido do titular]. — src/lgpd.ts, src/radar/lead.ts

Casos de uso

• Lead chegou pelo chat e pediu desconto. O agente faz Handoff com motivo negociacao; o dono recebe o e-mail e o cartão "Fazer o primeiro contato" aparece na Home depois de 4 h sem registro de contato.
• Indicação por WhatsApp. O Consultor cria o lead em /radar/leads/novo com origem indicacao e quem indicou. Se o e-mail já existir, cai no lead existente.
• Link para um evento. Compartilhe novo.witbiz.com.br/?evento=nome-do-evento (ou em QR code); quem conversar ou preencher o formulário chega com origem evento.
• Visitante saiu antes de dizer o nome. A lista de leads mostra "Triagens sem identificação" (duas ou mais mensagens); em /radar/conversa/:id dá para criar o lead com a conversa anexada.
• Proposta enviada e silêncio. Depois de 48 h sem sinal, chega o e-mail de silêncio com a sugestão da IA; o rascunho está pronto no Lead Workspace.
• Titular pede os dados. O admin baixa o JSON em "LGPD · dados do titular" (evento dados_exportados); se pedir eliminação, anonimiza.

Telas

• **/radar/ — Hoje (AI Command Center).** Briefing, números-filtro, fila única de prioridades (Próxima ação, tarefas, responder interesse, primeiro contato, confirmar estimativa, cobrar proposta, converter em cliente, contratos e riscos) e trilho de sinais. Por padrão mostra os seus leads e os sem dono; ?todos=1 mostra todos. "Pular" registra acao_dispensada e pode ser desfeito. Com a flag welcome_experience (ADR-0013), o primeiro acesso é levado a /radar/boas-vindas antes da Home, e o cartão "Ativação N% · Adoption Score" aparece até o checklist fechar (ver funcional/boas-vindas).
• **/radar/leads — Leads.** Contagem por estágio, busca por nome, empresa ou e-mail, filtros de vertical e dono ("meus e sem dono" é o padrão), Score, Valor de referência e triagens sem identificação.
• **/radar/leads/novo — Novo lead.** Formulário do lead manual.
• **/radar/lead/:id — Lead Workspace.** Cabeçalho com estágio, Score, risco e botões (WhatsApp, e-mail, marcar reunião, abrir proposta). Abas: Visão geral (Próxima ação, Cliente/converter, Tarefas, atividade e notas), Conversa, Diagnóstico (Pré-propostas, site, Reunião → CRM), Propostas (editor e Estratégia da proposta) e Linha do tempo. Ao lado: Resumo da IA, Ficha (estágio e dono) e Leads parecidos.
• **/radar/conversa/:id — Triagem sem identificação.** Transcrição e "Criar lead a partir desta conversa".

Permissões

• Anônimo (visitante do site): conversa no chat e envia o formulário; não vê nada da Radhr AI.
• Consultor: vê e age em todos os leads da organização (a lista só filtra, não restringe): estágio, dono, notas, tarefas, e-mail, WhatsApp, reunião, Próxima ação, resumo, leitura do site e conversão.
• Admin: tudo do consultor, mais exportar e anonimizar (LGPD).
• Financeiro e leitura: consultam leads, a Home e a linha do tempo, sem alterar nada. Notas, estágio, tarefas, e-mails, gestos da fila e novo lead são recusados com 403 pelo middleware (src/radar/permissoes.ts).
• Plano: o envio de WhatsApp pelo número da organização exige o plano Profissional ou superior (whatsapp em src/planos.ts); sem ele, fica o link wa.me. O Copiloto, que também age em leads, é do Profissional em diante. Com o Limite de IA atingido, resumo e Próxima ação não chamam o modelo.

Perguntas frequentes

O lead ficou sem dono. Por quê? O dono só é atribuído no Handoff (pela Vertical) ou à mão. Lead criado pelo formulário ou ainda em triagem fica sem dono e aparece em "meus e sem dono" para todos os Consultores. Atribua pela ficha.

Mudei o estágio para "ganho" à mão. Virou cliente? Não. O seletor só muda o estágio (quando a máquina permite) e espelha a Oportunidade. Cliente nasce pelo "Converter em cliente", que exige proposta aceita e e-mail; ele próprio fecha o lead como ganho.

Por que a Próxima ação não mudou depois que cliquei em "Gerar outra sugestão"? O botão força uma nova geração. Se a IA falhar, se o lead estiver fechado ou se o Limite de IA foi atingido, o aviso diz que não foi possível gerar.

O Score diz 40. É a chance real de fechar? É uma heurística de pontos, com os fatores mostrados ao lado do número. Ainda não é calibrada com ganhos e perdidos; use para priorizar, não para prever.

O aviso de silêncio vai repetir todo dia? Não. Depois de silencio_48h, o lead só é avisado de novo quando surgir outro evento seguido de mais 48 h de silêncio.

O resumo mudou de tom depois que o admin publicou o perfil da organização. É esperado? Sim. A versão do perfil faz parte do hash do resumo e da Próxima ação; com perfil novo, a próxima geração chama o modelo de novo com o contexto atualizado.

Por que a Próxima ação veio sem uma palavra que a IA costuma usar? O termo está no vocabulário proibido do perfil da organização e foi removido do texto. A linha do tempo do lead registra vocabulario_proibido_removido com os termos.

Posso apagar um lead? Não há exclusão. O admin pode anonimizar (LGPD): some o que identifica a pessoa, ficam valores, estágios e a trilha.