Manual de usuario
Guía de cada módulo del panel: para qué sirve, qué contiene, qué significa cada campo y cómo se crea/edita/elimina información.
Resumen del Día
/Pantalla de inicio del sistema: muestra de un vistazo el estado operativo de la flota del día (vehículos, conductores, viajes, eventos de geocerca y proyectos), con gráficos históricos y la ubicación en vivo de los vehículos en el mapa.
Qué hay en este módulo
- Selector de mes: permite elegir el mes sobre el que se calculan los indicadores y gráficos (no aplica para el rol Cliente, que siempre ve el mes actual).
- Tarjetas KPI: Vehículos activos, Conductores activos, Viajes del mes seleccionado, Eventos de geocerca del mes, Proyectos activos en el mes.
- Gráfico de barras "Viajes por mes": compara la cantidad de viajes de los últimos meses (desde junio 2026, primer mes con datos GPS en producción).
- Gráfico de barras "Viajes por día": desglosa los viajes día a día dentro del mes elegido.
- Tabla de flota: listado resumido de vehículos con su estado/actividad reciente.
- Mapa de flota en vivo: posición actual de los vehículos con GPS, se actualiza solo (isla React independiente del resto del dashboard).
- Vista alternativa para el rol Cliente: un tablero reducido (viajes del mes, vehículos, tabla de flota y gráfico de viajes por día) sin selector de mes ni las tarjetas de geocercas/proyectos.
A tener en cuenta
- El contenido del dashboard cambia según el rol de la sesión: administradores/gerentes/supervisores ven el tablero completo (grid "default"); el rol "client" ve una versión simplificada (grid "client") centrada solo en sus propios datos.
- Los KPIs y gráficos que dependen del mes se recalculan cada vez que se cambia el selector de mes; los KPIs de vehículos, conductores y la tabla de flota se cargan una sola vez porque no dependen del mes.
- El mapa de flota hace su propio refresco periódico de posiciones GPS, independiente de la carga del resto de la página.
Usuarios
/usersAdministra las cuentas que pueden ingresar al sistema y el rol/permisos que tiene cada una, incluyendo qué proyectos puede ver un usuario de tipo Cliente.
Qué hay en este módulo
- Tabla paginada con Nombre, Email, Rol y acciones (editar, eliminar) de cada usuario.
- Selector de cantidad de registros por página (50/100/200/500/1000).
- Botón "Nuevo" para crear un usuario.
- Un único diálogo de formulario que sirve tanto para crear como para editar (cambia el título, oculta la contraseña y ajusta el botón según el modo).
Campos
| Campo | Descripción | Requerido |
|---|---|---|
| Nombre name | Nombre completo del usuario. Obligatorio ("El nombre es requerido"). | Sí |
| Email email | Correo con el que el usuario inicia sesión. Obligatorio y debe tener formato de email válido ("Email inválido"). | Sí |
| Contraseña password | Solo se pide al crear un usuario nuevo (se oculta al editar). Mínimo 6 caracteres. | Sí |
| Rol role | Define los permisos del usuario. Opciones: Usuario, Supervisor, Gerente, Cliente, Administrador. Es opcional al editar (se puede dejar el rol actual). | Sí |
| Proyectos asignados assignedProjectIds | Solo aparece cuando el Rol seleccionado es "Cliente": un checklist con todos los proyectos para elegir a cuáles tiene acceso ese usuario. Si el rol no es Cliente, no se envían proyectos asignados. | No |
Operaciones
- Crear:
- Botón "Nuevo" abre el diálogo vacío con el rol "Usuario" por defecto. Al completar nombre, email, contraseña y rol (y proyectos si es Cliente) y enviar, se crea el usuario y se refresca la tabla.
- Editar:
- El ícono de lápiz en la fila abre el mismo diálogo precargado con los datos del usuario, sin el campo de contraseña. Si el rol es o pasa a ser Cliente, se muestra el checklist de proyectos asignados con sus selecciones actuales.
- Eliminar:
- El ícono de papelera abre un diálogo de confirmación con el nombre y email del usuario; al confirmar se elimina y la acción no se puede deshacer.
- Listar / Filtrar:
- La tabla trae los usuarios paginados desde el servidor; el único filtro disponible es la cantidad de resultados por página.
A tener en cuenta
- El checklist de "Proyectos asignados" solo tiene efecto para usuarios con rol Cliente: es la forma en que el sistema limita qué proyectos puede consultar ese usuario en el resto de la app.
- La contraseña nunca se pide ni se puede cambiar desde este formulario al editar un usuario existente.
Conductores
/driversMantiene el registro de los conductores de la flota: sus datos de contacto, cédula, contactos de emergencia y el control de sus fechas de ingreso/salida de la empresa.
Qué hay en este módulo
- Tabla paginada con selección múltiple (checkbox), Nombre Completo, Teléfono, fecha de Ingreso, fecha de Salida y Estado (badge).
- Selector de cantidad de registros por página.
- Botón "Importar" para carga masiva de conductores.
- Botón "Nuevo" para crear un conductor (diálogo simple: solo nombre y teléfono).
- Acciones por fila: "Gestionar fechas" (ingreso/salida), "Editar" (lleva a una página dedicada) y "Eliminar".
- Eliminación masiva de los conductores seleccionados con el checkbox de cada fila.
Campos
| Campo | Descripción | Requerido |
|---|---|---|
| Nombre Completo fullName | Nombre completo del conductor. Obligatorio ("El nombre completo es requerido"). | Sí |
| Teléfono phone | Debe empezar con +593 seguido de 9 dígitos (ej. +593978701575). Formato validado estrictamente; si no cumple, muestra "El teléfono debe empezar con +593 y tener 9 dígitos adicionales". | Sí |
| Cédula nationalIdNumber | Número de cédula del conductor. Opcional, solo se pide en la página dedicada de edición (no en el diálogo de creación). | No |
| Contactos de emergencia emergencyContacts | Lista de contactos (Nombre, Teléfono con el mismo formato +593, y Parentesco, todos obligatorios por contacto). Se administra en una lista de tamaño variable dentro de la página de edición, no al crear. | No |
| Fecha de ingreso / Fecha de salida workStartTime / workEndTime | Se gestionan desde el diálogo "Gestionar fechas" (ícono de reloj en la tabla). Determinan el Estado mostrado en el listado (Trabajando / Finalizado / No definido) y se pueden limpiar con el botón "Limpiar". | No |
Operaciones
- Crear:
- Botón "Nuevo" abre un diálogo solo con Nombre Completo y Teléfono. Los demás datos (cédula, contactos de emergencia) se agregan después editando el conductor.
- Editar:
- El ícono de lápiz navega a una página dedicada (/drivers/[id]/edit) donde se pueden modificar nombre, teléfono, cédula y administrar la lista de contactos de emergencia.
- Eliminar:
- Eliminar es un borrado lógico (soft-delete): el conductor queda con isActive=false y desaparece del listado, pero no se borra de la base de datos. Hay eliminación individual por fila y eliminación masiva de los conductores marcados con el checkbox.
- Listar / Filtrar:
- Tabla paginada desde el servidor; la columna Estado refleja si el conductor está actualmente trabajando según sus fechas de ingreso/salida. También existe "Importar" para carga masiva desde archivo.
A tener en cuenta
- El teléfono siempre se valida con el prefijo ecuatoriano +593 más 9 dígitos, tanto al crear como al editar y en cada contacto de emergencia.
- La edición es una página completa (no un diálogo) porque incluye el manejo de contactos de emergencia, una lista de longitud variable que no cabe cómodamente en un diálogo simple.
- Eliminar un conductor no borra su historial: solo lo oculta del listado activo (isActive=false).
Materiales
/materialsCatálogo simple de los materiales o cargas que transportan los vehículos de la flota (arena, ripio, cemento, etc.), usado luego para identificar qué se transporta en cada viaje.
Qué hay en este módulo
- Tabla paginada con una sola columna de datos (Nombre) y la columna de Acciones.
- Selector de cantidad de registros por página.
- Botón "Nuevo" para crear un material.
- Un único diálogo de formulario, usado tanto para crear como para editar (a diferencia de Conductores, no tiene página de edición dedicada porque es un solo campo).
Campos
| Campo | Descripción | Requerido |
|---|---|---|
| Nombre name | Nombre del material o carga (por ejemplo: Arena, Ripio, Cemento). Único campo del formulario, obligatorio ("El nombre es requerido"). | Sí |
Operaciones
- Crear:
- Botón "Nuevo" abre el diálogo con el campo Nombre vacío; al guardar, el material aparece en la tabla.
- Editar:
- El ícono de lápiz en la fila abre el mismo diálogo precargado con el nombre actual para modificarlo.
- Eliminar:
- El ícono de papelera abre un diálogo de confirmación antes de borrar el material definitivamente.
- Listar / Filtrar:
- Tabla paginada desde el servidor; no tiene más filtros que la cantidad de resultados por página, dado lo simple del catálogo.
A tener en cuenta
- El listado estaba vacío al documentar este módulo; se crearon dos materiales de prueba ("Arena" y "Ripio") solo para que las capturas no salieran vacías.
- Es el módulo más simple del sistema: un solo campo de texto sin validaciones adicionales más allá de ser obligatorio.
Proyectos
/projectsAdministra los proyectos/obras de transporte: a qué cliente pertenecen, cómo se cobra cada uno (modo y factores de cobro), qué rutas recorren y qué vehículos tienen asignados.
Qué hay en este módulo
- Tabla con Nombre, Meta de viajes/día, Cliente, Modo de Cobro, Vigencia (badge Activo / Por vencer / Cerrado con rango de fechas), Rutas asignadas, columna "Revisado" (switch para administradores) y Acciones.
- Selector de cantidad de registros por página.
- Botón "Nuevo" que lleva a una página completa de creación (no un diálogo), por lo complejo del formulario.
- Dentro del formulario: sección de Información del Proyecto, gestor de Configuraciones (histórico de modos/tarifas de cobro con vigencia), gestor de Rutas asignadas, Información del Cliente y gestor de Vehículos asignados.
Campos
| Campo | Descripción | Requerido |
|---|---|---|
| Nombre del Proyecto name | Nombre identificador del proyecto. Obligatorio ("El nombre es requerido"). | Sí |
| Obra workSite | Nombre del sitio/obra asociado. Opcional. | No |
| Meta de viajes por día targetTripsPerDay | Número entero mayor o igual a 0. Opcional: si se deja vacío no se envía; si se completa debe ser un entero válido ("Indica un número entero mayor o igual a 0, o déjalo vacío"). | No |
| Nombre del Cliente clientName | Nombre del cliente dueño del proyecto. Obligatorio ("El nombre del cliente es requerido"). | Sí |
| RUC del Cliente clientRuc | RUC (identificación tributaria) del cliente. Obligatorio ("El RUC del cliente es requerido"). | Sí |
| Configuraciones de cobro configurations | Historial de configuraciones con vigencia (fecha de inicio y fin opcional), Modo de Cobro (m³ x Kilómetro, Por Tonelada o Por Metro Cúbico) y sus factores asociados (Kilómetros por Viaje, Material Transportado en m³, Toneladas por Viaje), cada uno con un valor fijo o "dinámico" (tomado del viaje, de los vehículos asignados o de las guías del grupo operativo de WhatsApp, según el factor) más el costo correspondiente. Debe existir al menos una configuración para guardar el proyecto. | Sí |
| Rutas asignadas routes | Rutas (del módulo Rutas) asociadas al proyecto. Debe haber al menos una, todas las filas deben tener una ruta seleccionada y no se puede repetir la misma ruta dos veces. | Sí |
| Vehículos asignados assignedVehicles | Vehículos (del módulo Vehículos) asignados al proyecto, cada uno con su capacidad en m³. Todas las filas deben tener un vehículo seleccionado. | No |
| Revisado isReviewed | Switch visible solo para Administradores en la tabla, que marca el proyecto como revisado. Para Supervisores aparece como estado de solo lectura y, una vez revisado, el proyecto pasa a modo solo-ver para ellos. | No |
Operaciones
- Crear:
- Botón "Nuevo" lleva a la página /projects/create con el formulario completo vacío. Hay que completar datos del proyecto, al menos una configuración de cobro y al menos una ruta antes de poder guardar.
- Editar:
- El ícono de lápiz lleva a la página dedicada /projects/[id] con los datos precargados. Si el usuario es Supervisor y el proyecto ya está "Revisado", el formulario se muestra en modo solo lectura (el backend rechaza cualquier cambio de un supervisor sin importar ese estado).
- Eliminar:
- El ícono de papelera elimina el proyecto; no está disponible para el rol Supervisor.
- Listar / Filtrar:
- Tabla paginada desde el servidor; el switch "Revisado" en la columna permite a un Administrador marcar/desmarcar un proyecto directamente desde el listado sin entrar a editarlo.
A tener en cuenta
- Es el módulo con el formulario más complejo del sistema: combina datos simples del proyecto con tres gestores de listas (configuraciones de cobro, rutas y vehículos asignados), cada uno con sus propias validaciones antes de poder guardar.
- El rol Supervisor tiene permisos limitados: no puede eliminar proyectos y pierde la posibilidad de editar un proyecto una vez que un Administrador lo marca como "Revisado" (queda en modo solo lectura).
- El badge de Vigencia se calcula a partir de las fechas de la configuración de cobro más reciente: Activo, Por vencer o Cerrado.
Vehículos
/vehiclesAdministra la flota de vehículos de la empresa: sus datos técnicos, la matrícula vehicular en PDF, y el historial de llantas y cambios de aceite de cada unidad. Los vehículos se provisionan por otro flujo (no hay "Crear" desde esta pantalla), pero sí se pueden editar, eliminar y auditar.
Qué hay en este módulo
- Tabla con Placa, Tipo, Marca, un indicador de "Servicio de Rastreo" (si el vehículo tiene un dispositivo GPS asociado) y acciones.
- Filtros por Placa (texto) y Tipo (combo con los tipos existentes en la flota).
- Cada fila tiene 4 acciones: Ver detalles, Editar, Registro de Cambios (historial de llantas/aceite) y Eliminar.
- Página de detalle (solo lectura): datos del vehículo y visor embebido del PDF de la matrícula vehicular.
- Página de edición: formulario de datos + carga/eliminación del PDF de matrícula con vista previa en vivo al lado del formulario.
- Página "Registro de Cambios": un croquis visual del vehículo (llantas numeradas según su configuración + cabina) para llevar el historial de cambios de llantas por posición, y una pestaña separada para el historial de cambios de aceite.
Campos
| Campo | Descripción | Requerido |
|---|---|---|
| Placa plate | Identificador del vehículo. Obligatorio ("La placa es requerida"). | Sí |
| Tipo type | Texto libre para clasificar el vehículo (ej. Volqueta, Camión, Tráiler). Alimenta el filtro "Tipo" del listado. Opcional. | No |
| Marca brand | Marca del vehículo (ej. Toyota). Opcional. | No |
| Modelo modelName | Modelo del vehículo (ej. Corolla). Opcional. | No |
| Color color | Color del vehículo. Opcional. | No |
| Capacidad de Material (en toneladas) materialCapacity | Texto libre con la capacidad de carga del vehículo. Opcional. | No |
| Configuración de Llantas tireConfiguration | Cantidad de llantas del vehículo: 6, 10 o 12. Determina qué croquis (posiciones de llantas) se dibuja en "Registro de Cambios". Opcional. | No |
| Matrícula Vehicular (PDF) registrationImagePath | Archivo PDF de la matrícula. Solo se puede tener un archivo subido a la vez: hay que eliminar el actual antes de subir uno nuevo. Se valida que el archivo sea de tipo application/pdf. | No |
| Dispositivo GPS asociado gpsDeviceId | FK al dispositivo GPS (tabla devices) que rastrea a este vehículo. No se edita desde este formulario; solo se refleja como el indicador de color "Servicio de Rastreo Activo/Inactivo" en el listado. Cuando es null, el vehículo no tiene rastreo satelital. | No |
| Historial de llantas tireHistory | Lista de llantas instaladas por posición (código, fecha de instalación, kilómetros de instalación, motivo y estado "active"/"replaced"). Se gestiona desde la pestaña del croquis en "Registro de Cambios", no desde el formulario de edición principal. | No |
| Historial de cambios de aceite oilChangeHistory | Lista de cambios de aceite (fecha, kilómetros, tipo de aceite). Se gestiona desde la pestaña "Aceite" en "Registro de Cambios". | No |
Operaciones
- Crear:
- No disponible desde esta pantalla: los vehículos se provisionan por otro flujo (ej. importación o integración con el proveedor GPS). El listado solo permite editar, ver y eliminar los ya existentes.
- Editar:
- El ícono de lápiz abre /vehicles/[id]/edit: formulario con los datos técnicos y, a la derecha, la vista previa del PDF de matrícula actual. Subir un PDF nuevo requiere primero eliminar el existente (un único archivo por vehículo).
- Eliminar:
- El ícono de papelera abre un diálogo de confirmación con la placa del vehículo. Es un soft-delete (isActive=false): el vehículo deja de listarse pero no se borra físicamente.
- Listar / Filtrar:
- La tabla carga hasta 1000 vehículos de una vez y filtra/pagina en el cliente por Placa (contiene) y Tipo (exacto, con opciones autogeneradas a partir de los tipos presentes en la flota).
A tener en cuenta
- El indicador "Servicio de Rastreo" en el listado se calcula únicamente a partir de si el vehículo tiene gpsDeviceId asignado; no refleja si el GPS está reportando datos en tiempo real (eso se ve en "Sincronización GPS").
- En "Registro de Cambios", crear una llanta nueva en una posición que ya tenía una llanta "active" automáticamente marca la anterior como "replaced" (se conserva en el historial).
- El croquis de llantas cambia de forma según tireConfiguration (6/10/12 llantas); si el vehículo no tiene esa configuración definida, no se puede ubicar el historial por posición.
Ubicación GPS
/devices-locationsVista de solo lectura para ver en un mapa la trayectoria histórica de un vehículo en un rango de fechas, con reproducción tipo "video" punto por punto. No tiene operaciones de creación/edición: los datos de ubicación los genera el proveedor GPS automáticamente.
Qué hay en este módulo
- Panel izquierdo: lista de todas las placas con un punto de color que indica su estado (según su última posición conocida) y, si está en marcha, su velocidad actual. Tiene buscador por placa.
- Checkbox "Geocercas" para superponer en el mapa los polígonos/círculos de geocercas configurados.
- Selector de rango de fechas/horas (con hora) para acotar la trayectoria a consultar; por defecto el día de hoy completo.
- Barra de reproducción: play/pausa, control deslizante (slider) de tiempo, selector de velocidad de reproducción (x1 a x1000) y un campo de fecha/hora exacta para saltar a un instante puntual.
- Mapa interactivo con alternador de "basemap" (mapa calle / satélite), botón "Centrar" para encuadrar toda la trayectoria cargada, la ruta dibujada como línea, y un marcador que se mueve según el punto de reproducción actual.
- Barra de información sobre el mapa con: placa seleccionada, estado (En marcha/Detenido/Apagado/Sin señal) con su color, velocidad en km/h y kilometraje (odómetro) en el punto actual de reproducción.
- El estado y rango de fechas seleccionados se reflejan en la URL (?plates=...&start=...&end=...), por lo que se puede compartir o recargar un enlace a una trayectoria puntual.
Campos
| Campo | Descripción | Requerido |
|---|---|---|
| Placa plate | Identifica el vehículo cuya trayectoria se muestra; se elige de la lista de la izquierda. | No |
| Estado status | Calculado a partir de la última posición reportada: "En marcha" (verde, velocidad > 3 km/h), "Detenido" (ámbar, motor encendido pero quieto), "Apagado" (gris, ignición en false) o "Sin señal" (rojo, última posición con más de 24 horas de antigüedad). | No |
| Ignición (encendido del motor) ignition | Booleano reportado por el hardware GPS. Puede venir null cuando el rastreador no reporta ese dato — nunca se interpreta como "apagado" en ese caso; se prioriza la velocidad para decidir el estado. | No |
| Velocidad (km/h) speed | Velocidad instantánea reportada en el punto de la trayectoria. | No |
| Kilometraje (odómetro) mileage | Distancia acumulada reportada por el dispositivo, en metros (se muestra convertida a km). Puede venir null si el hardware no reporta odómetro — nunca se interpreta como 0. | No |
| Fecha y hora del punto timestamp | Momento exacto (hora de Ecuador) en que se registró esa posición; define dónde cae el punto dentro del slider de reproducción. | No |
A tener en cuenta
- Esta pantalla reutiliza datos de geocercas (features/geofences) solo para dibujarlas como referencia visual sobre el mapa; no permite editarlas desde acá.
- Al reproducir la trayectoria, el punto de partida es el último dato reportado dentro del rango (no el inicio del rango), para evitar que el marcador desaparezca si el vehículo recién empezó a reportar ese día.
- El módulo "Eventos de Geocerca" enlaza directamente a esta pantalla (botón "Ver en mapa") pasando placa y rango de fechas por URL para ver la entrada/salida puntual de un vehículo.
Sincronización GPS
/gps-sync-statusPanel de monitoreo técnico (solo lectura) del estado de la integración con el proveedor de GPS: si la conexión en tiempo real está activa, cuántos vehículos están sincronizados, y el progreso del backfill (carga histórica) de posiciones de cada dispositivo. Se refresca solo cada 3 segundos.
Qué hay en este módulo
- Cuatro tarjetas de KPIs en la parte superior: Proveedor (nombre, cuenta y host/URL base), Vehículos sincronizados (cuántos de cuántos están al día), Desfasados (sin posición reciente) y Tiempo real (estado de la conexión en vivo).
- Tabla de backfill por dispositivo: Vehículo, rango objetivo de fechas a procesar, estado (badge), barra de progreso con porcentaje y filas acumuladas, ETA estimado y hasta qué fecha/hora ya se procesó.
- La página entera se auto-refresca cada 3 segundos mientras está abierta (sin recargar), y detiene el refresco al navegar fuera de la página.
- Mensaje de error visible si falla la llamada al backend que entrega el estado del proveedor GPS.
Campos
| Campo | Descripción | Requerido |
|---|---|---|
| Proveedor provider.name / accountName / host / baseUrl | Nombre del proveedor GPS integrado (ej. Wialon), la cuenta usada para autenticarse (o "sin sesión" si no hay), y el host/URL base al que se conecta. El punto de color indica si la conexión en tiempo real está activa. | No |
| Vehículos sincronizados devices.synced / devices.total | Cantidad de vehículos con una posición reciente (dentro del umbral syncedThresholdMinutes) sobre el total de vehículos con GPS configurado. | No |
| Desfasados devices.stale | Cantidad de vehículos sin una posición reciente en tiempo real (fuera del umbral de "sincronizado"). | No |
| Tiempo real realtime.connected / fallbackActive | Estado de la suscripción en vivo al proveedor: "En vivo" (conectado, ícono rayo verde), "Respaldo" (fallbackActive=true, se está consultando por polling en vez de stream en vivo, ícono ámbar) o "Caído" (desconectado, ícono rojo). Muestra también cuántas unidades están suscritas, cada cuánto se consulta (pollIntervalMs) y la hora del último evento recibido. | No |
| Estado del backfill backfill[].phase | Por dispositivo: "Backfill en curso" (azul, cargando histórico), "Al día" (gris, ya terminó) o "Error — reintenta automático" (rojo, con el detalle del último error en un tooltip). | No |
| Progreso backfill[].progressPercent / accumulated | Barra de progreso (0-100%) del backfill y cantidad de filas acumuladas procesadas. Si progressPercent es null, se muestra "arrancando…" porque todavía no hay una estimación. | No |
| ETA backfill[].etaLabel | Tiempo estimado restante para terminar el backfill de ese dispositivo, en texto ya formateado por el backend (o "—" si no hay estimación). | No |
| Rango objetivo / Procesado hasta backfill[].targetFrom / targetTo / processedThrough | targetFrom–targetTo es el rango histórico de fechas que se quiere completar para ese dispositivo; processedThrough indica hasta qué fecha/hora ya se trajo esa información. | No |
A tener en cuenta
- Es una pantalla puramente de diagnóstico: no permite forzar un re-sync ni cancelar un backfill desde la UI, solo observar su progreso.
- La fila de backfill se ordena primero por estado (en curso, luego error, luego al día) y dentro de cada grupo alfabéticamente por nombre de vehículo.
- Un dispositivo en estado "Error" sigue reintentando automáticamente en el backend; la UI solo informa el último error, no requiere acción manual.
Geocercas
/geofencesAdministra las geocercas (zonas geográficas delimitadas, como campamentos, canteras o puntos de entrega) que se usan para armar rutas de proyectos y para detectar automáticamente cuándo un vehículo entra o sale de una zona.
Qué hay en este módulo
- Tabla con una miniatura del mapa de cada geocerca, su Nombre, Tipo (Polígono o Círculo con su radio en metros) y acciones.
- Filtro por Nombre (texto).
- Botón "Crear Geocerca" que lleva a una página dedicada /geofences/create con un mapa interactivo de pantalla completa para dibujar el polígono.
- Editar también usa una página dedicada (/geofences/[id]/edit) con el mismo editor de mapa, adaptado a Polígono o Círculo según el tipo de la geocerca.
Campos
| Campo | Descripción | Requerido |
|---|---|---|
| Nombre name | Nombre descriptivo de la geocerca. Obligatorio ("El nombre es requerido"). | Sí |
| Tipo kind | Polígono o Círculo. Al crear, siempre se dibuja como polígono (la API no permite crear círculos manualmente); un registro puede quedar como círculo si así se generó por otro medio, y en ese caso el formulario de edición muestra el editor de círculo (centro + radio) en vez del de polígono. | No |
| Puntos del Polígono coords (puntos del polígono) | Lista ordenada de coordenadas (latitud, longitud) que forman el polígono. Se agregan haciendo click en el mapa, se mueven arrastrando el marcador y se eliminan con click derecho sobre el marcador o con el botón "✕" de la lista. Se requieren al menos 3 puntos ("Se requieren al menos 3 puntos para formar un polígono"). | Sí |
| Punto de Ayuda Punto de Ayuda | Campo auxiliar para pegar una coordenada en formato "Latitud, Longitud" (el mismo orden que copia Google Maps) y agregarla al polígono sin tener que ubicarla a ojo en el mapa; muestra una previsualización antes de confirmar con "Usar". | No |
| Centro y Radio (solo geocercas tipo Círculo) center / radiusMeters | Cuando la geocerca es de tipo Círculo, en vez de puntos se edita un centro (arrastrando el marcador central) y un radio en metros (arrastrando el handle ámbar o escribiendo el valor exacto). El radio debe ser mayor a cero. | No |
Operaciones
- Crear:
- El botón "Crear Geocerca" lleva a /geofences/create: se ingresa un nombre y se dibuja un polígono haciendo click en el mapa (mínimo 3 puntos). Siempre crea geocercas de tipo polígono.
- Editar:
- El ícono de lápiz en la fila lleva a /geofences/[id]/edit, que carga la geometría existente y permite modificar el nombre y, según el tipo, los puntos del polígono o el centro/radio del círculo.
- Eliminar:
- El ícono de papelera abre un diálogo de confirmación antes de eliminar la geocerca definitivamente.
- Listar / Filtrar:
- La tabla pagina en el servidor (50 por página en esta instalación) y permite filtrar por nombre; cada fila muestra una miniatura en vivo del polígono/círculo sobre el mapa.
A tener en cuenta
- Las capturas de creación y edición se tomaron creando una geocerca real de prueba ("Patio de Pruebas QA") dibujando un polígono de 4 puntos haciendo click sobre el mapa; quedó guardada en la base de datos de desarrollo igual que cualquier otra geocerca creada desde la UI.
- El módulo de "Eventos de Geocerca" y la vista de "Ubicación GPS" reutilizan estas geocercas (solo lectura) para detectar entradas/salidas y para dibujarlas como referencia sobre el mapa de trayectorias.
- Al crear, la API no admite círculos manualmente — un registro de tipo círculo solo puede originarse por otra vía (ej. importación) y luego editarse desde acá con el editor de centro/radio.
Eventos de Geocerca
/geofence-eventsMuestra el historial de entradas y salidas de vehículos en las geocercas configuradas, generado automáticamente a partir de las posiciones GPS. Es una vista de solo lectura orientada a análisis y auditoría (ej. verificar cuánto tiempo estuvo un vehículo en una cantera o campamento).
Qué hay en este módulo
- Tabla con Geocerca (badge de color por geocerca), Placa, Entrada, Salida (o "En curso" si el vehículo sigue dentro), Duración y una acción "Ver en mapa".
- Filtros: rango de fechas (con atajos rápidos), combobox de Geocerca, combobox de Placa, y selector de cantidad de resultados por página (50/100/200/500/1000).
- Botón "Limpiar Filtros" que vuelve al rango de fechas por defecto (últimos 7 días) y quita los demás filtros.
- Contador de "Total" de eventos encontrados y texto que describe el rango de fechas activo.
- Botón "Exportar a Excel" que descarga todos los eventos que cumplen los filtros actuales (sin paginar) a un archivo .xlsx con columnas Geocerca, Placa, Entrada, Salida y Duración (s).
Campos
| Campo | Descripción | Requerido |
|---|---|---|
| Geocerca geofence.name | Nombre de la geocerca en la que ocurrió el evento, mostrado como badge de color (el color se asigna de forma consistente por nombre). | No |
| Placa plate | Placa del vehículo que entró/salió de la geocerca. | No |
| Entrada entry.at | Fecha y hora en que el vehículo entró a la geocerca. | No |
| Salida exit.at | Fecha y hora en que el vehículo salió de la geocerca. Si el vehículo sigue dentro (sesión sin cerrar todavía), se muestra "En curso" en vez de una fecha. | No |
| Duración durationSeconds | Tiempo total dentro de la geocerca, calculado como salida menos entrada. Se resalta en rojo con un punto indicador cuando es menor a 15 minutos (900 segundos), para llamar la atención sobre paradas muy cortas. Muestra "—" si todavía está en curso. | No |
A tener en cuenta
- La acción "Ver en mapa" de cada fila lleva a /devices-locations pasando la placa y el rango entrada–salida por URL, para ver exactamente ese tramo de la trayectoria del vehículo sobre el mapa.
- Los eventos los genera el backend automáticamente a partir de las posiciones GPS cruzadas contra la geometría de las geocercas; esta pantalla no permite crear, editar ni eliminar eventos manualmente.
- Un evento con Salida "En curso" indica que, al momento de la consulta, el vehículo seguía dentro de esa geocerca.
Rutas
/routesDefine las rutas que el motor GPS usa para detectar automáticamente los viajes de un vehículo: una secuencia ordenada de geocercas (paradas) y una ventana de duración válida. Es la planificación; los viajes que efectivamente ocurren se ven en "Reporte automático de viajes".
Qué hay en este módulo
- Tabla con Ruta (nombre + cantidad de paradas), chips con la secuencia de paradas (Origen → Parada 1 → … → Destino), interruptor de Habilitada/Deshabilitada, fecha de creación (más recientes primero) y acciones.
- Botón "Crear ruta" que lleva a /routes/create, un formulario de pantalla completa con mapa.
- Cada fila lleva a /routes/[id], una vista de detalle con el listado de paradas y un mapa con el trazado por calles entre ellas (OSRM).
Campos
| Campo | Descripción | Requerido |
|---|---|---|
| Nombre de la ruta name | Nombre descriptivo de la ruta. Se edita también desde el detalle con el ícono de lápiz junto al título. | Sí |
| Paradas geofenceIds (paradas) | Geocercas elegidas como paradas, en el orden en que se visitan: la primera es el Origen, la última el Destino. Se arman haciendo click en las geocercas del panel (o buscándolas por nombre) y se pueden reordenar arrastrando las filas ya seleccionadas. Se requieren al menos 2 paradas para crear o guardar la ruta. | Sí |
| Duración mínima minDurationMin | Minutos mínimos que debe durar un viaje por esta ruta. Si un vehículo recorre todas las paradas en menos tiempo, el viaje se marca como "Descartado" (se interpreta como rebote de GPS, no un viaje real). Debe ser un entero ≥ 0 y menor que la duración máxima. Por defecto 20 min. | Sí |
| Duración máxima maxDurationMin | Minutos máximos permitidos. Si el vehículo no llega a la última parada antes de este tiempo, el viaje queda "Incompleto". Debe ser un entero ≥ 1 y mayor que la duración mínima. Por defecto 360 min (6 h). | Sí |
| Habilitada active | Interruptor en el listado. Una ruta deshabilitada deja de generar viajes nuevos desde el GPS (el motor filtra por este campo), pero conserva su historial de viajes ya creados. | No |
Operaciones
- Crear:
- "Crear ruta" abre /routes/create: se escribe un nombre, se ajustan las duraciones mínima/máxima y se eligen al menos 2 geocercas en el orden de visita sobre un mapa interactivo. Al guardar redirige al detalle de la ruta recién creada.
- Editar:
- Desde el detalle de la ruta (/routes/[id]) se edita el nombre, la duración mínima/máxima y las paradas, cada uno con su propio ícono de lápiz y guardado independiente (no hay un único formulario de edición). Cambiar las duraciones solo aplica a los viajes que se cierren de ahí en adelante; los ya cerrados no se recalculan.
- Eliminar:
- Ícono de papelera en la fila del listado; elimina la ruta sin diálogo de confirmación adicional.
- Habilitar / Deshabilitar:
- El interruptor en la columna "Estado" del listado activa o desactiva la ruta sin pasar por el detalle; el cambio es optimista en la UI y se revierte si la petición falla.
- Listar / Filtrar:
- El listado no tiene filtros; trae todas las rutas y las ordena por fecha de creación, más nuevas primero.
A tener en cuenta
- Los viajes de una ruta no se crean a mano: los abre y cierra el motor GPS del backend al detectar que un vehículo pasó por todas las paradas en orden (ver módulo "Reporte automático de viajes"). Esta pantalla solo define la plantilla (paradas + ventana de duración).
- Ya existían 79 rutas cargadas en el entorno de desarrollo al documentar este módulo, por lo que no fue necesario crear datos de prueba para las capturas.
- El botón "Reconstruir del historial" en el listado de viajes automáticos usa las rutas de este módulo para generar retroactivamente viajes a partir del GPS ya guardado (no crea ni modifica rutas).
Reporte automático de viajes
/route-tripsMuestra los viajes que el motor GPS detecta automáticamente sobre las rutas del módulo "Rutas": arrancan cuando el vehículo entra a la primera parada y se completan al llegar a la última. No hay formulario de creación — todo el contenido lo genera el backend a partir de las posiciones GPS reales de los vehículos.
Qué hay en este módulo
- Tabla con Ruta, Vehículo (placa), Inicio, Duración (o cronómetro en vivo si el viaje sigue en curso) y Estado, paginada de a 20 viajes.
- Filtros: rango de fechas (por defecto, últimos 30 días), placa y un combo múltiple de estados (por defecto solo "Completado").
- Botón "Reconstruir del historial" que lleva a /route-trips/reconstruct para generar viajes retroactivos.
- El ícono de ojo en cada fila lleva a /route-trips/[id]: detalle con el progreso por cada parada y reproducción de la trayectoria GPS sobre un mapa.
Campos
| Campo | Descripción | Requerido |
|---|---|---|
| Ruta routeName | Nombre de la ruta (del módulo Rutas) sobre la que se detectó el viaje. | No |
| Vehículo vehiclePlate | Placa del vehículo que recorrió la ruta. | No |
| Inicio startedAt / scheduledAt | Momento en que el vehículo entró a la primera parada (o la hora programada si todavía no arrancó). | No |
| Duración duración | Tiempo entre el inicio y el cierre del viaje. Si el viaje está "En curso" se muestra un cronómetro en vivo (actualizado cada segundo) en vez de una duración fija. | No |
| Estado status | Uno de cuatro valores, calculados por el backend contra la ventana de duración de la ruta: "En curso" (todavía no llegó a la última parada), "Completado" (llegó dentro de la ventana válida), "Incompleto" (superó la duración máxima sin llegar a la última parada) y "Descartado" (llegó a la última parada en menos que la duración mínima — se interpreta como rebote de GPS, no un viaje real). | No |
Operaciones
- Ver detalle:
- El detalle de un viaje (/route-trips/[id]) muestra el avance por cada parada (visitada / hora de entrada y salida) y reproduce la trayectoria GPS del vehículo sobre el mapa con controles de play/pausa, barra de progreso y velocidad (x1 a x1000). Si todavía no hay posiciones GPS para la ventana del viaje, lo indica en vez de mostrar el reproductor.
- Reconstruir del historial:
- En /route-trips/reconstruct se elige una ruta, uno o más vehículos y un rango de fechas (máximo 92 días por corrida) para que el backend revise el historial GPS ya guardado y cree los viajes de esos días que no existan todavía. Un día solo cuenta si el vehículo pisó todas las paradas de la ruta en orden. El progreso se consulta por polling y la tabla de resultados indica, por vehículo y día, si se creó el viaje, si ya existía, si quedó incompleto o si no hubo paso por las paradas, con un link directo al viaje creado.
- Listar / Filtrar:
- La tabla pagina en el servidor (20 por página) y se filtra por rango de fechas, placa (texto libre) y uno o varios estados a la vez.
A tener en cuenta
- Este módulo es de solo lectura/reporte: no existe "Crear" ni "Eliminar" manual. Los únicos viajes que se pueden originar desde la UI son los del backfill ("Reconstruir del historial"), y ese flujo tampoco permite editar los datos del viaje — solo dispara el proceso automático contra el GPS ya guardado.
- A pesar de que la ruta real es /route-trips y el título de la página dice "Reporte automático de viajes", el código vive en src/features/routes/ (componentes RouteTripsList, RouteTripDetail, TripReconstructPage, etc. en routes.service.ts/routes.types.ts), no en src/features/report-trips/ — esa otra carpeta es la del módulo "Reporte manual de viajes" (/trips).
- Al momento de documentar, el entorno de desarrollo no tenía viajes con estado "Completado" en los últimos 30 días (filtro por defecto); se amplió el filtro a los 4 estados para poder capturar datos reales, lo que mostró 3 viajes "En curso". No se creó ningún dato de prueba porque estos viajes no se pueden generar manualmente desde la UI — solo los produce el motor GPS o el backfill contra posiciones reales.
Reporte manual de viajes
/tripsMuestra los viajes que los propios conductores reportan por WhatsApp (bot "agent-ocean"), con los datos propios de un viaje de Cabezal (tracto-camión con remolque) o de Volqueta (material a granel). A diferencia de "Reporte automático de viajes", acá no hay GPS: el dato lo escribe el conductor en la conversación y queda disponible para corregirlo desde esta pantalla.
Qué hay en este módulo
- Una sola pestaña ("Viajes") con filtros de fecha Desde/Hasta (por defecto últimos 30 días), Placa, Conductor y cantidad de registros por página.
- Tabla con acciones, foto de la guía (si el conductor envió una), Tipo (Cabezal/Volqueta), Estado, Placa, si la placa fue corregida manualmente, Conductor, Guía, Proyecto y el resto de los campos propios de cada tipo de viaje.
- El ícono de lápiz en cada fila lleva a /trips/[id]/edit, un formulario de edición de pantalla completa.
Campos
| Campo | Descripción | Requerido |
|---|---|---|
| Tipo type | Cabezal o Volqueta. Cambia qué sección de campos adicionales se muestra en el formulario de edición. | Sí |
| Estado status | En curso, Completado o Rechazado. | Sí |
| Placa / Vehículo plate / vehicleId | Vehículo con el que se hizo el viaje; en edición se elige de un combo contra el catálogo de vehículos. | Sí |
| Placa corregida plateOverridden | Indica (con un ícono) si un administrador corrigió manualmente la placa que el conductor reportó por WhatsApp, por ejemplo porque el bot la reconoció mal. | No |
| Conductor driverName / driverId | Conductor que reportó el viaje; en edición se elige de un combo contra el catálogo de conductores. | Sí |
| Guía guideNumber | Número de guía de remisión del viaje, si corresponde. | No |
| Proyecto projectId | Proyecto asociado al viaje. Desde 2026-08-13 también se completa para viajes de Cabezal (antes solo existía para Volqueta); se resuelve automáticamente del vehículo activo en el proyecto al momento de la confirmación por WhatsApp, pero puede corregirse acá. | No |
| Origen / Destino origin / destination | Punto de partida y de llegada del viaje, como texto libre. | No |
| Arrastre (solo Cabezal) trailerPlate | Placa del remolque/arrastre enganchado al cabezal. | No |
| Transporte (solo Cabezal) transportCompany | Empresa de transporte que realizó el viaje. | No |
| Retorna a (solo Cabezal) returnTo | Lugar al que vuelve el vehículo luego de la entrega. | No |
| Km (solo Cabezal) km | Kilometraje recorrido en el viaje. | No |
| Capacidad (solo Volqueta) capacity | Capacidad de carga de la volqueta usada en ese viaje. | No |
| Material (solo Volqueta) material | Material transportado (ej. lastre, asfalto). | No |
| Cantidad (solo Volqueta) quantity / quantityUnit | Cantidad transportada junto con su unidad: TON o M3. | No |
| Combustible fuelType | Tipo de combustible del vehículo usado en el viaje. | No |
| Observaciones notes | Comentarios libres sobre el viaje. | No |
| Desvío deviation | Texto libre para registrar si el viaje tuvo algún desvío respecto al recorrido esperado. | No |
| Foto guideImageUrl | Foto de la guía que el conductor adjuntó por WhatsApp; se ve en miniatura en la tabla y se amplía en un diálogo al hacer click. | No |
Operaciones
- Editar:
- El ícono de lápiz abre /trips/[id]/edit: permite corregir vehículo, conductor, proyecto, tipo, estado, guía, origen/destino, combustible y, según el Tipo elegido, los campos propios de Cabezal o de Volqueta, más observaciones y desvío. Vehículo y Conductor son obligatorios para guardar.
- Listar / Filtrar:
- La tabla pagina en el servidor y se filtra por rango de fechas, placa y nombre de conductor (ambos de texto libre), con un botón para limpiar todos los filtros.
A tener en cuenta
- No existe un botón "Crear" en esta pantalla: los viajes los origina el conductor reportando por WhatsApp (bot agent-ocean-v4), y acá solo se listan y se corrigen (Editar). No hay forma de dar de alta un viaje nuevo desde la UI.
- Al momento de documentar, el entorno de desarrollo no tenía ningún viaje manual cargado (se probó incluso ampliando el rango de fechas desde el año 2020), por lo que el listado se capturó vacío tal cual queda en ese estado. Tampoco se pudo mostrar el formulario de edición con datos reales por la misma razón — su contenido se documentó leyendo src/features/report-trips/components/trip-edit-page.tsx.
- Pese al nombre de la carpeta del código fuente (src/features/report-trips/), la ruta real de este módulo es /trips y su menú se llama "Reporte manual de viajes"; no confundir con /route-trips ("Reporte automático de viajes"), que vive en src/features/routes/.
- Siete tiempos de checkpoint que antes vivían en este reporte (llegada/ingreso/salida de origen, inicio de ruta, llegada/ingreso/salida de destino) y el tiempo total del circuito se eliminaron de este módulo: ese detalle ahora lo cubre el motor de Rutas (ver "Reporte automático de viajes").
Horarios
/schedulesHistorial de horarios de entrada y salida de los conductores, reportados por WhatsApp al bot agent-ocean-v4. Sirve para verificar asistencia y para calcular beneficios de alimentación (desayuno/merienda) según la hora de entrada y salida.
Qué hay en este módulo
- Pestañas "Gráficas" y "Datos" (Datos activa por defecto).
- Filtros: rango de fechas (por defecto la semana actual, lunes a domingo), Conductor (combo contra el catálogo de conductores) y cantidad de registros por página, con botón para limpiar filtros.
- Pestaña Gráficas: barra de asistencia por día (cantidad de horarios iniciados cada día del rango).
- Pestaña Datos: tabla con Conductor, Placa, Hora de inicio, si corresponde Desayuno, Hora de fin, si corresponde Merienda, Duración y Kilometraje.
- Botón "Exportar a Excel" que descarga el rango filtrado completo (sin paginar) como .xlsx.
Campos
| Campo | Descripción | Requerido |
|---|---|---|
| Conductor driverName | Conductor que reportó el horario. | No |
| Placa plate | Vehículo con el que trabajó el conductor en ese turno. | No |
| Hora Inicio startAt | Momento en que el conductor reportó el inicio de su turno. | No |
| Desayuno Desayuno (calculado) | No es un dato guardado: se marca con un check si la Hora Inicio es anterior a las 6:00 a. m., criterio para que le corresponda desayuno. | No |
| Hora Fin endAt | Momento en que el conductor reportó el fin de su turno. Puede quedar vacío si el turno sigue abierto. | No |
| Merienda Merienda (calculado) | Tampoco es un dato guardado: se marca con un check si la Hora Fin es igual o posterior a las 7:00 p. m., criterio para que le corresponda merienda. | No |
| Duración durationInSeconds | Duración del turno en formato hh:mm:ss, calculada por el backend entre inicio y fin. | No |
| Kilometraje finalMilage | Kilometraje final que el conductor reportó al cerrar el turno, si lo indicó. | No |
Operaciones
- Listar / Filtrar:
- La tabla pagina en el servidor y se filtra por rango de fechas y conductor; el total y el resumen por día se recalculan con el mismo filtro pero contra todas las páginas (no solo la visible).
- Exportar:
- El botón "Exportar a Excel" vuelca a un .xlsx (Cédula, Conductor, Placa, Hora Inicio, Hora Fin) todos los horarios que cumplen el filtro actual, recorriendo todas las páginas necesarias contra el backend.
A tener en cuenta
- Es un módulo de solo lectura: no hay "Crear", "Editar" ni "Eliminar" manual. Los horarios los reporta el conductor por WhatsApp; esta pantalla únicamente los lista, los grafica y los exporta.
- Al momento de documentar, el entorno de desarrollo no tenía ningún horario cargado (se verificó limpiando los filtros de fecha), por lo que el listado se capturó vacío. No se pudo generar un dato de prueba porque no existe un formulario de carga: el único origen de estos registros es la conversación de WhatsApp con el bot.
- Los campos Desayuno y Merienda no vienen del backend: la tabla los deriva en el momento a partir de la hora de inicio/fin de cada fila, con el mismo criterio que usa el reporte equivalente para Volquetas/Cabezales.
Combustible
/expenses/fuelRegistro de las cargas de combustible que los conductores reportan por WhatsApp, día a día. Sirve para controlar el gasto de combustible por vehículo y para ver cuánto se cargó en galones y en dólares en un período.
Qué hay en este módulo
- Pestañas "Gráficas" y "Datos" (Datos activa por defecto).
- Filtro de rango de fechas, con etiqueta de cuántos registros hay en el rango seleccionado.
- Tres indicadores: Total de cargas, Total en $ y Total en Galones del rango filtrado.
- Pestaña Gráficas: barra de monto en $ por día y barra de número de cargas por día.
- Pestaña Datos: tabla con Foto de la guía, Placa, Conductor, Cantidad y Fecha.
Campos
| Campo | Descripción | Requerido |
|---|---|---|
| Foto guideImageUrl | Foto de la guía/boleta de la carga que el conductor adjuntó por WhatsApp; se amplía en un diálogo al hacer click. Si no hay foto, se muestra un ícono vacío. | No |
| Placa plate | Vehículo al que se le cargó combustible. | No |
| Conductor driverName | Conductor que reportó la carga. | No |
| Cantidad quantity / unit | El backend registra cada carga en una sola unidad, nunca en ambas a la vez: en galones o directamente en dólares. La tabla y los totales muestran cada carga tal cual vino, sin convertir entre unidades (no hay forma de sumar galones y dólares en un único monto). | No |
| Fecha timestamp | Momento en que se reportó la carga de combustible. | No |
Operaciones
- Listar / Filtrar:
- El único filtro disponible es el rango de fechas; los indicadores y las gráficas se recalculan junto con la tabla al cambiarlo.
- Ver foto:
- Click en la miniatura de la guía abre un diálogo con la imagen en tamaño más grande.
A tener en cuenta
- Es un módulo de solo lectura: no hay "Crear", "Editar" ni "Eliminar". Las cargas de combustible las reporta el conductor por WhatsApp; esta pantalla solo las consulta, las totaliza y las grafica.
- El feature vive en src/features/expenses/ (initFuelExpensesPage), pero reutiliza el servicio y los tipos de src/features/report-trips/ (reportFuelService, FuelRecord) — los mismos que alimentan "Reporte manual de viajes" y "Horarios", todos datos reportados por WhatsApp.
- Al momento de documentar, el entorno de desarrollo no tenía ninguna carga de combustible registrada, por lo que ambas pestañas se capturaron vacías. No se pudo crear un dato de prueba porque no existe ningún formulario de carga manual en la UI.
































