Viagens sob demanda

Este documento descreve o serviço de viagens sob demanda no Fleet Engine. Você precisa ler O que é o Fleet Engine? e conhecer a capacidade específica necessária do serviço do Fleet Engine.

Ao ler esta documentação, tenha em mente o seguinte:

• Você atribui viagens aos veículos como uma forma de modelar a associação real entre a viagem e o motorista que faz a viagem. Leia Introdução a veículos para entender melhor como os veículos funcionam no Fleet Engine.
• Este documento também descreve alguns elementos do veículo que se aplicam apenas a viagens sob demanda.
• O Fleet Engine para viagens sob demanda usa dois recursos: um Trip e um Vehicle. O Fleet Engine oferece um serviço gRPC e interfaces REST:
  • TripService: gRPC e REST
  • VehicleService: gRPC e REST
  • Para simplificar, este manual usa exemplos de gRPC.

O que é uma viagem sob demanda?

No Fleet Engine, uma viagem representa uma jornada sob demanda que pode atingir várias metas de transporte. Por exemplo:

• Pessoas: transporte uma ou mais pessoas do local de embarque aos locais de entrega.
• Alimentos e produtos: retire um ou mais pedidos de comida de um determinado local da empresa e entregue esses pedidos a um ou mais destinatários nos locais deles.

Elementos da viagem

A ilustração a seguir mostra os elementos básicos de uma viagem: o ID do veículo atribuído, o status e os waypoints da viagem. Os tipos de waypoint variam de acordo com a etapa da jornada: embarque, intermediário e desembarque. Em qualquer viagem, um destino ou waypoint intermediário é opcional. No exemplo da imagem, o veículo chegou ao local de retirada.

Modelo de dados para viagens

Como o back-end atribui viagens a veículos, ele também precisa saber sobre outras viagens programadas para eles. Por esse motivo, os diagramas a seguir ilustram o modelo de dados do recurso Trip junto com o diagrama do recurso Vehicle associado. Você pode revisar os dois diagramas para explorar as relações entre os dois recursos, tendo em mente o seguinte:

• As viagens são atribuídas a um veículo pelo ID.
• A associação entre veículo e viagem é de muitos para um. Ou seja, uma determinada viagem pode ser a única programada para o veículo ou uma das muitas viagens de um veículo.
• Os objetos de viagem contêm duas listas de waypoints, uma para a viagem e outra para o veículo atribuído. Isso é explicado com mais detalhes neste documento.
• O veículo sob demanda também tem uma lista de waypoints da viagem, que é descrita em mais detalhes neste documento.

Tipos de viagem

Quando o serviço cria uma viagem, ele pode definir o campo tripType como um dos seguintes: EXCLUSIVE ou SHARED.

Viagens exclusivas

Uma viagem exclusiva é aquela cuja jornada não se sobrepõe a outras e que o veículo conclui antes ou depois de outras viagens na programação. Isso significa que, quando o sistema atribui viagens exclusivas, ele só pode atribuí-las a um veículo para que sejam concluídas em sequência, não simultaneamente. Para ilustrar, você pode criar viagens exclusivas com qualquer uma das seguintes características:

• Uma viagem com um único embarque e um único desembarque de um veículo sem outras viagens na programação.
• Uma viagem com embarque, waypoint intermediário e desembarque de um veículo sem outra viagem na programação.
• Uma viagem com embarque e desembarque adicionados ao final de uma viagem já programada para o veículo. Nesses casos, as viagens são exclusivas, mas são ordenadas de maneira sucessiva. Além disso, essas viagens podem incluir destinos intermediários, se necessário.

Viagens compartilhadas

Uma viagem compartilhada é aquela cuja jornada pode se sobrepor a outras reservas de viagem. O sistema pode atribuir esses tipos de viagem para que ocorram simultaneamente com destinos intercalados. Por exemplo, a desistência de uma viagem pode ocorrer após o embarque em outra viagem. Além disso, elas não podem usar waypoints intermediários.

