Skip to main content

Módulo 06: Leads & Clientes

Status: Documentado

Domínio: ver Domínio/Entidade: Lead e Domínio/Entidade: Cliente

ATA de Referência: (Ainda não aprovada)

1. Visão Geral da Regra​

O módulo de Leads & Clientes governa o início da jornada comercial: a captação, qualificação e conversão de contatos.

  • Um Lead é um contato inicial, sem vínculo formal. Dados podem estar incompletos.
  • Ao ser qualificado (CPF/CNPJ e contato validados), o Lead é convertido em Cliente, habilitando criação de propostas e vínculos com veículos.
  • A conversão é irreversível: um Lead convertido não retorna ao funil de Leads.

2. Ciclo de Vida do Lead​

2.1 Entradas de Leads​

Um lead pode entrar no sistema via:

  1. Cadastro manual — pelo Consultor logado (atribuído automaticamente ao próprio).
  2. API / Webhook — landing page, Facebook Lead Ads (atribuído via round-robin).
  3. Importação de planilha — Admin ou Gestor (atribuído via round-robin ou consultor específico).

2.2 Regras de Progressão de Status​

TransiçãoPré-condição obrigatória
NOVO → EM_ANDAMENTOPrimeira interação registrada (ligação, WhatsApp, e-mail ou reunião)
EM_ANDAMENTO → QUALIFICADONome + telefone válido + CPF/CNPJ informado (sem validação algorítmica nesta etapa)
QUALIFICADO → CONVERTIDOCPF/CNPJ válido algoritmicamente + endereço completo
EM_ANDAMENTO → PERDIDOMotivo de descarte obrigatório
PERDIDO → EM_ANDAMENTOAção explícita de repescagem pelo consultor

3. Timeout e Alertas (Governados pelo Tenant)​

As configurações abaixo são definidas por tenant (ver dominio/tenant.md → Configurações):

ConfiguraçãoComportamento
lead_alerta_ociosidade_diasGera alerta para o consultor e seu gestor após X dias sem interação
lead_expiracao_diasMove automaticamente para EXPIRADO leads NOVO ou EM_ANDAMENTO sem interação após Y dias

[!NOTE] O descarte automático por expiração registra o motivo "Expirado por inatividade" na timeline do lead.

4. Unicidade e Duplicidade​

  1. Bloqueio de duplicidade: O sistema verifica CPF/CNPJ e/ou Telefone/E-mail para evitar leads duplicados no mesmo tenant.
  2. Conflito de carteira ativa: Se um consultor tenta cadastrar um lead com CPF/CNPJ já ATIVO na carteira de outro consultor do mesmo tenant, o cadastro é bloqueado e o gestor de ambos os consultores é alertado.
  3. Repescagem de descartados: Um lead PERDIDO ou EXPIRADO pode ser reaberto pelo mesmo ou por outro consultor, criando novo ciclo de vida. O histórico anterior é preservado integralmente.

5. Distribuição Automática (Round-Robin)​

  • Leads originados de integrações (API/Webhook, Importação) são distribuídos em round-robin para a equipe ou para um consultor específico (configurável).
  • O algoritmo deve respeitar disponibilidade e horário de trabalho do consultor.
  • Leads importados em lote: a atribuição em round-robin ocorre sequencialmente no momento da importação.

[!NOTE] A implementação completa do round-robin com disponibilidade e horário de trabalho é considerada um épico técnico independente.

6. Regras do Cliente​

  1. Um Cliente é sempre originado de um Lead — não é possível criar um Cliente diretamente.
  2. O tipo_pessoa é herdado do Lead e é imutável após a conversão.
  3. O CPF/CNPJ é único por tenant — dois clientes não podem compartilhar o mesmo documento no mesmo tenant.
  4. Um Cliente pode ter múltiplos Veículos ativos simultaneamente, cada um com seu próprio contrato.
  5. O status BLOQUEADO impede geração de novas propostas, mas não cancela contratos existentes.
  6. Após a primeira proposta contratada, o Cliente pode ser sincronizado com o ERP (ex: Hinova).
  7. A visibilidade segue a regra de silo: apenas o consultor responsável e os gestores acima dele na hierarquia enxergam o cliente.

7. Gestão de Carteira​

  • Redistribuição: Gestor ou Gerente pode selecionar N leads de um consultor e transferir para outro (ex: férias, desligamento). Ação registrada na timeline de cada lead transferido.
  • Visibilidade: Gestor vê todos os leads/clientes dos consultores subordinados. Consultor vê apenas sua própria carteira.

8. Regras Inegociáveis​

[!IMPORTANT] A conversão de Lead para Cliente é irreversível. Uma vez convertido, o Lead não retorna ao Kanban de Leads. A entidade de gestão passa a ser o Cliente.

[!WARNING] Validação algorítmica de CPF/CNPJ na conversão é obrigatória. O dado será utilizado em contratos e na consulta de tabela FIPE (Módulo 07). Um documento inválido deve bloquear a conversão com mensagem de erro clara.