Entidade: Usuário

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 Regras de Negócio/Módulo 01: Autenticação & Acesso e Regras de Negócio/Módulo 03: Hierarquia de Times

---

1. Definição

Um Usuário é qualquer pessoa com acesso ao sistema CRM. Todo usuário pertence obrigatoriamente a um Tenant e a um Time (exceto os Super Admins da plataforma).

---

2. Atributos Principais

Campo	Tipo	Obrigatório	Notas
id	UUID	Sim	Gerado pelo sistema
tenant_id	UUID	Sim	FK → Tenant
time_id	UUID	Sim*	FK → Time. Obrigatório para todos os papéis exceto SUPER_ADMIN e ADMIN
nome	string	Sim	Nome completo
email	string	Sim	Único por tenant. Usado como login
cpf	string	Sim	CPF validado
telefone	string	Não	Formato E.164
foto_url	string	Não	URL pública da foto de perfil
papel	enum	Sim	SUPER_ADMIN, ADMIN, GESTOR, CONSULTOR, AUDITOR_VISTORIA, GESTOR_VISTORIA (Ver permissões)
canal_vendas	enum	Não	INTERNO (leads qualificados, cotação com adesão fixa), EXTERNO (campo/prospecção, cotação com adesão flexível). Requerido se papel for CONSULTOR ou GESTOR
status	enum	Sim	ATIVO, INATIVO, SUSPENSO, PENDENTE_CONVITE (Ver ciclo de vida)
created_at	timestamp	Sim	Imutável após criação
last_login_at	timestamp	Não	Atualizado a cada sessão

---

3. Papéis (Enum papel)

Papel	Escopo de visibilidade	Pode convidar?
SUPER_ADMIN	Toda a plataforma (apenas infra, nunca dados de clientes)	Cria tenants
ADMIN	Toda a empresa (tenant)	Sim, qualquer papel
GESTOR	Próprio time + times apadrinhados	Sim, convida CONSULTOR
CONSULTOR	Própria carteira	Não
AUDITOR_VISTORIA	Fila de auditoria e laudos de vistoria de todo o tenant	Não
GESTOR_VISTORIA	Fila de auditoria, laudos e gestão de equipe de auditores de vistoria	Sim, convida AUDITOR_VISTORIA

Os papéis não são hierarquia de permissão genérica — cada um tem acesso estritamente definido pelas regras de negócio de hierarquia e áreas operacionais.

---

4. Relacionamentos

Usuário ──── pertence a ──── Tenant (N:1)
Usuário ──── pertence a ──── Time   (N:1)
Usuário ──── possui ─────── Leads   (1:N, quando papel = CONSULTOR/GESTOR)
Usuário ──── recebe ─────── Tarefas (1:N)
Usuário ──── gera ──────── Eventos na Timeline (1:N)

Legenda de Cardinalidade:

• N:1 (Muitos para Um): Múltiplos registros deste domínio apontam para um mesmo registro de destino (ex: vários usuários pertencem ao mesmo tenant/time).
• 1:N (Um para Muitos): Um único registro deste domínio possui múltiplos registros filhos associados (ex: um usuário/consultor possui múltiplos leads ou tarefas).

---

5. Estados do Ciclo de Vida (Enum status)

Definição dos Estados

Status	Significado Comercial	Impacto no Acesso	Ação de Transição
PENDENTE_CONVITE	Convite enviado pelo Admin. Cadastro incompleto.	Bloqueado para login e API.	Ativação do link de convite e definição da senha inicial de acesso.
ATIVO	Cadastro completo e regular.	Acesso liberado (respeitando visibilidade de papel).	Operação normal no sistema.
SUSPENSO	Acesso bloqueado temporariamente por decisão administrativa.	Bloqueado para login e API.	Reativação manual pelo Admin (retorna para ATIVO).
INATIVO	Desligamento ou inativação permanente.	Bloqueado definitivo.	Estado final. Exige redistribuição de Leads/Tarefas órfãs.

Diagrama de Transição de Estados

---

6. Invariantes (Restrições Absolutas)

• Um usuário jamais pode existir sem um tenant (tenant_id é obrigatório e imutável).
• Um CONSULTOR ou GESTOR jamais pode existir sem um time (estado órfão não permitido).
• Usuários com papel CONSULTOR ou GESTOR devem obrigatoriamente possuir um canal_vendas definido (INTERNO ou EXTERNO).
• Usuários com papel AUDITOR_VISTORIA ou GESTOR_VISTORIA não possuem canal_vendas associado (deve ser nulo).
• O email é o identificador de login e é único dentro do tenant (pode se repetir em tenants diferentes).
• O papel pode ser alterado apenas pelo ADMIN do tenant ou pelo SUPER_ADMIN.
• Apenas usuários com papel AUDITOR_VISTORIA, GESTOR_VISTORIA ou ADMIN possuem acesso para auditar, aprovar, reprovar ou delegar auditorias de vistorias veiculares. Consultores e gestores comerciais possuem acesso estritamente de leitura aos laudos e status.