Normalmente, você usaria uma viagem compartilhada para um dos cenários de pool compartilhado ilustrados na seção Cenários de viagem.

Pontos de referência da viagem

No Google Maps, um waypoint é um lugar ao longo de um trajeto, geralmente definido por uma coordenada de latitude/longitude. Para viagens sob demanda, um waypoint é representado por um objeto TripWaypoint, que contém outras informações, como as seguintes:

• O ID da viagem
• O WaypointType: embarque, intermediário ou desembarque
• Informações de caminho e distância entre o waypoint da viagem anterior e o atual
• Condições de trânsito no caminho até o waypoint da viagem
• Tempo de viagem e HEC até o waypoint da viagem

Consulte as referências:

• TripWaypoint: gRPC ou REST
• WaypointType: gRPC ou REST

Tipos de waypoint da viagem

Um waypoint da viagem é definido em relação ao ciclo de vida geral da jornada de um veículo:

• Ponto de referência de embarque: usado para a origem ou o início de uma viagem, como quando um motorista pega um pedido de comida para entrega posterior ou quando o motorista pega uma pessoa para desembarque mais tarde.
• Ponto de referência intermediário: destino intermediário que pode ser usado para várias finalidades, como quando um motorista desembarca um passageiro do mesmo grupo de reserva, mas a viagem em si não está concluída, porque há mais passageiros. Esse waypoint é opcional e só pode ser usado para viagens exclusivas.
• Ponto de chegada: usado para o local final da jornada, por exemplo, quando o passageiro restante sai do veículo.

Listas de waypoints da viagem

Uma entidade Trip inclui duas listas de waypoints, cada uma delas um campo repetido do tipo TripWaypoint. Uma lista descreve os campos necessários para a viagem, e a outra descreve todos os waypoints restantes do veículo associado à viagem. Assim, você tem uma visão completa de todos os elementos do percurso: a viagem e o percurso do veículo inteiro.

• Pontos de referência restantes do veículo: um campo chamado vehicle_waypoints. Contém todos os waypoints restantes de todas as viagens atribuídas ao veículo.
• Pontos de referência restantes da viagem: um campo chamado remaining_waypoints. Ele contém waypoints que o veículo precisa percorrer em sequência antes do ponto de desembarque final da viagem. Confira os cenários em Cenários de viagem.
  • Em uma viagem de destino único atribuída a um veículo sem outras viagens na programação, isso incluiria apenas os locais de embarque e desembarque, supondo que o veículo não tivesse saído do waypoint de embarque.
  • Em qualquer outro cenário, em que o veículo também está programado para outras viagens, os waypoints restantes de qualquer viagem no itinerário incluem todos os waypoints de outras viagens que o veículo precisa percorrer antes de chegar ao waypoint de desembarque. Por exemplo, em uma viagem de ida e volta em que o veículo está desembarque na viagem A, os waypoints restantes da viagem B incluem o waypoint de desembarque da viagem A. O Fleet Engine calcula essas informações usando o campo vehicle_waypoints.

Consulte a referência da entidade Trip: gRPC ou REST.

Cenários de viagem

Os diagramas a seguir ilustram uma variedade de cenários de viagem compatíveis. Nesses cenários, somente a viagem de pool compartilhada é do tipo SHARED. Todas as outras são EXCLUSIVE. Os diagramas também mostram o status da viagem e os waypoints restantes do veículo que está fazendo a viagem, conceitos descritos mais adiante neste guia.

Status da viagem e ciclo de vida

Esta seção descreve o status da viagem e o impacto dele no veículo, além de vários cenários que você encontra ao atribuir e gerenciar viagens sob demanda.

Geralmente, uma viagem passa por vários estados, da criação à conclusão. Em termos gerais, uma viagem pode estar ativa ou inativa, dependendo do status dela. O status da viagem afeta vários cenários de casos de uso com o Fleet Engine, bem como a capacidade de identificar o progresso do veículo ao longo da jornada. O restante deste documento discute esses cenários.

A tabela a seguir lista o status da viagem por tipos ativos e inativos.

