rckrdmrd/erp-transportistas-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
6ed7f9e2ec
erp-transportistas-v2/docs/02-definicion-modulos/MAI-006-tracking
History
Adrian Flores Cortes 6ed7f9e2ec [BACKUP] Pre-restructure workspace backup 2026-01-29 
- Updated docs and inventory files
- Added new architecture docs

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-29 17:35:54 -06:00
..
historias-usuario [BACKUP] Pre-restructure workspace backup 2026-01-29 2026-01-29 17:35:54 -06:00
README.md [BACKUP] Pre-restructure workspace backup 2026-01-29 2026-01-29 17:35:54 -06:00
REQUERIMIENTOS.md docs: Add Phase 3 secondary modules specifications (P1/P2/P3) 2026-01-27 02:24:35 -06:00
RESUMEN-EPICA.md docs: Add Phase 3 secondary modules specifications (P1/P2/P3) 2026-01-27 02:24:35 -06:00

README.md

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
US-MAI006-011 Configurar dispositivo GPS 5 P1 Backlog
US-MAI006-012 Recibir posiciones GPS en tiempo real 8 P0 Backlog
US-MAI006-013 Validar posiciones GPS 5 P1 Backlog
US-MAI006-014 Cambiar proveedor GPS 5 P1 Backlog
US-MAI006-015 Configurar intervalo de tracking 3 P2 Backlog
Total 83

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_gps esta particionada por rango mensual en el campo fecha_particion para 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 imei en posiciones_gps permite asociar posiciones con dispositivos GPS fisicos independientemente de la unidad asignada.
  • Datos JSONB: Los campos datos, evidencias y notificaciones_enviadas utilizan 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