Overview
O setup de um veículo permite manter o veículo e o catálogo completo de assentos em uma única operação. SeatType e Seat são gerenciados dentro do contexto do veículo.
Conteúdo hierárquico
SeatType carrega name, color e price. Cada categoria carrega o array de Seat que pertence a ela — assim o cliente não precisa referenciar IDs internos entre categoria e assento:
Exemplo de conteúdo:
{
"licensePlate": "ABC1D23",
"model": "Sprinter",
"manufacturer": "Mercedes-Benz",
"year": 2024,
"type": "VAN",
"floorCount": "FIRST",
"seatTypes": [
{
"name": "Executivo",
"color": "#8B5CF6",
"price": 8000,
"seats": [
{ "label": "01", "floor": "FIRST", "row": 1, "column": "A", "side": "LEFT", "status": "AVAILABLE" },
{ "label": "02", "floor": "FIRST", "row": 1, "column": "B", "side": "RIGHT", "status": "AVAILABLE" }
]
}
]
}
A licensePlate é normalizada em maiúscula, sem espaços e sem hífen. Unicidade é global. seatTypes é opcional no cadastro/atualização; quando um Seat omite status, o padrão é AVAILABLE.
Cadastro
Atualização por substituição
A atualização é substituição completa quando o operador envia seatTypes. O catálogo anterior deixa de ser usado em novas vendas e o novo catálogo passa a valer. Se seatTypes for omitido do conteúdo, o catálogo permanece intacto e apenas os campos do veículo são atualizados.
A substituição remove o catálogo anterior das listagens e vendas futuras, preservando histórico de tickets já emitidos.
Vehicle Status Lifecycle
O status muda por ações próprias de ativação, desativação e remoção:
| Ação | Validação |
|---|
| Ativar | Veículo precisa estar INACTIVE |
| Desativar | Veículo precisa estar ACTIVE; bloqueado se o veículo tiver viagens ativas |
| Remover | Bloqueado se o veículo tiver viagens ativas |
SeatType Suggestions
As sugestões ajudam o cliente a oferecer opções no formulário de cadastro. A lista combina:
- Categorias já cadastradas pela organização.
- Um catálogo padrão (
Comum, Executivo, Leito) para nomes ainda não usados na organização.
A deduplicação é por name em lowercase, com categorias da organização tendo precedência sobre o catálogo padrão.
Multi-tenancy
Toda consulta e mutação é limitada à organização autenticada. Veículos de outras organizações não são expostos.
Capacidades OPS
| Capacidade | Permissão | Descrição |
|---|
| Listar veículos | read:vehicle | Lista paginada com filtros e ordenação |
| Detalhar veículo | read:vehicle | Retorna veículo com catálogo |
| Cadastrar veículo | create:vehicle | Cadastra veículo e catálogo na mesma operação |
| Atualizar veículo | update:vehicle | Atualiza campos e/ou substitui catálogo |
| Ativar veículo | update:vehicle | Marca como ACTIVE |
| Desativar veículo | update:vehicle | Marca como INACTIVE |
| Remover veículo | delete:vehicle | Remove veículo |
| Sugerir SeatTypes | read:vehicle | Sugestões de SeatType para autocomplete |
Business Rules
| Regra | Descrição |
|---|
| Placa única e normalizada | licensePlate é única globalmente, em maiúsculo e sem espaços. |
| Catálogo opcional | Quando seatTypes é enviado, SeatType e Seat são criados/substituídos junto com o veículo. |
| SeatType/Seat no contexto do veículo | SeatTypes e Seats são mantidos junto com o veículo. |
| Substituição total | Update do catálogo substitui o catálogo anterior. |
| Histórico preservado | Tickets/TripSeatSegments existentes continuam associados ao assento usado no momento da venda. |
| Status separado do update | status muda por ações próprias de ativação e desativação. |
| Pronto para escala | Veículo escalável deve estar ACTIVE e possuir catálogo com assentos disponíveis. |
| Desativação/exclusão bloqueada por viagens | deactivate e DELETE falham com vehicle.has_active_trips se o veículo tiver viagens ativas. |
| Escopo por organização | Veículos pertencem à organização da empresa. |
A escolha por substituição total no update simplifica o cliente: ele envia o catálogo final desejado, sem precisar calcular diferenças entre versões.
