Viagens sob demanda

Este documento descreve o serviço de viagens sob demanda no Fleet Engine. Ele pressupõe que você leu O que é o Fleet Engine? e conhece o recurso específico do serviço do Fleet Engine de que precisa.

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

  • Você atribui viagens a veículos como uma forma de modelar a associação real entre a viagem e o motorista que a realiza. Leia Introdução aos veículos para entender melhor como eles 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 fornece 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 alcançar várias metas de transporte. Por exemplo:

  • Pessoas: transporte uma ou mais pessoas de um local de retirada para um local de entrega.
  • Comida e produtos: pegue um ou mais pedidos de comida em 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 da viagem e os pontos de passagem. Os tipos de ponto de passagem variam dependendo da etapa da viagem: coleta, intermediária e entrega. Em qualquer viagem, um destino intermediário ou ponto de passagem é 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 o veículo. Por isso, os diagramas a seguir ilustram o modelo de dados do recurso Trip com o diagrama do recurso Vehicle associado. Você pode analisar os dois diagramas para entender as relacionamentos entre os dois recursos, lembrando do seguinte:

  • As viagens são atribuídas a um veículo por ID.
  • A associação entre a viagem e o veículo é de muitos para um. Ou seja, uma determinada viagem pode ser a única programada para o veículo ou uma de muitas.
  • Os objetos de viagem contêm duas listas de waypoints, uma para a viagem em si 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 pontos de passagem da viagem, descrita com mais detalhes neste documento.

Modelo de dados de viagens

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.

Viagens exclusivas

Uma viagem exclusiva é aquela que 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 serem 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 para um veículo sem outras viagens na programação.
  • Uma viagem com um ponto de referência intermediário, um ponto de embarque e um ponto de desembarque para um veículo sem outra viagem na programação.
  • Uma viagem com uma coleta e uma entrega adicionadas ao final de uma viagem já programada para o veículo. Nesses casos, cada viagem é exclusiva da outra, mas as viagens são ordenadas uma após a outra. Além disso, essas viagens podem incluir destinos intermediários, se necessário.

Viagens compartilhadas

Uma viagem compartilhada é aquela que pode se sobrepor a outras reservas de viagem. Para esses tipos de viagem, o sistema pode atribuir a elas a ocorrência simultaneamente com destinos intercalados. Por exemplo, a entrega de uma viagem pode ocorrer após a coleta de outra. Além disso, as viagens compartilhadas não podem usar waypoints intermediários.

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

Pontos de referência da viagem

No Google Maps, um ponto de passagem é um lugar ao longo de uma rota, geralmente definido por uma coordenada de latitude/longitude. Para viagens sob demanda, um ponto de passagem é representado por um objeto TripWaypoint, que contém informações adicionais, como:

  • O ID da viagem
  • O WaypointType, seja embarque, intermediário ou desembarque
  • Informações sobre o caminho e a distância entre o ponto de passagem da viagem anterior e o atual
  • Condições de trânsito no trajeto até o ponto de passagem
  • Tempo de viagem e HEC para o ponto de passagem da viagem

Consulte as referências:

Tipos de ponto de passagem da viagem

Um ponto de passagem da viagem é definido em relação ao ciclo de vida geral de uma viagem de veículo:

  • Waypoint de retirada: usado para a origem ou o início de uma viagem, por exemplo, quando um motorista retira um pedido de comida para entrega posterior ou quando um motorista retira uma pessoa para deixar em outro lugar mais tarde.
  • Ponto de passagem intermediário: um destino intermediário que pode ser usado para vários fins, como quando um motorista deixa um passageiro da mesma reserva, mas a viagem não é concluída porque ainda há outros passageiros. Esse ponto de passagem é opcional e pode ser usado apenas para viagens exclusivas.
  • Ponto de entrega: usado para o local final da viagem, como quando o passageiro sai do veículo.

Listas de pontos de passagem 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 própria viagem e a outra lista descreve todos os pontos de passagem restantes para o veículo associado à viagem. Isso permite que você tenha uma visão completa de todos os elementos da viagem: a viagem e toda a jornada do veículo.

  • Pontos de passagem restantes do veículo: um campo chamado vehicle_waypoints. Ele contém todos os waypoints restantes de todas as viagens atribuídas ao veículo.
  • Pontos de passagem restantes da viagem: um campo chamado remaining_waypoints. Ele contém pontos de passagem que o veículo precisa percorrer em sequência antes do ponto de entrega final da viagem. Consulte os cenários em Cenários de viagem.
    • Para uma viagem de destino único atribuída a um veículo sem outras viagens na programação, isso incluiria apenas um local de retirada e um de entrega, supondo que o veículo não tenha saído do ponto de retirada.
    • Em qualquer outro cenário em que o veículo também esteja programado para outras viagens, os waypoints restantes de qualquer viagem no itinerário vão incluir todos os waypoints de outras viagens que o veículo precisa percorrer antes de chegar ao waypoint de entrega dessa viagem. Por exemplo, em uma viagem de ida e volta em que o veículo está a caminho do ponto de entrega da viagem A, os waypoints restantes da viagem B vão incluir o ponto de entrega 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 vários cenários de viagens com suporte. Nesses cenários, apenas a viagem compartilhada é do tipo SHARED. Todas as outras são EXCLUSIVE. Os diagramas também mostram o status da viagem e os pontos de passagem restantes do veículo que está realizando a viagem, conceitos descritos mais adiante neste guia.

