Entidade: Veículo

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 07: Veículos & FIPE

---

1. Definição

Um Veículo é o bem a ser protegido pelo contrato de proteção veicular. Pertence obrigatoriamente a um Cliente e é o elo central entre o cliente, as propostas e os contratos.

Um cliente pode possuir múltiplos veículos ativos simultaneamente. Cada veículo pode receber múltiplas propostas, mas apenas uma proposta ativa por vez — ao assinar uma, as demais são invalidadas automaticamente.

---

2. Atributos Principais

Campo	Tipo	Obrigatório	Notas
id	UUID	Sim	Gerado pelo sistema
tenant_id	UUID	Sim	FK → Tenant
cliente_id	UUID	Sim	FK → Cliente proprietário
tipo	enum	Sim	CARRO, MOTO, CAMINHAO, BICICLETA, OUTROS
marca	string	Sim	Ex: "Toyota"
modelo	string	Sim	Ex: "Corolla"
ano_fabricacao	int	Sim	Ex: 2021
ano_modelo	int	Sim	Ex: 2022
placa	string	Não	Formato MERCOSUL (ABC1D23) ou antigo (ABC-1234). Pode ser nulo para veículos 0km não emplacados
chassi	string	Não	Identificador alternativo à placa
renavam	string	Não	Registro Nacional de Veículos Automotores (11 dígitos numéricos). Obrigatório para veículos usados/emplacados. Opcional para veículos 0km em fase de faturamento
cor	string	Não	Cor predominante do veículo conforme documento oficial do órgão de trânsito (ex: Preto, Branco, Prata)
codigo_fipe	string	Não	Código da tabela FIPE. Nulo para veículos não tabelados ou lançamentos 0km ainda não catalogados
fipe_status	enum	Sim	VINCULADO (possui código FIPE), PENDENTE_CADASTRO_FIPE (lançamento 0km ainda não tabelado), ISENTO (veículo não tabelável pela FIPE)
valor_base_informado	decimal	Não	Valor declarado/avaliado — usado como fallback ou para planos não tabelados
nota_fiscal_numero	string	Não	Número da Nota Fiscal de fábrica (obrigatório se fipe_status for PENDENTE_CADASTRO_FIPE)
nota_fiscal_emissao	date	Não	Data de emissão da Nota Fiscal (obrigatório se fipe_status for PENDENTE_CADASTRO_FIPE)
nota_fiscal_valor	decimal	Não	Valor de aquisição do veículo na Nota Fiscal (obrigatório se fipe_status for PENDENTE_CADASTRO_FIPE)
created_at	timestamp	Sim	Imutável após criação
updated_at	timestamp	Sim

O valor FIPE corrente não é gravado diretamente no veículo. É consultado no momento da criação de cada proposta e congelado naquela proposta. No veículo armazena-se apenas o codigo_fipe para referência futura.

---

3. Categorias: Tabelados vs. Não Tabelados

Categoria	Tipos	Tem codigo_fipe?
Tabelados	Carros, Motos, Caminhões convencionais	Sim — obrigatório se o plano exigir FIPE
Não Tabelados	Bicicletas, Máquinas Agrícolas, Veículos customizados	Não — usam valor_base_informado

---

4. Relacionamentos

Veículo ──── pertence a ──── Cliente      (N:1)
Veículo ──── pertence a ──── Tenant       (N:1)
Veículo ──── recebe ─────── Propostas     (1:N)
Veículo ──── tem ────────── Contratos     (1:N)
Veículo ──── passa por ──── Vistorias     (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 veículos de um mesmo cliente).
• 1:N (Um para Muitos): Um único registro deste domínio possui múltiplos registros filhos associados (ex: um veículo pode receber várias propostas ou passar por várias vistorias ao longo do tempo).

---

5. Invariantes (Restrições Absolutas)

• Um veículo sempre pertence a um cliente_id — não existe veículo órfão no sistema.
• Placa e/ou Chassi são os identificadores únicos do bem físico; ao menos um deve estar presente (exceto veículos 0km não emplacados no momento do cadastro).
• O tipo é imutável após o cadastro.
• Um veículo pode ter N propostas, mas ao assinar qualquer uma delas, todas as demais propostas ENVIADA do mesmo veículo são automaticamente marcadas como SUBSTITUIDA.
• Se o plano selecionado em uma proposta exige FIPE, a ausência de codigo_fipe válido no veículo impede a geração da proposta, exceto se o veículo possuir fipe_status = PENDENTE_CADASTRO_FIPE e contiver dados válidos e anexados da Nota Fiscal de fábrica (onde o valor da NF servirá temporariamente como base de cotação e limite de indenização).
• Veículos cadastrados com fipe_status = PENDENTE_CADASTRO_FIPE exigem obrigatoriamente o preenchimento de nota_fiscal_numero, nota_fiscal_emissao e nota_fiscal_valor.
• Para veículos 0km ainda sem placa, o sistema aceita salvar com placa = null, usando o chassi como identificador temporário.