Status de viagem ativa	Status de viagem inativo
NEW UNKNOWN_TRIP_STATUS ENROUTE_TO_PICKUP ARRIVED_AT_PICKUP ENROUTE_TO_INTERMEDIATE_DESTINATION ARRIVED_AT_INTERMEDIATE_DESTINATION ENROUTE_TO_DROPOFF	COMPLETE CANCELED

Status da viagem e waypoints restantes do veículo

Ao atribuir outras viagens a um veículo que já está em execução, você precisa entender a relação entre os waypoints restantes do veículo e como o status da viagem afeta esses waypoints restantes.

Por exemplo, você pode atribuir uma nova solicitação de serviço de transporte por aplicativo a um veículo que aceite apenas viagens exclusivas e esteja prestes a concluir uma viagem. Nesse caso, você modelaria a viagem de ida e volta. Ao atribuir essa viagem, o sistema precisa garantir que os waypoints da nova viagem ocorram após os waypoints da viagem em andamento.

Durante o percurso do veículo, o Fleet Engine remove um waypoint da viagem anterior da lista de waypoints restantes somente quando o veículo informa que está a caminho do próximo destino ou que está concluído. Ou seja:

• ENROUTE_TO_INTERMEDIATE_DESTINATION
• ENROUTE_TO_DROPOFF
• CONCLUÍDA

Quando o status da viagem muda para COMPLETED, o Fleet Engine remove o waypoint final da viagem da lista de waypoints restantes do veículo.

Por outro lado, as mudanças de status que indicam a chegada a um waypoint normalmente não afetam a lista de waypoints restantes do veículo:

• ARRIVED_AT_PICKUP
• ARRIVED_AT_INTERMEDIATE_DESTINATION
• ARRIVED_AT_DROPOFF

Para ilustrar com um exemplo de viagem sob demanda: suponha que o motorista pega um cliente em sua residência, o transporta para um local onde ele espera que o cliente conclua uma tarefa e, em seguida, transporta o cliente de volta para sua residência. Quando criada inicialmente, a viagem tem três waypoints: PICKUP, INTERMEDIATE e DROPOFF. A tabela a seguir ilustra os resultados de uma consulta para os waypoints restantes em vários estados da jornada:

Status da viagem	Pontos de referência restantes
ARRIVED_AT_PICKUP	PICKUP INTERMEDIATE DROPOFF
ENROUTE_TO_INTERMEDIATE_DESTINATION	PICKUP INTERMEDIATE DROPOFF
ARRIVED_AT_INTERMEDIATE_DESTINATION	PICKUP INTERMEDIATE DROPOFF
ENROUTE_TO_DROPOFF	PICKUP INTERMEDIATE DROPOFF
ARRIVED_AT_DROPOFF	PICKUP INTERMEDIATE DROPOFF
COMPLETE	PICKUP INTERMEDIATE DROPOFF

Requisitos de status para viagens reatribuídas ou canceladas

Antes de realizar as seguintes ações, você precisa definir o status da viagem como NEW ou CANCELED.

• Ao mudar as atribuições de veículo para uma viagem. Por exemplo, se um motorista recusar a atribuição de um veículo em uma viagem e ele precisar ser reatribuído a outro veículo.
• Ao limpar a atribuição de um veículo para uma viagem Por exemplo, se um motorista cancelar uma viagem no trajeto e você quiser remover a atribuição de veículo, o status precisará ser NEW ou CANCELED.

Resultados da pesquisa com base no status da viagem

Quando você usa o serviço SearchTrips para um veículo específico, ele retorna a lista de viagens ativas no SearchTripsResponse. As viagens ativas também aparecem no campo active_trips da entidade Vehicle. Consulte a referência SearchTripsResponse para detalhes: gRPC ou REST.

Assim, todas as viagens com status ativo aparecem no campo active_trips, mas as concluídas ou canceladas, não.

A seguir

• Configurar o Fleet Engine
• Criar veículos
• Criar jornadas sob demanda