Viajes a pedido

En este documento, se describe el servicio de viajes a pedido en Fleet Engine. Se da por sentado que leíste ¿Qué es Fleet Engine? y que conoces la función específica del servicio de Fleet Engine que necesitas.

Mientras lees esta documentación, ten en cuenta lo siguiente:

  • Asignas viajes a vehículos como una forma de modelar la asociación del mundo real entre el viaje y el conductor que lo completa. Lee Introducción a los vehículos para comprender mejor cómo funcionan los vehículos en Fleet Engine.
  • En este documento, también se describen algunos elementos de los vehículos que solo se aplican a los viajes a pedido.
  • Fleet Engine para viajes a pedido usa dos recursos: un Trip y un Vehicle. Fleet Engine proporciona un servicio gRPC y interfaces REST:
    • TripService: gRPC y REST
    • VehicleService: gRPC y REST
    • Para simplificar, este manual usa ejemplos de gRPC.

¿Qué es un viaje a pedido?

En Fleet Engine, un viaje representa un recorrido a pedido que puede lograr una variedad de objetivos de transporte. Por ejemplo:

  • Personas: Transporte de una o más personas desde la ubicación de partida hasta la de destino.
  • Comida y bienes: Retira uno o más pedidos de comida de una ubicación de un negocio determinado y entrega estos pedidos a uno o más destinatarios en sus ubicaciones.

Elementos del viaje

En la siguiente ilustración, se muestran los elementos básicos de un viaje: el ID del vehículo asignado, el estado del viaje y los puntos de referencia del viaje. Los tipos de puntos de referencia varían según la etapa del viaje: partida, intermedio y destino. En cualquier viaje, un destino o punto de referencia intermedio es opcional. En el ejemplo de la imagen, el vehículo llegó a la ubicación de partida.

Modelo de datos de viajes

A medida que tu backend asigna viajes a los vehículos, también debe conocer los otros viajes programados para el vehículo. Por esa razón, en los siguientes diagramas, se ilustra el modelo de datos del recurso Trip junto con el diagrama de su recurso Vehicle asociado. Puedes revisar ambos diagramas para explorar las relaciones entre los dos recursos, teniendo en cuenta lo siguiente:

  • Los viajes se asignan a un vehículo por ID.
  • La asociación viaje-vehículo es de varios a uno. Es decir, un viaje determinado puede ser el único programado para el vehículo o uno de muchos.
  • Los objetos de viaje contienen dos listas de puntos de referencia de viaje, una para el viaje en sí y otra para el vehículo asignado. Esto se explica con más detalle en este documento.
  • El vehículo a pedido también tiene una lista de puntos de referencia del viaje, que se describe con más detalle en este documento.

Modelo de datos de viaje

Modelo de datos de vehículos

Tipos de viaje

Cuando tu servicio crea un viaje, puede configurar el campo tripType como una de las siguientes opciones: EXCLUSIVE o SHARED.

Viajes exclusivos

Un viaje exclusivo es aquel cuyo recorrido no se superpone con otros viajes y que el vehículo completa antes o después de otros viajes en su programa. Esto significa que, cuando tu sistema asigna viajes exclusivos, solo puede asignarlos a un vehículo para que se completen en secuencia, no de forma simultánea. A modo de ejemplo, puedes crear viajes exclusivos con cualquiera de las siguientes características:

  • Es un viaje con un solo punto de partida y un solo destino para un vehículo que no tiene otros viajes en su agenda.
  • Es un viaje con un punto de partida, un punto de referencia intermedio y un punto de destino para un vehículo que no tiene otro viaje en su programación.
  • Un viaje con una partida y una llegada agregadas al final de un viaje ya programado para el vehículo En estos casos, cada viaje es exclusivo del otro, pero los viajes se ordenan de forma consecutiva. Además, estos viajes pueden incluir destinos intermedios si es necesario.

Viajes compartidos

Un viaje compartido es aquel cuyo recorrido puede superponerse con otras reservas de viaje. Para estos tipos de viajes, el sistema puede asignarlos para que se realicen de forma simultánea con destinos intercalados. Por ejemplo, la entrega de un viaje puede ocurrir después de la partida de otro. Además, es posible que los viajes compartidos no usen puntos de referencia intermedios.

Por lo general, usarías un viaje compartido para una de las situaciones de uso compartido de viajes que se ilustran en la sección Situaciones de viaje.

Puntos de referencia del viaje

En Google Maps, un punto de referencia es un lugar a lo largo de una ruta, que suele definirse con una coordenada de latitud y longitud. En el caso de los viajes a pedido, un punto de referencia está representado por un objeto TripWaypoint, que contiene información adicional, como la siguiente:

  • El ID del viaje
  • El WaypointType, ya sea de partida, intermedio o destino
  • Información de ruta y distancia entre el punto de referencia del viaje anterior y el actual
  • Condiciones de tráfico en la ruta hacia el punto de referencia del viaje
  • Tiempo de viaje y hora de llegada estimada al punto de referencia del viaje

