Transportes - Vincular Veículo à Excursão

O que é

O card Veículos da tela de edição da excursão é onde você define quais ônibus, vans, micro-ônibus ou carros vão atender aquela viagem. Cada item da lista representa um transporte vinculado à excursão e carrega a capacidade, o badge de ocupação ("X/Y passageiros") e, quando aplicável, o motorista designado e o nome da transportadora.

O usuário chega aqui logo após criar a excursão, quando precisa montar a frota da viagem. Também é o ponto de partida para situações operacionais comuns: trocar um ônibus que quebrou por outro do mesmo grupo, adicionar um segundo veículo de apoio para acomodar a lista de espera ou remover um veículo confirmado em excesso. As alterações feitas aqui repercutem na alocação de assentos, no rooming list, nos embarques exclusivos do transporte e no total de vagas exibido em outras áreas da excursão.

Como usar

1. Vá em Viagens no sidebar, abra a excursão desejada e role até o card Veículos (ícone de caminhão azul, com o contador de itens entre parênteses ao lado do título).
2. Clique em Adicionar (botão azul claro no canto superior direito do card) ou em Adicionar veículo se a lista estiver vazia. Abre o modal Adicionar Transporte com duas abas.
3. Para vincular um veículo já cadastrado, fique na aba Selecionar Veículo:
   • Use o campo Buscar por modelo, placa ou empresa... quando houver mais de 3 veículos. O contador "X de Y veículo(s) disponível(is)" mostra quantos casaram com o filtro.
   • Clique no card do veículo desejado. Veículos com fundo vermelho e ícone de X estão em conflito de datas (em uso em outra excursão no mesmo período) e não podem ser selecionados - a mensagem "Em uso: {Nome da excursão}" aparece logo abaixo.
   • O vínculo é gravado imediatamente: o veículo somete da lista de disponíveis e aparece no card Veículos com a capacidade total como vagas_total.
4. Para adicionar um transporte sem veículo cadastrado (placeholder), clique na aba Sem Veículo e preencha:
   • Nome (obrigatório) - texto livre, ex.: "Ônibus 1", "A Confirmar".
   • Tipo - Van, Micro-ônibus, Ônibus, Ônibus Leito, Ônibus Semi-leito, Ônibus Executivo, Ônibus Double Decker, Minivan ou Carro.
   • Vagas (obrigatório) - capacidade total. O texto de ajuda lembra: "Informe a capacidade total do veículo. Os assentos dos guias são descontados automaticamente."
   • Clique em Adicionar no rodapé do modal.
5. Depois de adicionado, cada linha mostra a foto/ícone, modelo (ou nome), tipo, capacidade, placa, transportadora e o badge de passageiros (verde quando há vagas, vermelho quando o veículo está lotado). A ordem dos itens segue o campo ordem (preenchido automaticamente como max(ordem)+1 na criação).

Casos especiais

Trocar o veículo de um transporte existente

Clique no botão Trocar veículo (duas setas circulares azuis) à direita do item. Abre o modal Trocar Veículo mostrando a lista de outros veículos disponíveis. Selecione o substituto:

• Se houver passageiros cadastrados, aparece o aviso âmbar "Atenção: Transferência de passageiros" e uma confirmação extra antes do envio. O backend mantém os mesmos números de assento sempre que possível e responde com a mensagem "Veículo trocado com sucesso! {N} passageiro(s) mantido(s) nos mesmos assentos."
• Se o novo veículo tiver capacidade menor que algum assento já ocupado, o sistema devolve um aviso 409 orphan_seats listando os passageiros afetados. Confirme o window.confirm para prosseguir - esses passageiros ficam com o campo assento zerado e precisam ser realocados manualmente depois.
• Veículos em conflito de datas com outras excursões aparecem desabilitados, em vermelho, com o aviso "Em uso: {Nome da excursão}".

Vincular um veículo a um transporte criado sem veículo

Itens criados pela aba Sem Veículo exibem o botão azul Vincular veículo (ícone de elo de corrente) no lugar do Trocar. Ele abre o mesmo modal de troca, mas a operação grava o veiculo_id pela primeira vez e atualiza vagas_total para a capacidade do veículo escolhido.

Editar um transporte sem veículo

Somente itens sem veiculo_id mostram o botão âmbar Editar transporte (ícone de lápis). O modal Editar Transporte permite ajustar Nome, Tipo e Vagas (mesmas opções e validações do cadastro). Para itens com veículo vinculado, essas informações vêm direto do cadastro do veículo e não são editáveis aqui - altere no cadastro do veículo.

