Fleet App — Plataforma de Viajes y Logística

Visión general

Fleet App es la plataforma que desarrollamos para Transporte Guaramang con el objetivo de ordenar la operación logística de punta a punta. Reúne en una única aplicación web la gestión de pedidos, conductores, clientes, vehículos, precios, calificaciones y reportes, y separa la experiencia en dos áreas con layouts y rutas independientes: el panel de administración y clientes y el portal del conductor.

Ciclo de vida del pedido

El pedido es el corazón de la plataforma. Modelamos su ciclo de vida con estados explícitos (pendiente, publicado, agendado, en tránsito, completado, cancelado, expirado) y endpoints dedicados para cada transición:

• Publicar — el cliente o el administrador hace visible la orden para los conductores disponibles.
• Aceptar — el conductor toma la orden desde su app.
• Iniciar — el conductor marca el inicio real del viaje.
• Completar parada / completar orden — el conductor cierra cada punto de entrega y luego la orden completa.
• Cancelar — la orden puede cancelarse según el rol y el estado, controlado por useOrderPermissions.

Todo el flujo se refleja en tiempo real en los listados y en el módulo de monitoreo.

Cotización en tiempo real y configuración de precios

El sistema de precios es la otra pieza clave. Permite configurar precios por ruta, tipo de vehículo y nivel (provincia/ciudad), además de precios especiales por cliente. A partir de esa configuración, el endpoint GET /quotes devuelve una cotización en vivo que se muestra en el drawer del pedido mientras el usuario completa origen, destino y vehículo.

• Configuración de precios base y precios por cliente desde el panel de administración.
• Cotización automática al crear o editar una orden.
• Aplicación de cargos extra por cargador u otros adicionales.

Experiencia diferenciada para conductores

El conductor no comparte layout con el administrador: tiene un DriverLayout propio y rutas bajo /conductor/* protegidas por el guard driver. Desde su app puede:

• Ver órdenes disponibles filtradas por sus provincias de cobertura.
• Aceptar, iniciar y completar pedidos, incluyendo el complete por parada para órdenes multi-destino.
• Consultar su viaje actual y sus calificaciones.
• Editar su disponibilidad por provincia desde su perfil.

La información de perfil, vehículo y contactos adicionales se hidrata desde el mismo backend, con validaciones consistentes entre el portal administrativo y la app del conductor.

Monitoreo en vivo y operación

La pantalla de monitoreo (accesible para roles notDriver) muestra los viajes en tránsito y asignados sobre el mapa, con actualización en vivo del estado y la ubicación. Esta vista es la que utiliza la operación para responder ante incidencias y mantener visibilidad sobre toda la flota sin tener que ir pedido por pedido.

Geocodificación y direcciones

Tanto en el alta de pedidos como en la gestión de direcciones de clientes integramos Google Maps mediante @vis.gl/react-google-maps. El usuario puede:

• Buscar una dirección por texto y obtener coordenadas y provincia/ciudad asociados.
• Ajustar el marker manualmente arrastrándolo en el mapa.
• Parsear URLs de Google Maps para extraer la dirección.

Esto elimina errores de transcripción de direcciones y asegura que cada pedido llegue a la coordenada correcta.

Arquitectura técnica

La aplicación se construyó como una SPA modular con 13 módulos de dominio (auth, addresses, clients, drivers, driver, orders, pricing, ratings, reports, tracking, home, profile, users) y patrones consistentes en todo el código:

• React 19 + TypeScript + Vite para el build y la base de UI.
• Mantine como sistema de componentes (formularios, tablas, modales, notificaciones) y Tailwind CSS para estilos utilitarios.
• TanStack Query para el estado del servidor, con cache, prefetch y un MutationCache global que centraliza toasts e invalidaciones por prefijo de query key.
• Zustand para estado de cliente (useAuthStore persistido, useAppStore para UI).
• Zod para validación de formularios, con la versión envuelta en val() para integrarse con Mantine.
• React Router v7 con data loaders por detalle (driverShowLoader, clientShowLoader, etc.) que prefetchan la query antes de que la página se monte.
• Guards Protected y RoleGuard para autenticación y autorización por rol (superAdmin, admin, client, driver, notDriver, notClient).

El resultado es una base de código con convenciones claras y repetibles que el equipo puede extender sin improvisar arquitectura en cada módulo nuevo.