ec43d9c6cd
Modules documented: - MAI-003 (OT): README, REQUERIMIENTOS, RESUMEN-EPICA, 10 US - MAI-006 (Tracking): README, REQUERIMIENTOS, RESUMEN-EPICA - MAI-008 (Incidencias): 3 US (18 SP) - MAI-011 (Flota): README, REQUERIMIENTOS, RESUMEN-EPICA - MAI-012 (Combustible): 3 US (18 SP) - MAI-013 (Mantenimiento): 3 US (18 SP) - MAI-014 (Carriers): 3 US (18 SP) - MAI-015 (Portal): 3 US (18 SP) - MAE-016 (Carta Porte): 10 US - MAE-017 (HOS): 3 US (16 SP) - MAE-018 (Reportes): 3 US (18 SP) Phase 2+3 complete: 13 modules, 50+ User Stories Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
11 KiB
MAI-006: Tracking en Tiempo Real
Modulo: MAI-006 | Version: 1.0.0 | Actualizado: 2026-01-27
Schema BD: tracking | DDL: database/ddl/03-tracking-schema-ddl.sql
Descripcion
Sistema de rastreo GPS en tiempo real para unidades de transporte de carga. Permite la ingestion de posiciones GPS, la deteccion automatica de eventos mediante geocercas, el calculo dinamico de ETA y la generacion de alertas operativas. Brinda visibilidad completa del viaje tanto al coordinador de trafico como al cliente final a traves del portal.
Componentes Principales
| Componente | Descripcion |
|---|---|
| Receptor GPS | Ingestion de posiciones GPS desde dispositivos/proveedores de telematica (latitud, longitud, velocidad, rumbo, odometro, HDOP, satelites) |
| Motor de Geocercas | Evaluacion en tiempo real de posiciones contra geocercas poligonales y circulares utilizando PostGIS (ST_DWithin, ST_Contains) |
| Calculador ETA | Recalculo dinamico de tiempo estimado de arribo considerando distancia restante, factor de trafico y factor de clima |
| Sistema de Alertas | Generacion automatica de alertas por reglas configurables: desvio de ruta, exceso de velocidad, parada prolongada, entrada/salida de geocerca, boton de panico, entre otros |
| Historial de Tracking | Almacenamiento particionado por fecha de todas las posiciones GPS para consulta historica y generacion de reportes de recorrido |
| Mapa en Tiempo Real | Visualizacion en mapa de la posicion actual de todas las unidades de la flota con actualizacion via WebSocket |
Actores
| Actor | Rol en el Modulo |
|---|---|
| Coordinador de Trafico | Monitorea flota en tiempo real, atiende alertas, valida desvios, configura geocercas y reglas de alerta |
| Cliente (Portal) | Consulta posicion actual de su envio, ETA dinamico, historial de eventos del viaje |
| Sistema Automatico | Procesa posiciones GPS, evalua geocercas, genera alertas, recalcula ETAs, envia notificaciones |
| Operador/Conductor | Genera eventos manuales desde app movil (arribo, incidente), porta dispositivo GPS |
| Jefe de Flota | Consulta dashboard de flota, analiza reportes de recorrido y eficiencia |
Funcionalidades
F1. Ingestion de Eventos GPS
Recepcion y almacenamiento de posiciones GPS provenientes de dispositivos de telematica. Cada evento incluye: latitud, longitud, altitud, velocidad en km/h, rumbo (0-360 grados), odometro, estado del motor, HDOP (precision horizontal), numero de satelites, IMEI del dispositivo y proveedor GPS. Las posiciones se almacenan en la tabla tracking.posiciones_gps, particionada mensualmente por fecha_particion para optimizar consultas historicas.
F2. Geocercas (Geofencing)
Definicion de zonas de interes como geocercas circulares (centro + radio en metros) o poligonales (geometria POLYGON SRID 4326). Tipos soportados: CLIENTE, PROVEEDOR, PATIO, ZONA_RIESGO, CASETA, GASOLINERA, PUNTO_CONTROL, OTRO. Cada geocerca puede configurarse con alertas de entrada y/o salida y un tiempo maximo de permanencia. El motor de geocercas utiliza indices GIST de PostGIS para evaluar cada posicion GPS contra las geocercas activas del tenant.
F3. ETA Dinamico
Calculo y recalculo continuo del tiempo estimado de arribo (ETA) para cada viaje activo. El sistema registra el ETA original, el ETA recalculado actual y el anterior, junto con la distancia restante en km, el tiempo restante en minutos, factores de ajuste por trafico y clima, y el estado resultante (EN_TIEMPO, ADELANTADO, RETRASADO) con los minutos de diferencia. Los calculos se almacenan en tracking.eta_calculado para trazabilidad historica.
F4. Alertas Operativas
Generacion automatica de alertas basada en reglas configurables por tenant. Tipos de alerta: ENTRADA_GEOCERCA, SALIDA_GEOCERCA, EXCESO_VELOCIDAD, PARADA_PROLONGADA, DESVIO_RUTA, TEMPERATURA_FUERA_RANGO, BATERIA_BAJA, SIN_SENAL, BOTON_PANICO, APERTURA_PUERTA, CONSUMO_ANOMALO. Cada alerta tiene severidad (INFO, WARNING, CRITICAL), puede ser leida y atendida con resolucion documentada, y dispara notificaciones configurables por email, SMS y push.
F5. Historial de Tracking
Consulta de la ruta historica recorrida por una unidad en un rango de fechas. Permite reconstruir el trayecto completo de un viaje, calcular distancias reales vs planeadas, identificar paradas y desvios, y generar reportes detallados de recorrido con metricas de velocidad promedio, maxima, tiempo en movimiento y tiempo detenido.
F6. Dashboard de Flota en Tiempo Real
Visualizacion en mapa de la posicion actual de todas las unidades de la flota. Incluye filtros por estado del viaje, tipo de unidad, operador asignado y alertas activas. Actualizacion en tiempo real via WebSocket. Muestra indicadores clave: unidades en movimiento, detenidas, con alertas criticas y fuera de cobertura.
Entidades (Schema: tracking)
| Entidad | Tabla DDL | Descripcion |
|---|---|---|
| PosicionGps | tracking.posiciones_gps |
Posiciones GPS particionadas por fecha. Campos: latitud, longitud, altitud, velocidad_kmh, rumbo, odometro, motor_encendido, hdop, satelites, proveedor_gps, imei |
| Evento | tracking.eventos |
Eventos de tracking durante viajes. Campos: tipo_evento, fuente, latitud, longitud, direccion, datos (JSONB), parada_id, evidencias (JSONB) |
| Geocerca | tracking.geocercas |
Geocercas/zonas de interes. Campos: codigo, nombre, tipo, es_circular, centro_latitud/longitud, radio_metros, poligono (GEOMETRY POLYGON 4326), alerta_entrada/salida, tiempo_permanencia_minutos |
| Alerta | tracking.alertas |
Alertas generadas por el sistema. Campos: tipo, severidad, titulo, mensaje, datos (JSONB), leida, atendida, resolucion, notificaciones_enviadas |
| ReglaAlerta | tracking.reglas_alerta |
Reglas configurables para generacion de alertas. Campos: nombre, tipo_alerta, severidad, condiciones (JSONB), aplica_todas_unidades, unidades_ids, notificar_email/sms/push, destinatarios |
| EtaCalculado | tracking.eta_calculado |
Historial de calculos de ETA. Campos: eta_original, eta_actual, eta_anterior, distancia_restante_km, tiempo_restante_minutos, factor_trafico, factor_clima, estado, minutos_diferencia |
ENUMs
| Enum | Valores |
|---|---|
tipo_geocerca |
CLIENTE, PROVEEDOR, PATIO, ZONA_RIESGO, CASETA, GASOLINERA, PUNTO_CONTROL, OTRO |
severidad_alerta |
INFO, WARNING, CRITICAL |
tipo_alerta |
ENTRADA_GEOCERCA, SALIDA_GEOCERCA, EXCESO_VELOCIDAD, PARADA_PROLONGADA, DESVIO_RUTA, TEMPERATURA_FUERA_RANGO, BATERIA_BAJA, SIN_SENAL, BOTON_PANICO, APERTURA_PUERTA, CONSUMO_ANOMALO |
API Endpoints
| Metodo | Endpoint | Descripcion |
|---|---|---|
| POST | /api/tracking/posiciones |
Registrar posicion GPS (ingestion desde dispositivo/proveedor) |
| GET | /api/tracking/posiciones/:unidadId/actual |
Obtener ultima posicion conocida de una unidad |
| GET | /api/tracking/posiciones/:unidadId/historial |
Obtener historial de posiciones (con rango de fechas) |
| GET | /api/tracking/viajes/:viajeId/recorrido |
Obtener recorrido completo de un viaje |
| POST | /api/tracking/geocercas |
Crear geocerca (circular o poligonal) |
| GET | /api/tracking/geocercas |
Listar geocercas del tenant |
| GET | /api/tracking/geocercas/:id |
Obtener detalle de geocerca |
| PUT | /api/tracking/geocercas/:id |
Actualizar geocerca |
| DELETE | /api/tracking/geocercas/:id |
Desactivar geocerca |
| GET | /api/tracking/alertas |
Listar alertas (filtros: tipo, severidad, atendida, rango fechas) |
| GET | /api/tracking/alertas/:id |
Obtener detalle de alerta |
| PATCH | /api/tracking/alertas/:id/leer |
Marcar alerta como leida |
| PATCH | /api/tracking/alertas/:id/atender |
Marcar alerta como atendida con resolucion |
| POST | /api/tracking/reglas-alerta |
Crear regla de alerta |
| GET | /api/tracking/reglas-alerta |
Listar reglas de alerta |
| PUT | /api/tracking/reglas-alerta/:id |
Actualizar regla de alerta |
| DELETE | /api/tracking/reglas-alerta/:id |
Desactivar regla de alerta |
| GET | /api/tracking/eta/:viajeId |
Obtener ETA actual del viaje |
| GET | /api/tracking/eta/:viajeId/historial |
Obtener historial de calculos ETA |
| GET | /api/tracking/flota/dashboard |
Dashboard de flota en tiempo real |
| GET | /api/tracking/viajes/:viajeId/reporte |
Generar reporte de recorrido del viaje |
| WS | /ws/tracking/flota |
WebSocket para actualizaciones en tiempo real de posiciones |
| WS | /ws/tracking/alertas |
WebSocket para notificaciones de alertas en tiempo real |
Historias de Usuario
| ID | Titulo | SP | Prioridad | Estado |
|---|---|---|---|---|
| US-MAI006-001 | Ver posicion actual de unidad en mapa | 5 | P0 | Backlog |
| US-MAI006-002 | Configurar geocercas | 8 | P0 | Backlog |
| US-MAI006-003 | Recibir alerta de entrada/salida geocerca | 5 | P0 | Backlog |
| US-MAI006-004 | Consultar ETA dinamico del viaje | 8 | P0 | Backlog |
| US-MAI006-005 | Ver historial de ruta recorrida | 5 | P1 | Backlog |
| US-MAI006-006 | Configurar alertas por tipo de evento | 5 | P1 | Backlog |
| US-MAI006-007 | Detectar desvio de ruta | 8 | P1 | Backlog |
| US-MAI006-008 | Ver dashboard de flota en tiempo real | 5 | P1 | Backlog |
| US-MAI006-009 | Generar reporte de recorrido | 3 | P2 | Backlog |
| US-MAI006-010 | Integrar dispositivo GPS | 5 | P1 | Backlog |
| Total | 57 |
Dependencias
Depende de
| Modulo | Motivo |
|---|---|
| MAI-001 (Fundamentos) | Auth, RBAC, multi-tenancy, tenant_id en RLS policies |
| MAI-003 (Ordenes de Transporte) | viaje_id referenciado en posiciones_gps, eventos, alertas y eta_calculado |
| MAI-011 (Gestion de Flota) | unidad_id referenciado en posiciones_gps y alertas; operador_id en alertas |
Bloquea a
| Modulo | Motivo |
|---|---|
| MAI-005 (Despacho) | Visibilidad de tracking post-despacho |
| MAI-007 (POD y Cierre) | Eventos de tracking para cierre operativo, tiempos reales |
| MAI-008 (Incidencias) | Alertas que pueden derivar en incidencias |
| MAI-015 (Portal Cliente) | Mapa de tracking, ETA y eventos para el cliente |
| MAE-018 (Reportes y KPIs) | Datos de tracking para KPIs de puntualidad y eficiencia |
Notas Tecnicas
- PostGIS: Se requiere la extension PostGIS habilitada. Los indices espaciales GIST se utilizan para consultas de proximidad (ST_DWithin) y contencion (ST_Contains) en la evaluacion de geocercas.
- Particionamiento: La tabla
posiciones_gpsesta particionada por rango mensual en el campofecha_particionpara manejar el alto volumen de datos GPS sin degradar el rendimiento. - WebSocket: Las actualizaciones en tiempo real del mapa de flota y las notificaciones de alertas se transmiten via WebSocket (Socket.IO o ws nativo de NestJS) con canales por tenant.
- RLS (Row Level Security): Todas las tablas del schema tracking tienen politicas RLS activas que filtran por
tenant_id = current_setting('app.tenant_id')::uuid. - SRID 4326: Todas las coordenadas geograficas utilizan el sistema de referencia WGS 84 (SRID 4326), estandar para GPS.
- IMEI: El campo
imeienposiciones_gpspermite asociar posiciones con dispositivos GPS fisicos independientemente de la unidad asignada. - Datos JSONB: Los campos
datos,evidenciasynotificaciones_enviadasutilizan JSONB para flexibilidad en el almacenamiento de metadatos variables por tipo de evento o alerta.
MAI-006 Tracking en Tiempo Real - ERP Transportistas v1.0.0