Guias - Vincular Guia à Excursão

O que é

A seção Guias / Equipe dentro da página de edição da excursão controla quais profissionais vão acompanhar aquela viagem. Cada vínculo une um guia já cadastrado a uma excursão específica e guarda quatro informações operacionais: a função desempenhada (cargo), o transporte que ele vai acompanhar, o ponto de embarque onde ele encontra o grupo e a poltrona reservada para ele.

O fluxo é todo feito em modal - sem recarregar a página - e usa as rotas /admin/api/excursoes/{id}/guias*. Você normalmente chega aqui depois de criar a excursão e os transportes, durante a montagem da operação.

Em pacotes de viagem (tipo_excursao = pacote_viagem), o transporte é opcional, já que o cliente vai por conta própria; nos demais tipos de excursão o transporte é obrigatório no momento do vínculo.

Como usar

1. Vá em Excursões no sidebar e abra a excursão desejada para edição.
2. Role até o bloco Guias / Equipe (ícone de grupo de usuários).
3. Clique em Adicionar no canto superior direito do bloco.
4. No modal, escolha o guia na lista Selecione o Guia. Só aparecem guias ativos que ainda não estão vinculados a essa excursão.
5. Preencha os campos que aparecem após escolher o guia:
   • Veículo/Transporte - obrigatório em excursões com transporte; oculto em pacotes de viagem. Lista os transportes já cadastrados na excursão.
   • Ponto de Embarque - opcional. A lista filtra automaticamente embarques compatíveis com o transporte selecionado (embarques sem transporte_id ficam sempre disponíveis).
   • Poltrona - opcional. Clique em Selecionar para abrir o mapa visual de assentos. A poltrona escolhida fica bloqueada para o guia e não poderá ser usada por passageiros.
   • Função - opcional. Escolha um dos Cargos ativos cadastrados em Cargos de Guias.
   • Observação - opcional. Texto livre de até 500 caracteres.
6. Clique em Adicionar no rodapé do modal. A lista atualiza com o novo vínculo imediatamente.

Editar um vínculo existente

1. Na lista da seção Guias / Equipe, clique no ícone de lápis ao lado do guia.
2. Ajuste função, transporte, embarque, poltrona ou observação. O guia em si não pode ser trocado - para isso, remova e adicione outro.
3. Clique em Salvar.

Remover um guia

1. Clique no ícone de lixeira ao lado do guia.
2. Confirme na caixa de diálogo.
3. O guia é desvinculado apenas dessa excursão - o cadastro principal em Guias não é apagado.

Casos especiais

Pacote de viagem (sem transporte próprio)

Quando a excursão está marcada como Pacote de viagem, o campo Veículo/Transporte fica oculto no modal e deixa de ser obrigatório. Você pode vincular guias mesmo sem nenhum transporte cadastrado. A poltrona também não aparece, já que depende do transporte.

Excursão com mais de um transporte

Cada vínculo é por transporte. Se a excursão tem 2 ônibus e você quer um guia em cada, faça dois vínculos do mesmo guia? Não - o sistema impede o mesmo guia ser vinculado duas vezes à excursão. Use guias diferentes (ou monitores) por transporte. Para um guia que precisa circular entre veículos, deixe a poltrona em branco e use a Observação para registrar a logística.

Selecionar poltrona pelo mapa visual

Se o veículo tem layout visual cadastrado, o botão Selecionar abre o mapa em modal com os pisos do veículo (Piso Inferior / Piso Superior quando houver). A legenda diferencia:

• Azul - disponível
• Vermelho - ocupado por passageiro
• Âmbar - ocupado por outro guia
• Verde - selecionado por você agora
• Itens fixos do veículo: motorista, escada, banheiro, corredor

Se o veículo não tem layout, aparece uma grade simples numerada de 01 até o total de vagas. Você pode também clicar em Sem assento para deixar o guia sem poltrona reservada.

Editar a poltrona de um guia já vinculado

Ao reabrir um vínculo existente que tem poltrona, o sistema marca o assento atual como selecionável de novo, mesmo aparecendo como "ocupado por guia". Assim você consegue mantê-lo ou trocar sem conflito.

Pontos de embarque sem transporte associado

Embarques cadastrados na excursão sem transporte_id aparecem para qualquer transporte selecionado. Embarques amarrados a um transporte só aparecem quando aquele transporte está escolhido no modal.

Função: campo livre alimentado por Cargos

A função salva é o nome do cargo (texto). A lista do select é alimentada pelos cargos ativos cadastrados em Cargos de Guias, ordenados por relevância. Não há lista fixa de "guia principal / auxiliar / monitor" - são apenas exemplos padrão exibidos quando o cargo bate com esses nomes em telas legadas.

Erros comuns e como resolver

• "Este guia já está vinculado a esta excursão" - Causa: cada guia pode entrar uma única vez por excursão. Solução: edite o vínculo existente em vez de criar outro, ou escolha outro guia.
• "Este assento já está ocupado" - Causa: a poltrona escolhida já está com outro passageiro ou outro guia no mesmo transporte. Solução: abra o mapa de assentos e escolha uma livre, ou use Sem assento.
• "Transporte não pertence a esta excursão" - Causa: o transporte selecionado foi removido da excursão durante a operação. Solução: feche o modal, recarregue a página e tente novamente.
• "Nenhum transporte cadastrado" (aviso amarelo no modal) - Causa: a excursão ainda não tem transporte. Solução: cadastre um transporte na seção Transportes antes de vincular o guia, ou marque a excursão como Pacote de viagem se for o caso.
• "Nenhum guia disponível" (no modal) - Causa: todos os guias ativos já estão vinculados a essa excursão ou não há guias cadastrados. Solução: use o link Cadastrar novo guia que aparece no próprio modal.
• "Selecione um veículo/transporte" (validação local antes do envio) - Causa: tentativa de salvar sem escolher transporte em excursão que não é pacote. Solução: selecione o transporte ou marque a excursão como Pacote de viagem.

Onde encontrar

• URL: /admin/excursoes/{excursao}/edit - seção Guias / Equipe da página de edição
• Caminho no menu: Excursões > abrir excursão > Editar > bloco Guias / Equipe
• Endpoints internos: POST/PUT/DELETE /admin/api/excursoes/{excursao}/guias, GET /admin/api/excursoes/{excursao}/guias-disponiveis, GET /admin/api/excursoes/{excursao}/guias-assentos/{transporte}
• Permissão necessária: editar as viagens
• Módulo necessário: nenhum

Veja também

• Guias - Listagem
• Guias - Cadastrar Guia
• Guias - Pagamento por Excursão
• Guias - Cargos