Consulta las referencias:

Tipos de puntos de referencia de viaje

Un punto de referencia de viaje se define en relación con el ciclo de vida general de un viaje en vehículo:

  • Punto de partida de la ubicación de partida: Se usa para el origen o el comienzo de un viaje, por ejemplo, cuando un conductor recoge un pedido de comida para una entrega posterior o cuando recoge a una persona para dejarla más tarde.
  • Punto de referencia intermedio: Es un destino intermedio que se puede usar para varios fines, por ejemplo, cuando un conductor deja a un pasajero del mismo grupo de reserva, pero el viaje no está completo, ya que quedan más pasajeros. Este punto de referencia es opcional y solo se puede usar para viajes exclusivos.
  • Punto de destino: Se usa para la ubicación final del viaje, por ejemplo, cuando el pasajero restante sale del vehículo.

Listas de puntos de referencia de viajes

Una entidad Trip incluye dos listas de puntos de referencia, cada una de las cuales es un campo repetido de tipo TripWaypoint. Una lista describe los campos necesarios para el viaje en sí, y la otra describe todos los puntos de referencia restantes para el vehículo asociado con el viaje. Esto te permite tener un panorama completo de todos los elementos del recorrido: el viaje y todo el recorrido del vehículo.

  • Puntos de referencia restantes para el vehículo: Es un campo llamado vehicle_waypoints. Contiene todos los puntos de referencia restantes de todos los viajes asignados al vehículo.
  • Puntos de referencia restantes del viaje: Es un campo llamado remaining_waypoints. Contiene puntos de referencia que el vehículo debe recorrer en secuencia antes del punto de destino final del viaje. Consulta las situaciones en Situaciones de viaje.
    • En el caso de un viaje a un solo destino asignado a un vehículo sin otros viajes en su programa, esto solo incluiría una ubicación de partida y una de destino, siempre y cuando el vehículo no haya salido del punto de partida.
    • En cualquier otra situación de viaje en la que el vehículo también esté programado para otros viajes, los puntos de referencia restantes de cualquier viaje en su itinerario incluirán todos los puntos de referencia de otros viajes que el vehículo debe atravesar antes de llegar al punto de destino de ese viaje. Por ejemplo, en un viaje consecutivo en el que el vehículo está en camino al punto de destino del viaje A, los puntos de referencia restantes del viaje B incluirán el punto de destino del viaje A. Fleet Engine calcula esta información con el campo vehicle_waypoints.

Consulta la referencia de la entidad Trip: gRPC o REST.

Situaciones de viaje

En los siguientes diagramas, se ilustran varias situaciones de viaje admitidas. En estos casos, solo el viaje compartido es del tipo SHARED; todos los demás son EXCLUSIVE. Los diagramas también muestran el estado del viaje y los puntos de intersección restantes del vehículo que realiza el viaje, conceptos que se describen más adelante en esta guía.

Viaje a un solo destino

Un viaje a un solo destino es un viaje EXCLUSIVE con una ubicación de partida y una de destino. Por ejemplo, un conductor recoge a un pasajero de una ubicación y lo transporta a otra, o bien un conductor recupera un pedido de entrega de comida de un restaurante y lo entrega a un cliente.

Viajes con varios destinos

Un viaje de varios destinos es un viaje EXCLUSIVE que contiene uno o más destinos intermedios entre las ubicaciones de partida y destino. Por ejemplo, tres clientes de viajes compartidos reservan un viaje juntos desde el teléfono de una persona, pero cada uno tiene destinos diferentes.

Viajes consecutivos

Los viajes consecutivos son viajes EXCLUSIVE que contienen una serie de viajes independientes que se producen uno después del otro. Cada viaje de la cadena puede tener un destino único o varios. En esta situación, un conductor se compromete a recoger a otro cliente antes de completar el viaje actual.

Estos viajes solo se pueden asignar a vehículos que permitan la programación consecutiva. Consulta la referencia de Vehicle REST, gRPC.

Viajes compartidos

Un viaje compartido con otros usuarios difiere de los otros tipos de viajes. En primer lugar, debe ser un viaje SHARED, no EXCLUSIVE. Aquí, el vehículo ejecuta los viajes de forma simultánea en lugar de hacerlo en secuencia, como en el caso de los viajes exclusivos. Si bien un viaje compartido comparte su recorrido con otros viajes, no comparte la información de las ubicaciones de partida y destino entre los viajes. En cambio, cada viaje es una reserva exclusiva, de modo que el usuario final que reservó un viaje no puede ver la información de partida o destino de ningún otro viaje que no sea el suyo. Por ejemplo:

  • Un servicio de transporte de aeropuerto recoge a varios clientes en sus casas y los deja en diferentes terminales del aeropuerto a lo largo de la ruta. La persona 2 puede usar tu app para consumidores para hacer un seguimiento del progreso del viaje, pero su app solo muestra su parte del viaje y no dónde se recogió a la persona 1 ni dónde se la dejará, aunque partes de sus viajes se superpongan.
  • Un conductor de entrega de comida recoge tres pedidos de comida del mismo restaurante para entregarlos a diferentes residencias de clientes. Con tu app para consumidores, la persona 3 puede ver dónde y cuándo se retiró su comida, así como la ruta del conductor, pero no puede ver las ubicaciones de entrega de comida de las personas 1 y 2.

