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.

Modelo de dados de viagem

Modelo de dados do veículo

Tipos de viagem

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

Observação :o tipo de viagem que você define só pode ser atribuído a um veículo compatível com esse tipo de viagem. Por exemplo, só é possível atribuir uma viagem SHARED a um veículo com supported_trip_types definido como SHARED. Consulte a referência para Serviço do veículo, gRPC ou Rest.

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.

Observação :somente viagens exclusivas podem ter destinos ou waypoints intermediários. Consulte Tipos de waypoints da viagem para mais detalhes.

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.

Viagem de destino único

Uma viagem de destino único é uma viagem de EXCLUSIVE com um local de embarque e um de desembarque. Por exemplo, um motorista pega um passageiro em um local e o transporta para outro, ou recupera um pedido de entrega de comida de um restaurante e o entrega para um cliente.

Viagens com vários destinos

Uma viagem com vários destinos é uma viagem de EXCLUSIVE que contém um ou mais destinos intermediários entre os locais de embarque e desembarque. Por exemplo, três clientes de serviços de transporte por aplicativo agendam uma viagem usando o smartphone de uma pessoa, mas cada um tem destinos diferentes.

Viagens de ida e volta

Viagens de ida e volta são viagens EXCLUSIVE que contêm uma série de viagens independentes que ocorrem uma logo após a outra. Cada viagem na cadeia pode ter um ou vários destinos. Neste cenário, um motorista se compromete a pegar outro cliente antes de concluir a viagem atual.

Essas viagens só podem ser atribuídas a veículos que permitem agendamentos consecutivos. Consulte a referência Vehicle REST e gRPC.

Viagens de pool compartilhadas

Uma viagem em pool compartilhada é diferente dos outros tipos de viagem. Primeiro, ela precisa ser uma viagem de SHARED, não de EXCLUSIVE. Nesse caso, o veículo executa as viagens simultaneamente, e não em sequência, como acontece com viagens exclusivas. Embora uma viagem em pool compartilhada compartilhe a jornada com outras viagens, ela não compartilha as informações do local de embarque e desembarque entre as viagens. Cada viagem é uma reserva exclusiva, de modo que o usuário final que reservou uma viagem não pode ver as informações de embarque ou destino de outra viagem além das próprias. Exemplo:

• Um serviço de traslado do aeroporto pega vários clientes na residência deles e os deposita em diferentes terminais do aeroporto ao longo do trajeto. A pessoa 2 pode usar seu app para consumidor para acompanhar o progresso da viagem, mas o app mostra apenas a parte dela, e não onde a pessoa 1 foi embarcada, nem onde a pessoa 1 será despejada, mesmo que algumas partes da jornada se sobreponham.
  
• Um entregador de comida escolhe três pedidos do mesmo restaurante para entregar em diferentes residências. Usando seu app para o consumidor, a pessoa 3 pode ver onde e quando a comida foi retirada e o trajeto do motorista, mas não pode ver os locais de entrega de alimentos das pessoas 1 e 2.
  

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

Observação :para definições de status, consulte a referência gRPC ou REST.

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