erp-transportistas-v2/docs/02-definicion-modulos/MAI-006-tracking/historias-usuario/US-MAI006-012-recibir-posiciones-tiempo-real.md

US-MAI006-012: Recibir posiciones GPS en tiempo real

Metadata

Campo	Valor
ID	US-MAI006-012
Epica	EPIC-MAI-006 - Tracking en Tiempo Real
Modulo	tracking
Prioridad	P0
Story Points	8
Sprint	Por asignar
Estado	Backlog

Historia de Usuario

Como coordinador de trafico de una empresa transportista, quiero ver las posiciones GPS de las unidades actualizandose cada 30 segundos en el mapa, para monitorear la ubicacion de la flota en tiempo real y tomar decisiones operativas informadas.

Descripcion Detallada

La recepcion de posiciones GPS en tiempo real es la funcionalidad central del modulo de tracking. El sistema debe ser capaz de recibir posiciones desde multiples fuentes (webhooks de proveedores GPS, polling a APIs, ingesta manual) y procesarlas de manera eficiente para que se visualicen en el mapa de flota con minima latencia.

Cada posicion recibida se almacena en la tabla particionada tracking.posiciones_gps con todos los metadatos disponibles (velocidad, rumbo, altitud, odometro, estado del motor, precision GPS). El sistema identifica la unidad correspondiente a traves del IMEI del dispositivo y, si la unidad tiene un viaje activo, asocia la posicion al viaje.

Las actualizaciones se transmiten a los clientes web conectados a traves de WebSocket, permitiendo que el mapa se actualice sin necesidad de hacer polling. El intervalo de actualizacion configurado (por defecto 30 segundos) determina la frecuencia esperada de posiciones, y se generan alertas cuando un dispositivo deja de reportar.

Criterios de Aceptacion

Escenario 1: Recibir posicion via webhook del proveedor GPS

Dado que existe un dispositivo GPS activo con IMEI "352093088937641" asociado a la Unidad T-001, Cuando el proveedor GPS (Traccar) envia un webhook con la posicion: lat 19.4326, lon -99.1332, velocidad 65 km/h, timestamp 2026-01-27T14:30:00Z, Entonces el sistema crea un registro en tracking.posiciones_gps con todos los datos, asociado a la unidad correspondiente, y emite la actualizacion via WebSocket al canal /ws/tracking/flota.

Escenario 2: Asociar posicion a viaje activo

Dado que la Unidad T-001 tiene un viaje activo (estado EN_TRANSITO) y recibe una nueva posicion GPS, Cuando se procesa la posicion, Entonces el sistema asocia la posicion al viaje activo (viaje_id) permitiendo trazar el recorrido del viaje y calcular distancia recorrida.

Escenario 3: Actualizar mapa en tiempo real via WebSocket

Dado que el coordinador tiene abierto el dashboard de flota con el mapa, Cuando se recibe una nueva posicion de cualquier unidad del tenant, Entonces el marcador de la unidad en el mapa se mueve a la nueva posicion en menos de 2 segundos desde que se proceso la posicion, mostrando velocidad actual y direccion.

Escenario 4: Detectar dispositivo sin reportar

Dado que un dispositivo GPS tiene configurado intervalo de 30 segundos y no ha reportado en los ultimos 5 minutos, Cuando el sistema ejecuta la verificacion periodica de conectividad, Entonces se genera una alerta de tipo "SIN_SENAL" con severidad WARNING para la unidad correspondiente y se muestra indicador visual de "Sin conexion" en el mapa.

Escenario 5: Almacenar posicion con datos completos

Dado que se recibe una posicion GPS con todos los datos opcionales (altitud, rumbo, odometro, motor_encendido, hdop, satelites), Cuando se procesa la posicion, Entonces todos los campos se almacenan correctamente en la BD y estan disponibles para consulta en el historial de posiciones.

Escenario 6: Alta frecuencia de posiciones

Dado que el sistema recibe 100 posiciones por segundo de diferentes unidades, Cuando se procesan las posiciones, Entonces todas se almacenan correctamente sin perdida de datos y el tiempo de procesamiento por posicion es menor a 100ms.

Tareas Tecnicas

• Database: Verificar tabla tracking.posiciones_gps particionada por mes (campo fecha_particion). Verificar indices: idx_posicion_unidad_fecha, idx_posicion_viaje, idx_posicion_geo (GIST). Crear particion para el mes actual si no existe.
• Backend: Crear PositionIngestionService con metodo ingestPosition() que: 1) Identifica unidad por IMEI, 2) Valida posicion, 3) Asocia a viaje activo si existe, 4) Almacena en BD, 5) Emite via WebSocket. Crear WebhookController con endpoint POST /api/webhooks/gps/:provider. Implementar adaptadores para cada proveedor (Traccar, Wialon, Samsara, Geotab).
• WebSocket: Implementar gateway WebSocket (TrackingGateway) con canal /ws/tracking/flota segregado por tenant_id. Emitir eventos position.updated con payload: {unidadId, lat, lon, velocidad, rumbo, timestamp}.
• Frontend: Implementar hook useFleetWebSocket() que conecta al canal de tracking. Actualizar estado del mapa cuando se reciben posiciones. Mostrar indicador de ultima actualizacion por unidad.
• Monitoring: Implementar job cron CheckDeviceConnectivity que se ejecuta cada minuto y genera alertas para dispositivos sin reportar.
• Tests: Tests de ingestion de posiciones. Tests de emision WebSocket. Tests de carga (100+ posiciones/segundo).

Dependencias

• Depende de: US-MAI006-011 (configurar dispositivo GPS), MAI-011 (unidades), MAI-003 (viajes)
• Bloquea: US-MAI006-001 (ver posicion actual), US-MAI006-005 (historial), US-MAI006-003 (alertas geocerca)

Notas Tecnicas

• Webhook Endpoints:
  • POST /api/webhooks/gps/traccar
  • POST /api/webhooks/gps/wialon
  • POST /api/webhooks/gps/samsara
  • POST /api/webhooks/gps/geotab
• WebSocket Gateway: @WebSocketGateway({ namespace: '/tracking' })
• Canal WebSocket: /ws/tracking/flota - segregado por tenant via query param o header
• Particionamiento: Las posiciones se almacenan en particiones mensuales (posiciones_gps_2026_01, posiciones_gps_2026_02, etc.)
• Timeout sin senal: Generar alerta si no hay posiciones en 5 * intervalo_configurado (default: 150 segundos)
• Bulk insert: Para alto volumen, usar insert en lotes de 100 posiciones
• Redis cache: Cachear ultima posicion conocida de cada unidad en Redis para consultas rapidas

---

US-MAI006-012 - ERP Transportistas v1.0.0