Excursões - Mapa de Check-ins

O que é

O Mapa de Check-ins é a visão geográfica do checklist de embarque. Cada check-in ou check-out feito pelo guia no Portal do Guia, quando o GPS do celular está ativo, grava latitude e longitude - esse registro vira um marcador no mapa. Marcadores verdes representam check-ins e marcadores roxos representam check-outs. Registros sem coordenadas (digitados sem GPS) continuam visíveis na lista lateral, mas não aparecem no mapa.

Você normalmente abre esta página no dia da viagem, para acompanhar o embarque acontecendo em tempo real e conferir se os check-ins estão sendo feitos nos pontos de embarque corretos. Ao ativar o modo Ao Vivo, a tela passa a buscar atualizações a cada 8 segundos, dá um toast quando chega um novo registro e centraliza o mapa automaticamente no último ponto recebido.

Como usar

1. Vá em Viagens (Excursões) no sidebar, abra a excursão desejada e acesse o Checklist. No cabeçalho do Checklist clique em Ver no Mapa (o botão só aparece quando já existe pelo menos um check-in). A URL será /admin/excursoes/{excursao}/checklist/mapa.

2. Leia o painel de estatísticas no topo:

   • Check-ins - total de check-ins sobre o total de passageiros.
   • Check-outs - total de check-outs sobre o total de check-ins.
   • Primeiro / Último - horário do primeiro e do último registro da aba ativa (check-in ou check-out).

3. Use os filtros logo abaixo das estatísticas para focar:

   • Buscar - filtra por nome do passageiro (mapa e lista).
   • Embarque - mostra só os registros do ponto de embarque escolhido.
   • Guia - disponível quando há check-ins atribuídos a guias.

4. Alterne entre check-in e check-out clicando nas abas Check-in (verde) e Check-out (roxo) no topo da coluna lateral direita. O mapa e a lista refletem a aba ativa.

5. Clique em um marcador no mapa para abrir o popup com os detalhes do registro: data/hora completa, ponto de embarque, método (QR Code ou manual), registrado por, dispositivo e IP. O popup ainda traz dois atalhos:

   • Abrir no Google Maps - abre as coordenadas em nova aba.
   • Cancelar Registro - abre o modal de cancelamento.

6. Clique em um item da lista lateral para o mapa voar até a posição daquele check-in (zoom 17) e abrir o popup correspondente.

7. Acompanhe em tempo real: clique em Ao Vivo (botão verde do cabeçalho). A tela passa a buscar novos check-ins/check-outs a cada 8 segundos, dá um toast verde a cada novo registro, desenha o marcador no mapa com uma animação pulsante e centraliza no último ponto recebido. Para parar, clique em Parar (mesmo botão, agora vermelho). O estado fica salvo no navegador por até 4 horas, então se você fechar a aba e voltar, o monitoramento retoma sozinho.

8. Registre check-in ou check-out manualmente pelos blocos Aguardando Check-in e Aguardando Check-out no rodapé da lista lateral. Clique no botão Check-in (verde) ou Check-out (roxo) ao lado do passageiro, confira o nome, o embarque e a hora no modal Confirmar Check-in / Check-out e clique em Confirmar Check-in ou Confirmar Check-out. O registro entra com método Manual e "Registrado por" mostra o seu usuário.

9. Cancele um registro errado pelo popup do marcador: clique em Cancelar Registro, informe o motivo no modal Cancelar Registro e confirme em Confirmar Cancelamento. O registro fica marcado como cancelado e some do mapa após o reload.

Casos especiais

Registros sem GPS

Check-ins ou check-outs feitos sem permissão de localização no celular não têm coordenadas e por isso não aparecem no mapa. Eles ficam listados em blocos separados Check-in sem localização e Check-out sem localização na coluna lateral, com a etiqueta azul Sem GPS ao lado do horário, agrupados pelo ponto de embarque do passageiro.

Nenhum registro com coordenadas ainda

Se nenhum check-in ou check-out da excursão tem GPS, a página exibe um estado vazio com o ícone de mapa e a mensagem "Nenhum registro com localização", junto com o aviso "Os check-ins e check-outs precisam ter coordenadas GPS para aparecer no mapa." e o atalho Ver Lista para voltar ao checklist. Os cards de estatísticas e os filtros ficam ocultos enquanto não houver registros.

Monitoramento ao Vivo retomado automaticamente

Ao iniciar o Ao Vivo, o navegador guarda um marcador local (localStorage) válido por 4 horas. Se você recarregar a página, fechar a aba ou abrir o mapa em outro momento dentro dessa janela, o monitoramento volta a rodar sozinho - sem precisar clicar de novo. Para encerrar de verdade, use o botão Parar.

Trocas automáticas de aba no Ao Vivo

Se chegar um check-out enquanto você está na aba Check-in (ou o contrário), o sistema troca a aba sozinho para mostrar o novo registro centralizado e com o popup aberto. Isso evita que você perca um evento por estar olhando para a aba errada.

Erros comuns e como resolver

• "Erro ao fazer check-in." / "Erro ao fazer check-out." - Causa: falha de rede ou validação no endpoint POST /admin/api/excursoes/{id}/checklist/checkin|checkout. Solução: confira a conexão, recarregue a página e tente novamente; se o passageiro já tem check-in/check-out, o backend responde negando a duplicidade.
• "Erro ao cancelar registro." - Causa: motivo em branco, problema de rede ou registro já cancelado. Solução: preencha o motivo do cancelamento (campo obrigatório), recarregue se precisar e tente de novo.
• Marcador não aparece mesmo após o check-in pelo app - Causa: o guia fez o registro sem permissão de localização no celular. Solução: o registro fica em Check-in sem localização na lateral; para futuros, peça ao guia para permitir GPS no Portal do Guia.

Onde encontrar

• URL: /admin/excursoes/{excursao}/checklist/mapa
• Caminho no menu: Viagens (Excursões) > {Excursão} > Checklist > Ver no Mapa
• Permissão necessária: ver as viagens
• Módulo necessário: nenhum

Veja também

• Excursões - Check-in de Passageiros
• Checklist de Embarque
• Pontos de Embarque
• Gerenciar Transportes