按需行程

本文档介绍了 Fleet Engine 中的按需行程服务。本文假定您已阅读什么是 Fleet Engine？，并且了解所需的特定 Fleet Engine 服务功能。

在阅读本文档时，请注意以下几点：

  • 您将行程分配给车辆，以此方式在行程与完成该行程的司机之间建立真实关联。阅读车辆简介，更好地了解车辆在 Fleet Engine 中的工作原理。
  • 本文档还介绍了一些仅适用于按需行程的车辆元素。
  • 用于按需行程的 Fleet Engine 使用两种资源：Trip 和 Vehicle。Fleet Engine 提供 gRPC 服务和 REST 接口：
    • TripService：gRPC 和 REST
    • VehicleService：gRPC 和 REST
    • 为简单起见，本手册使用 gRPC 示例。

什么是按需行程？

在 Fleet Engine 中，行程表示可以实现各种交通目标的按需旅程。例如：

  • 人员：将一人或多人从上车点运送到下车点。
  • 食品和商品：从指定营业地点自提一个或多个食品订单，然后将这些订单送到一个或多个收件人的营业地点。

行程元素

下图显示了行程的基本元素：分配的车辆 ID、行程状态和行程航点。航点类型因行程所处的阶段（上车点、中间点和下车点）而异。在任何行程中，中间目的地或航点都是可选的。在图片示例中，车辆已到达上车点

行程数据模型

当您的后端将行程分配给车辆时，它还必须了解为车辆安排的其他行程。因此，下图说明了 Trip 资源的数据模型及其关联的 Vehicle 资源的图表。您可以查看这两个图表，以探索这两种资源之间的关系，请注意以下几点：

  • 行程是通过 ID 分配给车辆的。
  • 旅行车辆关联为多对一。也就是说，某个行程可能是为车辆安排的唯一行程，也可能是车辆的众多行程之一。
  • 行程对象包含两个行程航点列表，一个用于行程本身，另一个用于指定的车辆。本文档对此进行了更详细的说明。
  • 按需车辆还包含行程航点列表，本文档对此进行了更详细的说明。

行程数据模型

车辆数据模型

行程类型

当您的服务创建行程时，它可以将 tripType 字段设置为以下任一值：EXCLUSIVE 或 SHARED。

专属行程

独占行程是指其行程与其他行程不重叠的行程，以及车辆在其计划的其他行程之前或之后完成的行程。这意味着，当系统分配专属行程时，只能将其分配给要按顺序（而非同时）完成的车辆。为说明这一点，您可以创建具有以下任何特征的专属行程：

  • 某辆车的行程仅有 1 个上车点和 1 个下车点，且行程中没有其他行程。
  • 包含上车点、中间航点和下车点的车辆行程，且该行程中没有其他行程。
  • 在已设定的车辆行程末尾的包含上车点和下车点的行程。在这种情况下，每个行程都是彼此专属的，但这些行程以连续的方式进行排序。此外，如果需要，此类行程可以包含中途目的地。

共享行程

共享行程是指其历程可与其他行程预订重叠的行程。对于这些行程类型，您的系统可以将其分配为与交错目的地同时发生。例如，一次行程的下车点可能在另一行程的上车点后发生。此外，分享的行程不能使用中间航点。

通常，您可以将共享行程用于行程场景部分中所述的共享池场景。

行程航点

在 Google 地图中，航点是指路线沿途的地点，通常由纬度/经度坐标定义。对于按需行程，航点由 TripWaypoint 对象表示，该对象包含其他信息，例如：

  • 行程 ID
  • WaypointType（上车点、中间层或下车点）
  • 上一个行程航点与当前航点之间的路径和距离信息
  • 到达行程航点的路径上的路况信息
  • 到达行程航点的行程时间和预计到达时间

请参阅参考文档：

行程航点类型

行程航点是相对于车辆行程的一般生命周期定义的：

  • 自提航点 - 用于行程的出发地或起点，例如当司机取餐订单以便后续送餐时，或司机接一个人稍后下车时。
  • 中间航点 - 可用于各种目的的中间目的地，例如司机为同一预订方的一位乘客下车，但行程本身并未完成，因为还剩余更多乘客。此航点是可选的，只能用于专属行程。
  • 下车航点 - 用于行程的最终地点，例如当其余乘客下车时。

行程航点列表

Trip 实体包含两个航点列表，其中每个航点都是一个 TripWaypoint 类型的重复字段。一个列表描述了行程本身所必需的字段，另一个用于描述与行程相关联的车辆的所有剩余航点。这样，您就可以全面了解行程的所有元素：行程和整个车辆行程。

  • 车辆的其余航点 - 一个名为 vehicle_waypoints 的字段。它包含分配给车辆的所有行程的所有剩余航点。
  • 行程的剩余航点 - 一个名为 remaining_waypoints 的字段。它包含在行程的最终下车点之前必须按顺序行驶的航点。请参阅行程场景中的场景。
    • 对于单目的地行程，如果车辆没有离开上车点，这将仅包含上车点和下车点。
    • 对于同样安排车辆进行其他行程的任何其他行程场景，其行程中任何行程的剩余航点将包含车辆在到达该行程的下车点之前必须遍历的其他行程的所有航点。例如，在连续的行程中，车辆正在前往行程 A 的下车点行驶，行程 B 的剩余航点将包含行程 A 的下车航点。Fleet Engine 使用 vehicle_waypoints 字段计算此信息。

请参阅 Trip 实体的参考文档：gRPC 或 REST。