Vincular o motorista

Quando o veículo tem uma empresa de transporte associada, uma linha extra com ícone de pessoinha aparece abaixo do item. Ela mostra:

• Vincular motorista: {Nome} quando há exatamente um motorista ativo disponível na transportadora.
• Um seletor "Selecione um motorista..." quando há dois ou mais.
• O motorista atual com botões Trocar (azul) e X (cinza, remove).
• O aviso âmbar "Todos os motoristas desta transportadora já estão em uso em outros veículos." quando outros transportes da mesma excursão já consumiram os motoristas disponíveis. Um motorista só pode estar em um veículo por excursão.

Excursão com várias compras do mesmo veículo

O sistema bloqueia vincular o mesmo veiculo_id duas vezes na mesma excursão. Se precisar de mais um ônibus do mesmo modelo, cadastre veículos distintos na frota ou use a aba Sem Veículo com um nome diferenciado.

Veículo em uso em outra viagem do mesmo período

O endpoint veiculos-disponiveis cruza as datas (data_inicio/data_fim) com outras excursões ativas (exceto canceladas, finalizadas e arquivadas) e marca os veículos sobrepostos como conflito. Para liberar o veículo, ajuste as datas de uma das excursões ou troque o veículo da outra.

Erros comuns e como resolver

• "Este veículo já está vinculado a esta excursão" - Causa: tentativa de adicionar/trocar para um veículo que já consta no card Veículos dessa mesma excursão. Solução: escolha outro veículo ou remova primeiro o vínculo existente.
• "Este veículo já está em uso na excursão "{Nome}" nas mesmas datas." - Causa: o veículo está alocado em outra excursão com datas sobrepostas. Solução: ajuste as datas ou troque o veículo da outra excursão antes de tentar de novo.
• "Informe o nome e a quantidade de vagas" - Causa: aba Sem Veículo enviada com campo Nome ou Vagas vazios. Solução: preencha ambos antes de clicar em Adicionar.
• "Não é possível remover este veículo pois há {N} passageiro(s) cadastrado(s). Use a opção 'Trocar' para transferir os passageiros para outro veículo." - Causa: o veículo tem passageiros confirmados ou pendentes vinculados. Solução: use Trocar veículo ou mova os passageiros para outro transporte da excursão antes de remover.
• "Não é possível remover este veículo pois há {N} passageiro(s) vinculado(s) aos seus pontos de embarque exclusivos." - Causa: existem embarques marcados como exclusivos deste transporte com passageiros designados. Solução: realoque os passageiros ou desvincule os embarques exclusivos antes de remover o veículo.
• "{N} passageiro(s) estão em assentos que não existem no novo veículo (capacidade {X})..." - Causa: o veículo escolhido na troca tem capacidade menor que o número do assento de algum passageiro. Solução: confirme o window.confirm para prosseguir aceitando que esses passageiros fiquem sem assento, ou escolha outro veículo com capacidade igual/maior.
• "Veículo sem empresa de transporte vinculada." (ao tentar vincular motorista) - Causa: o veículo selecionado não tem transporte_id no cadastro. Solução: edite o cadastro do veículo e associe uma empresa de transporte primeiro.
• "Motorista inválido para esta transportadora." - Causa: o motorista enviado não pertence à empresa de transporte do veículo. Solução: escolha um motorista da transportadora correta no seletor.
• "Este motorista já está vinculado ao {veiculo} nesta excursão." - Causa: o mesmo motorista foi tentado em dois veículos da mesma excursão. Solução: escolha outro motorista ou desvincule do veículo anterior.
• "Nenhum veículo disponível" (modal Adicionar) - Causa: todos os veículos ativos da frota já estão vinculados ou em conflito de datas. Solução: clique em Cadastrar novo veículo para criar um veículo novo, ou ajuste vínculos/datas existentes.

Onde encontrar

• URL: /admin/excursoes/{excursao}/edit
• Caminho no menu: Viagens > Editar Excursão > card Veículos
• Permissão necessária: editar as viagens
• Módulo necessário: nenhum

Veja também

• Cadastrar Veículo
• Cadastrar Empresa de Transporte
• Layout de Assentos
• Configurar Assentos
• Detalhes do Transporte
• Detalhes do Veículo