Hierarquia de Versões: Marca → Modelo → Versão → Versão Detalhe

Este documento explica como funciona a modelagem da base de dados para a hierarquia de veículos e por que existe a separação entre Versão e Versão Detalhe.

Estrutura da Hierarquia

A hierarquia de dados do catálogo segue a seguinte estrutura:

Fabricante (Marca)
  └── Modelo
      └── Versão
          └── Versão Detalhe

Relacionamentos

1. Fabricante: Representa a marca do veículo (ex: Chevrolet, Ford, Fiat)
2. Modelo: Representa o modelo do veículo (ex: Onix, Cruze, Fiesta)
   • Relaciona-se com: Fabricante
3. Versão: Representa a versão básica do modelo (ex: "Onix 1.0", "Onix 1.4")
   • Relaciona-se com: Modelo
4. Versão Detalhe: Representa uma configuração específica da versão com todas as características técnicas
   • Relaciona-se com: Versão
   • Contém informações como: combustível, portas, transmissão, carroceria, anos de fabricação, etc.

Por que existe Versão Detalhe?

A separação entre Versão e Versão Detalhe existe porque uma mesma versão pode ter múltiplas configurações diferentes ao longo dos anos ou com características distintas. A Versão Detalhe armazena as informações específicas que variam entre diferentes configurações da mesma versão.

Exemplo Prático

Considere o modelo Onix da Chevrolet:

Estrutura Simplificada

Fabricante	Modelo	Versão	Versão Detalhe
Chevrolet	Onix	Onix 1.0	Onix 1.0 MT 2020-2022 Flex
Chevrolet	Onix	Onix 1.0	Onix 1.0 MT 2023-2024 Flex
Chevrolet	Onix	Onix 1.0	Onix 1.0 AT 2021-2024 Flex
Chevrolet	Onix	Onix 1.4	Onix 1.4 Turbo MT 2022-2024 Flex
Chevrolet	Onix	Onix 1.4	Onix 1.4 Turbo AT 2022-2024 Flex

Tabela Detalhada: Exemplo de Versões Detalhadas

A tabela abaixo exemplifica por que precisamos da Versão Detalhe - uma mesma versão pode ter múltiplas configurações:

Versão	Versão Detalhe	Combustível	Portas	Transmissão	Carroceria	Ano Início	Ano Fim	Observação
Onix 1.0	Onix 1.0 MT	Flex	4	Manual	Hatchback	2020	2022	Versão descontinuada
Onix 1.0	Onix 1.0 MT	Flex	4	Manual	Hatchback	2023	-	Versão atual
Onix 1.0	Onix 1.0 AT	Flex	4	Automático	Hatchback	2021	-	Versão atual
Onix 1.4	Onix 1.4 Turbo MT	Flex	4	Manual	Hatchback	2022	-	Versão atual
Onix 1.4	Onix 1.4 Turbo AT	Flex	4	Automático	Hatchback	2022	-	Versão atual

Por que essa separação é necessária?

1. Variações ao longo dos anos: Uma mesma versão pode ter mudanças técnicas em diferentes anos de fabricação

   • Exemplo: O Onix 1.0 MT de 2020 pode ter características diferentes do Onix 1.0 MT de 2023

2. Diferentes configurações: Uma versão pode ter múltiplas opções de transmissão, carroceria, etc.

   • Exemplo: Onix 1.0 pode ter Manual (MT) e Automático (AT)

3. Mudanças de especificações: As características técnicas podem mudar mesmo mantendo o mesmo nome de versão

   • Exemplo: Mudança de motor, adição de novos recursos, etc.

4. Precisão na criação de anúncios: Para criar um anúncio, você precisa do version_detail_id específico, não apenas do version_id, porque:

   • O anúncio precisa das características técnicas exatas (combustível, transmissão, portas, etc.)
   • O sistema precisa saber exatamente qual configuração está sendo anunciada
   • Facilita a busca e filtragem de anúncios

Campos da Versão Detalhe

A Versão Detalhe contém os seguintes campos principais:

Campo	Descrição	Exemplo
id	ID único da versão detalhada	1234
name	Nome da versão detalhada (ou nome do modelo se não houver nome específico)	"Onix 1.0 MT"
fuel	Tipo de combustível	Flex, Gasolina, Diesel, etc.
door	Quantidade de portas	2, 4, etc.
transmission	Tipo de transmissão	Manual, Automático, etc.
body	Tipo de carroceria (opcional)	Hatchback, Sedan, SUV, etc.
motorcycle_style	Estilo de moto (opcional, apenas para motocicletas)	Esportiva, Custom, etc.
start_year	Ano de início de fabricação	2020
end_year	Ano de fim de fabricação (null se ainda em produção)	2022 ou null
is_still_production	Indica se ainda está em produção	true/false

Como usar na prática?

1. Buscar Versões Detalhadas de um Modelo

GET /catalog/versions/{model_id}

Este endpoint retorna todas as versões detalhadas disponíveis para um modelo específico, incluindo todas as variações de transmissão, anos, etc.

2. Criar um Anúncio

Ao criar um anúncio, você deve usar o version_detail_id, não o version_id:

{
  "version_detail_id": 1234,  // ✅ Correto - ID da versão detalhada
  "category": 1,
  "color": 5,
  "make_year": 2023,
  "model_year": 2023,
  // ... outros campos
}

aviso

Sempre use o version_detail_id ao criar anúncios. O version_id não é suficiente porque não contém todas as informações técnicas necessárias.

Resumo

• Versão: Representa o nome/comercial da versão (ex: "Onix 1.0")
• Versão Detalhe: Representa uma configuração específica com todas as características técnicas
• Uma Versão pode ter múltiplas Versões Detalhadas (diferentes anos, transmissões, etc.)
• Para criar anúncios, sempre use o version_detail_id