行程场景

下图说明了各种受支持的行程场景。在这些场景中，只有共享池行程的类型为 SHARED，所有其他行程均为 EXCLUSIVE 类型。这些图表还显示了执行行程的车辆的行程状态和剩余航点，这些概念将在本指南后面部分进行介绍。

单目的地行程

单目的地行程是指具有一个上车点和一个下车点的 EXCLUSIVE 行程。例如，司机从一个位置接乘客，将乘客运送到另一个位置；或者，司机从一家餐馆检索外卖订单，然后送给顾客。

多目的地行程

多目的地行程是指在上车点和下车点之间包含一个或多个中间目的地的 EXCLUSIVE 行程。例如，三位拼车客户通过一个人的手机一起预订行程，但每位拼车客户都有单独的目的地。

连续旅行

连续行程是 EXCLUSIVE 行程，其中包含一系列接连发生的独立行程。链中的每项行程可以是单目的地，也可以是多目的地。在此场景中，司机在完成当前行程之前承诺接另一位客户。

这些行程只能分配给允许连续安排的车辆。请参阅 Vehicle REST、gRPC 参考文档。

共享泳池行程

共享池化行程不同于其他行程类型。首先，它必须是 SHARED 行程，而不是 EXCLUSIVE 行程。在这种情况下，车辆会同时执行行程，而不是像独占行程按顺序执行。虽然共享的池化行程会与其他行程共享其“历程”，但它不会在行程之间分享上车点和下车点位置信息。相反，每个行程都是专属预订，这样，预订过一次行程的最终用户只能看到自己的行程，而看不到任何其他行程的上车点或目的地信息。例如：

  • 酒店提供机场班车服务，接送各种客户到其住处，然后沿途将他们寄往不同的机场航站楼。用户 2 可能使用您的消费者应用来跟踪行程进度，但他们的应用仅显示他们的一部分历程，而不显示人 1 的接人位置，也不显示用户 1 将下车的位置，尽管其历程的某些部分存在重叠。
  • 一名送餐司机从同一家餐厅取了三个订餐，然后送到不同的顾客居住地。通过您的消费者应用，第 3 个人可以查看取餐地点和时间，还可以查看司机路线，但无法查看第 1 个人和第 2 个人的送餐地点。

行程状态及其生命周期

本部分介绍了行程状态及其对车辆的影响，以及在分配和管理按需行程时遇到的各种场景。

行程通常会经历从创建到完成的各种状态。一般来说，行程可能会处于活跃或非活跃状态，具体取决于其状态。行程状态会影响 Fleet Engine 的各种用例，以及让您确定车辆在行程中的进度的能力。本文档的其余部分将讨论这些场景。

下表按活跃和非活跃类型列出了行程状态。

有效行程状态 无效行程状态
NEW
UNKNOWN_TRIP_STATUS
ENROUTE_TO_PICKUP
ARRIVED_AT_PICKUP
ENROUTE_TO_INTERMEDIATE_DESTINATION
ARRIVED_AT_INTERMEDIATE_DESTINATION
ENROUTE_TO_DROPOFF 		COMPLETE
CANCELED

行程状态和剩余车辆航点

为已在执行行程的车辆分配其他行程时，您应了解车辆的剩余航点之间的关系，以及行程状态对这些剩余航点的影响。

例如，您可以将新的拼车请求分配给仅支持专属行程且正在完成行程的车辆。在这种情况下，您可以将行程建模为连续行程。在分配此类行程时，您的系统应确保新行程的航点位于正在进行的行程的航点之后。

在车辆行程期间，Fleet Engine 仅在车辆报告前往下一个目的地或已完成路线时，才会从车辆的剩余航点列表中移除之前的行程航点。也就是说，以下任意一种情况：

  • ENROUTE_TO_INTERMEDIATE_DESTINATION
  • ENROUTE_TO_DROPOFF
  • 已完成

当行程状态更改为 COMPLETED 时，Fleet Engine 会从车辆的剩余航点列表中移除行程的最终航点。

相比之下，表示到达航点的状态变化通常对车辆的剩余航点列表没有影响：

  • ARRIVED_AT_PICKUP
  • ARRIVED_AT_INTERMEDIATE_DESTINATION
  • ARRIVED_AT_DROPOFF

我们用一个按需乘车的示例来说明：假设司机从其住所接客户，将其带到一个场所，等待客户完成任务，然后将客户送回他们的住所。最初创建时，行程有三个航点：PICKUP、INTERMEDIATE 和 DROPOFF。下表说明了针对行程的不同状态的剩余航点的查询结果：

行程状态 其余航点
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

重新分配或取消的行程的状态要求

您必须先将行程状态设置为 NEW 或 CANCELED，然后才能执行以下任一操作。

  • 更改行程的车辆分配时。例如，如果驾驶员针对行程拒绝了车辆分配，则需要将其重新分配给其他车辆。
  • 清除行程的车辆分配时。例如，如果驾驶员在路线中取消行程，并且您想要清除车辆分配，则状态必须为 NEW 或 CANCELED。

基于行程状态的搜索结果

当您为特定车辆使用 SearchTrips 服务时，它会在 SearchTripsResponse 中返回有效行程的列表。有效行程也会显示在 Vehicle 实体的 active_trips 字段中。如需了解详情，请参阅 SearchTripsResponse 参考：gRPC 或 REST。

因此，所有处于有效状态的行程都会显示在 active_trips 字段中，但已完成或已取消的行程则不会显示。

后续步骤