Skip to main content
Uma Trip representa uma viagem agendada — a combinação de cooperativa, permissionário, rota, veículo e motorista em uma data/hora específica. É a entidade central do domínio de Operations.

​
Máquina de Estados

​
TripStatus

​
Transições

Cada transição atualiza o status da viagem.
As transições são explícitas. Horário de partida e registro de embarque não alteram o status por conta própria. Registrar BOARDING_COMPLETED mantém a viagem no status atual.

​
Disponibilidade

Uma viagem é considerada disponível para venda quando está SCHEDULED e departureAt ainda é futuro. A busca de ofertas só retorna viagens nessa condição.

​
Operational guard

O guard operacional valida coerência de operação somente em dois checkpoints pesados: Boarding não executa essa validação estrutural completa. No embarque, a regra deve se concentrar em Trip ativa, ticket válido, assento/manifesto e registro de TicketActivity. Quando o guard encontrar bloqueio ou incoerência, a operação deve:
  • impedir a criação/materialização ou o start da Trip;
  • registrar log auditável com recurso, motivo, usuário/ator e timestamp;
  • criar uma Notification com audience = BKO, type = OPERATIONAL_GUARD_ALERT e priority = URGENT;
  • entregar a notificação aos usuários internos administradores da MOB/BKO.

​
Rastreamento GPS

Trip não guarda campos de tracking diretamente. O último ping GPS aceito fica na tabela auxiliar 1:1 TripTracking. O histórico completo do trajeto fica em TripTrackingPoint.

​
Histórico de trajeto GPS

O histórico de trajeto é append-only. Ele serve para:
  • exibir o caminho percorrido no mapa;
  • auditar divergências entre rota planejada e rota executada;
  • apoiar análise de quilometragem e subsídio;
  • investigar falhas de tracking ou inconsistências operacionais.
Filtros esperados:
O app do motorista não precisa enviar um histórico separado. Cada envio aceito de localização gera o ponto histórico e atualiza o último tracking da Trip.

​
Relação com Outros Domínios

  • Tenant: a Trip pertence à Cooperative e é executada por um TransportOperator.
  • Fleet: a Trip referencia um Vehicle da cooperativa e um Driver vinculado ao permissionário.
  • Operations: a Trip contém TripStops (paradas) e TripItineraries (trechos compráveis); a venda de tickets gera TripSeatSegments.
  • Sales: Orders e Tickets são vendidos referenciando os TripItineraries da viagem. O Ticket mantém cooperativeId e transportOperatorId.

​
Criação avulsa de viagem

Criação avulsa registra uma única viagem.

​
Dados esperados

A cooperativa (cooperativeId) vem do escopo da organização autenticada. O transportOperatorId indica quem executa a viagem. Os itinerários referenciam paradas por stopOrder.

​
Fluxo passo-a-passo

​
Validações na criação

A criação avulsa valida escopo da rota, regularidade do permissionário, autorização de frota, cota e conflitos de horário de veículo e motorista.

​
Validação no start

Ao iniciar a viagem, a mesma coerência operacional deve ser revalidada. Isso evita que uma Trip materializada corretamente continue operando depois de bloqueio administrativo, vencimento de CNH, mudança de autorização, rota inativada ou cota indisponível. Se a validação falhar, a Trip permanece SCHEDULED, o start é bloqueado e o sistema emite OPERATIONAL_GUARD_ALERT para admins MOB/BKO.

​
Controle de cota

O limite é configurado em TransportOperatorRoutePolicy, por permissionário, rota e vigência.
A cota controla viagens executadas. Criar viagens futuras não deve consumir definitivamente a cota do permissionário.

​
Cancelamento de Trip

Cancelar uma Trip bloqueia novas vendas e precisa tratar os tickets já emitidos.
Trip cancelada não deve manter assento ocupado em segmentos de tickets cancelados.

​
Subsídio por quilômetro

O subsídio usa a TransportOperatorRoutePolicy vigente. A política aponta para permissionário e rota e define o valor por quilômetro e a fonte da distância. Exemplo: uma rota de 120 km com subsídio de R2,00/kmgeraR 2,00/km gera R 240,00 de subsídio bruto para uma Trip concluída, antes de ajustes e conciliação.

​
Geração de TripStops e TripItineraries

Os TripStops representam as paradas físicas da viagem; os TripItineraries referenciam pares de paradas como trechos compráveis. Exemplo: viagem São Paulo → Campinas → Ribeirão Preto TripStops (nome resolvido via pointId no catálogo global): TripItineraries:
É possível criar itinerários para trechos intermediários e para o trajeto completo, cada um com preço independente. Isso permite precificação flexível — o trecho completo pode custar menos que a soma dos parciais.

​
Materialização a partir de programações

Além da criação avulsa, viagens são geradas em lote a partir de uma programação recorrente (TripSchedule). A programação define rota, veículo, motorista, frequência e paradas-template, e o DEVMOB materializa as ocorrências em um horizonte móvel de 90 dias. Cada viagem candidata é avaliada antes da criação: candidatas duplicadas, em conflito ou sem autorização operacional são ignoradas, e somente as MATERIALIZABLE são criadas. Detalhes de frequência, idempotência e detecção de conflitos estão na página de Trip Schedules.

​
Cancelamento

O cancelamento marca a viagem como CANCELLED. Tickets, orders, payments e receivables permanecem fora do escopo dessa operação.