Entidade: Cliente

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 Cliente é a evolução natural de um Lead no sistema. A conversão formal ocorre no momento da emissão ou assinatura do Contrato. Para evitar perda de vendas e burocracia inicial, o Lead pode receber cotações, aceitar propostas e até realizar e aprovar a Vistoria (presencial ou self-service) contendo apenas dados básicos de contato e do veículo. A documentação cadastral completa (CPF/CNPJ, RG, endereço completo, etc.) torna-se obrigatória e é exigida apenas no momento da confecção do Contrato, instante em que o Lead é efetivamente promovido a Cliente.

Lead  (dados mínimos de contato + veículo. Apto a receber Propostas e realizar Vistorias)
  ↓  emissão/assinatura do contrato + preenchimento cadastral obrigatório
Cliente  (cadastro completo e contrato gerado/assinado)

Um cliente pode possuir múltiplos Veículos e, consequentemente, múltiplos Contratos ativos.

---

2. Atributos Principais

Campo	Tipo	Obrigatório	Notas
id	UUID	Sim	Gerado pelo sistema
tenant_id	UUID	Sim	FK → Tenant
lead_id	UUID	Sim	FK → Lead de origem (imutável)
consultor_id	UUID	Sim	FK → Usuário responsável
tipo_pessoa	enum	Sim	PESSOA_FISICA ou PESSOA_JURIDICA. Herdado do Lead
nome	string	Sim	Nome completo (PF) ou nome do representante/contato (PJ)
razao_social	string	Sim*	Obrigatório se PJ. Razão social da empresa
cpf_cnpj	string	Sim	CPF (PF) ou CNPJ (PJ) validado
telefone	string	Sim	Formato E.164
email	string	Sim	Único por tenant
endereco	object	Sim	CEP, logradouro, número, complemento, cidade, estado
status	enum	Sim	ATIVO, INATIVO, BLOQUEADO
senha_hash	string	Não	Hash da senha de acesso ao portal do cliente
ultimo_login_app	timestamp	Não	Data e hora do último acesso ao portal
token_recuperacao	string	Não	Token temporário para redefinição de senha / primeiro acesso
token_expira_em	timestamp	Não	Expiração do token de recuperação
aceitou_termos_app	boolean	Sim	Default: false. Confirmação de aceite dos termos de uso
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)
cpf_cnpj	CPF (11 dígitos)	CNPJ (14 dígitos)
razao_social	Não utilizado	Razão social (obrigatório)
rg	RG do titular	Não utilizado
data_nascimento	Data de nascimento	Não utilizado
nome_fantasia	Não utilizado	Nome fantasia da empresa (opcional)
inscricao_estadual	Não utilizado	IE da empresa (opcional)
responsavel_nome	Não utilizado	Nome do sócio/representante legal (opcional)

Campos específicos de PF e PJ são ignorados pelo sistema quando não aplicáveis ao tipo.

---

3. Relacionamento com Veículos (Agregado)

Um Cliente pode possuir múltiplos veículos sob sua responsabilidade, sendo cada veículo o objeto de um Contrato de Proteção Veicular independente.

Para evitar redundância de informações e inconsistências de manutenção futura, toda a especificação técnica detalhada dos atributos, categorias e restrições de validação de veículo está centralizada em seu próprio documento de domínio:

• Consulte: Domínio/Entidade: Veículo

---

4. Relacionamentos

Cliente ──── originado de ──── Lead          (1:1)
Cliente ──── pertence a ────── Tenant        (N:1)
Cliente ──── é de ──────────── Consultor     (N:1 → Usuário)
Cliente ──── possui ─────────── Veículos     (1:N)
Cliente ──── possui ─────────── Contratos    (1:N, via Veículo)
Cliente ──── possui ─────────── Propostas    (1:N, via Veículo)
Cliente ──── possui ─────────── Timeline     (1:N → Evento)
Cliente ──── possui ─────────── Tarefas      (1:N)

Legenda de Cardinalidade:

• 1:1 (Um para Um): Relação exclusiva e obrigatória de correspondência única (ex: um Lead origina exatamente um Cliente).
• N:1 (Muitos para Um): Múltiplos registros deste domínio podem estar associados a um único registro de destino (ex: vários clientes de um mesmo consultor).
• 1:N (Um para Muitos): Um único registro deste domínio pode possuir múltiplos registros filhos associados (ex: um cliente pode possuir vários veículos).

---

5. Invariantes (Restrições Absolutas)

• Um cliente sempre está associado a um único lead_id de origem — não é possível criar um cliente diretamente sem passar pelo lead. A relação de conversão é estritamente de 1 para 1 (1:1): um Lead convertido só pode originar um único Cliente, sendo a chave lead_id marcada como única no banco de dados para impedir duplicações ou reaproveitamento de leads.
• O tipo_pessoa é herdado do Lead e é imutável.
• O cpf_cnpj é único dentro do tenant — não podem existir dois clientes com o mesmo CPF ou CNPJ no mesmo tenant.
• Clientes PJ devem ter razao_social obrigatoriamente preenchida.
• Um cliente pode ter vários veículos ativos simultaneamente, cada um com seu próprio contrato.
• A visibilidade segue as mesmas regras de silo do lead: somente o consultor responsável e os gestores acima dele na hierarquia enxergam o cliente.
• O status BLOQUEADO impede geração de novas propostas, mas não cancela contratos existentes.