Viagem de destino único

Uma viagem de destino único é uma viagem 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 um motorista retira um pedido de entrega de comida de um restaurante e o entrega a um cliente.

Viagens com vários destinos

Uma viagem com vários destinos é uma viagem EXCLUSIVE que contém um ou mais destinos intermediários entre os locais de retirada e entrega. Por exemplo, três clientes de transporte por aplicativo reservam uma viagem juntos pelo smartphone de uma pessoa, mas cada um tem destinos diferentes.

Viagens consecutivas

Viagens consecutivas são viagens EXCLUSIVE que contêm uma série de viagens independentes que ocorrem uma após a outra. Cada viagem na cadeia pode ter um ou vários destinos. Nesse 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 a programação consecutiva. Consulte a referência Vehicle REST, gRPC.

Viagens compartilhadas

Uma viagem compartilhada é diferente dos outros tipos de viagem. Primeiro, ela precisa ser uma viagem SHARED, não EXCLUSIVE. Aqui, o veículo executa as viagens simultaneamente, em vez de em sequência, como em viagens exclusivas. Embora uma viagem compartilhada compartilhe a viagem com outras, ela não compartilha informações de local de partida e de entrega entre as viagens. Em vez disso, cada viagem é uma reserva exclusiva, de modo que o usuário final que reservou uma viagem não pode acessar as informações de coleta ou destino de nenhuma outra viagem, apenas da própria. Exemplo:

  • Um serviço de transporte de aeroporto pega vários clientes na residência e os deixa em diferentes terminais de aeroporto ao longo da rota. A pessoa 2 pode usar seu app de consumo para acompanhar o progresso da viagem, mas o app dela mostra apenas a parte da jornada dela, e não onde a pessoa 1 foi pega nem onde ela vai ser deixada, mesmo que partes das viagens se sobreponham.
  • Um entregador de comida coleta três pedidos do mesmo restaurante para entregar em diferentes residências de clientes. Usando o app do consumidor, a pessoa 3 pode conferir onde e quando o alimento foi retirado e ver o trajeto do motorista, mas não os locais de entrega de comida para as pessoas 1 e 2.

Status da viagem e ciclo de vida

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

Uma viagem geralmente passa por vários estados, desde a criação até a conclusão. De modo geral, uma viagem pode ser ativa ou inativa, dependendo do status. O status da viagem afeta vários cenários de uso com o Fleet Engine, além de permitir que você identifique o progresso do veículo durante a 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 viagens ativas Status de viagem inativa
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á executando uma, entenda a relação entre os waypoints restantes do veículo e como o status da viagem afeta esses waypoints.

Por exemplo, você pode atribuir uma nova solicitação de transporte por aplicativo a um veículo que aceita apenas viagens exclusivas e está em processo de conclusão de uma viagem. Nesse caso, você modelaria a viagem como uma viagem consecutiva. Ao atribuir uma viagem desse tipo, seu sistema precisa garantir que os pontos de passagem da nova viagem ocorram após os pontos de passagem da viagem em andamento.

Durante a jornada do veículo, o Fleet Engine remove um ponto de passagem anterior da lista de pontos de passagem restantes do veículo somente quando o veículo informa que está a caminho do próximo destino ou que a viagem foi concluída. Ou seja, qualquer um dos seguintes:

  • ENROUTE_TO_INTERMEDIATE_DESTINATION
  • ENROUTE_TO_DROPOFF
  • CONCLUÍDA

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

Por outro lado, as mudanças de status que indicam a chegada a um ponto de passagem geralmente não têm efeito na lista de pontos de passagem restantes do veículo:

  • ARRIVED_AT_PICKUP
  • ARRIVED_AT_INTERMEDIATE_DESTINATION
  • ARRIVED_AT_DROPOFF

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

Status da viagem Waypoints 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 canceladas ou reatribuídas

Antes de fazer qualquer uma das ações a seguir, defina o status da viagem como NEW ou CANCELED.

  • Ao mudar as alocações de veículo para uma viagem. Por exemplo, se um motorista recusar a atribuição de um veículo para uma viagem e ela precisar ser reatribuída a outro veículo.
  • Ao limpar uma atribuição de veículo para uma viagem. Por exemplo, se um motorista cancelar uma viagem em andamento e você quiser limpar a atribuição do veículo, o status precisa 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 mais detalhes: gRPC ou REST.

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

A seguir