Entidade: Lead

Tipos e formatos: ver Domínio/Tipos e Formatos Comuns

Camada: Domínio — Define o que o objeto é, seus atributos e relacionamentos.

Regras de comportamento: ver Domínio/Mapeamento de Domínio e Regras de Negócio

---

1. Definição

Um Lead é um potencial cliente recém-captado — alguém que demonstrou interesse, mas ainda não teve documentação validada. O lead é o ponto de entrada do funil de vendas do CRM. Ao qualificar um lead, ele é promovido à entidade Cliente.

Um lead pode ser Pessoa Física (PF) ou Pessoa Jurídica (PJ). No caso de PJ, o veículo a ser protegido pertence à empresa, e os campos de identificação mudam conforme o tipo.

---

2. Atributos Principais

Campo	Tipo	Obrigatório	Notas
id	UUID	Sim	Gerado pelo sistema
tenant_id	UUID	Sim	FK → Tenant
consultor_id	UUID	Sim	FK → Usuário responsável
tipo_pessoa	enum	Sim	PESSOA_FISICA ou PESSOA_JURIDICA
nome	string	Sim	Nome completo (PF) ou nome do contato/representante (PJ)
razao_social	string	Sim*	Razão social. Obrigatório se tipo_pessoa = PESSOA_JURIDICA
cpf_cnpj	string	Não	CPF (PF) ou CNPJ (PJ). Exigido na qualificação
telefone	string	Sim*	Formato E.164. Obrigatório se email ausente
email	string	Sim*	Obrigatório se telefone ausente
origem	enum	Sim	MANUAL, IMPORTACAO, FORMULARIO_WEB, INDICACAO, AUTOMACAO
status	enum	Sim	NOVO, EM_ANDAMENTO, QUALIFICADO, CONVERTIDO, PERDIDO, EXPIRADO. Ver Ciclo de Vida
etapa_funil	enum	Sim	NOVO, CONTATO, QUALIFICADO, PROPOSTA_ENVIADA, NEGOCIACAO
temperatura	enum	Não	FRIO, MORNO, QUENTE
anotacoes	text	Não	Campo livre para o consultor
ultimo_contato_at	timestamp	Não	Atualizado a cada interação
expiracao_at	timestamp	Não	Gerado automaticamente pela config do tenant
created_at	timestamp	Sim	Imutável após criação

2.1 Campos por Tipo de Pessoa

Campo	Pessoa Física (PF)	Pessoa Jurídica (PJ)
nome	Nome completo do interessado	Nome do contato/representante na empresa
razao_social	Não utilizado	Razão social da empresa (obrigatório)
cpf_cnpj	CPF — exigido na qualificação	CNPJ — exigido na qualificação

Na fase de lead, cpf_cnpj ainda não é obrigatório. Torna-se exigido no momento da qualificação (promoção a Cliente).

---

3. Dados do Veículo (opcional na fase de lead)

O consultor pode registrar o veículo de interesse durante a prospecção, antes da qualificação formal:

Campo	Tipo	Notas
veiculo_marca	string	Ex: "Toyota"
veiculo_modelo	string	Ex: "Corolla"
veiculo_ano	int	Ex: 2021
veiculo_placa	string	Opcional nesta fase

---

4. Estados do Ciclo de Vida

---

5. Relacionamentos

Lead ──── pertence a ──── Tenant      (N:1)
Lead ──── é de ────────── Consultor   (N:1 → Usuário)
Lead ──── gera ─────────  Tarefas     (1:N)
Lead ──── possui ────────  Timeline   (1:N → Evento)
Lead ──── pode virar ────  Cliente    (1:0..1)

Legenda de Cardinalidade:

• N:1 (Muitos para Um): Múltiplos registros deste domínio apontam para um mesmo registro de destino (ex: vários leads pertencem ao mesmo tenant).
• 1:N (Um para Muitos): Um único registro deste domínio possui vários registros filhos (ex: um lead pode gerar múltiplas tarefas).
• 1:0..1 (Um para Zero ou Um): Relação opcional de correspondência única (ex: um lead pode nunca se tornar cliente, mas se for convertido, gerará no máximo um único cliente).

---

6. Invariantes (Restrições Absolutas)

• Todo lead deve ter ao menos um contato válido — telefone ou e-mail.
• Um lead PJ deve ter obrigatoriamente razao_social preenchida.
• O lead pode receber Propostas/Cotações e realizar e aprovar a Vistoria com dados mínimos de contato e informações básicas do veículo. A aprovação da vistoria não converte o lead automaticamente em cliente.
• A promoção do lead para Cliente (conversão) ocorre estritamente na emissão ou assinatura do Contrato, exigindo obrigatoriamente nesse ponto o preenchimento de CPF/CNPJ, RG e endereço completo para fins jurídicos.
• Um lead CONVERTIDO não pode ser editado — a edição ocorre na entidade Cliente.
• Um lead pertence exclusivamente ao consultor que o cadastrou; outros consultores só o enxergam se estiverem acima dele na hierarquia de times.
• O tipo_pessoa é imutável após o cadastro do lead.