Estado del viaje y su ciclo de vida

En esta sección, se describe el estado de los viajes y su impacto en el vehículo, así como varias situaciones que puedes encontrar cuando asignas y administras viajes a pedido.

Por lo general, un viaje pasa por varios estados, desde su creación hasta su finalización. En términos generales, un viaje puede ser activo o inactivo, según su estado. El estado del viaje afecta a una variedad de situaciones de casos de uso con Fleet Engine, así como a tu capacidad para identificar el progreso del vehículo a lo largo del viaje. En el resto de este documento, se analizan esas situaciones.

En la siguiente tabla, se enumera el estado de los viajes por tipo de viaje activo o inactivo.

Estados de viaje activos Estados de viajes inactivos
NEW
UNKNOWN_TRIP_STATUS
ENROUTE_TO_PICKUP
ARRIVED_AT_PICKUP
ENROUTE_TO_INTERMEDIATE_DESTINATION
ARRIVED_AT_INTERMEDIATE_DESTINATION
ENROUTE_TO_DROPOFF 		COMPLETE
CANCELED

Estado del viaje y puntos de referencia restantes del vehículo

Cuando asignes viajes adicionales a un vehículo que ya está realizando un viaje, debes comprender la relación entre los puntos de referencia restantes del vehículo y cómo el estado del viaje afecta a esos puntos de referencia.

Por ejemplo, puedes asignar una nueva solicitud de viaje compartido a un vehículo que solo admite viajes exclusivos y que está a punto de completar un viaje. En este caso, modelarías el viaje como un viaje consecutivo. Cuando asignes un viaje de este tipo, tu sistema debe asegurarse de que los puntos de referencia del viaje nuevo aparezcan después de los puntos de referencia del viaje en curso.

Durante el viaje del vehículo, Fleet Engine quita un punto de referencia de viaje anterior de la lista de puntos de referencia restantes del vehículo solo cuando el vehículo informa que está en camino al siguiente destino o que lo completó. Es decir, cualquiera de los siguientes:

  • ENROUTE_TO_INTERMEDIATE_DESTINATION
  • ENROUTE_TO_DROPOFF
  • COMPLETED

Cuando el estado del viaje cambia a COMPLETED, Fleet Engine quita el punto de referencia final del viaje de la lista de puntos de referencia restantes del vehículo.

Por el contrario, los cambios de estado que indican la llegada a un punto de referencia suelen no tener efecto en la lista de puntos de referencia restantes del vehículo:

  • ARRIVED_AT_PICKUP
  • ARRIVED_AT_INTERMEDIATE_DESTINATION
  • ARRIVED_AT_DROPOFF

Para ilustrar con un ejemplo de viaje a pedido, supongamos que el conductor recoge a un cliente de su residencia, lo transporta a un lugar donde espera a que el cliente complete una tarea y, luego, lo lleva de regreso a su residencia. Cuando se crea inicialmente, el viaje tiene tres puntos de referencia: PICKUP, INTERMEDIATE y DROPOFF. En la siguiente tabla, se ilustran los resultados de una consulta de los puntos de referencia restantes en varios estados del viaje:

Estado del viaje Puntos de referencia 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 estado para los viajes reasignados o cancelados

Antes de poder realizar cualquiera de las siguientes acciones, debes establecer el estado del viaje en NEW o CANCELED.

  • Cuando se cambian las asignaciones de vehículos para un viaje. Por ejemplo, si un conductor rechaza la asignación de un vehículo para un viaje y se debe reasignar a otro vehículo.
  • Cuando borras la asignación de un vehículo para un viaje. Por ejemplo, si un conductor cancela un viaje en ruta y quieres borrar la asignación del vehículo, el estado debe ser NEW o CANCELED.

Resultados de la búsqueda según el estado del viaje

Cuando usas el servicio SearchTrips para un vehículo específico, muestra la lista de viajes activos en SearchTripsResponse. Los viajes activos también aparecen en el campo active_trips de la entidad Vehicle. Consulta la referencia de SearchTripsResponse para obtener detalles: gRPC o REST.

Por lo tanto, todos los viajes con un estado activo aparecen en el campo active_trips, pero no los viajes completados o cancelados.

¿Qué sigue?