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/RESUMEN-EPICA.md
Adrian Flores Cortes ec43d9c6cd docs: Add Phase 3 secondary modules specifications (P1/P2/P3) 
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>
2026-01-27 02:24:35 -06:00

7.5 KiB
Raw Blame History

RESUMEN-EPICA.md - MAI-006 Tracking en Tiempo Real

Epica: EPIC-MAI-006 | Version: 1.0.0 | Actualizado: 2026-01-27

Epica

ID: EPIC-MAI-006 Titulo: Tracking en Tiempo Real Modulo: MAI-006 Schema BD: tracking DDL: database/ddl/03-tracking-schema-ddl.sql

Descripcion de la Epica

Implementar el sistema completo de rastreo GPS en tiempo real para la flota de transporte de carga. El sistema debe permitir la ingestion masiva de posiciones GPS desde multiples proveedores de telematica, la configuracion y evaluacion automatica de geocercas utilizando PostGIS, el calculo dinamico de ETA considerando factores de trafico y clima, y la generacion de alertas operativas con flujo de atencion. Debe proporcionar visibilidad completa del estado y ubicacion de todas las unidades tanto para el equipo de operaciones (coordinador de trafico) como para el cliente final a traves del portal.

Objetivos de Negocio

  1. Visibilidad operativa total: Conocer la ubicacion exacta de cada unidad en cualquier momento, eliminando la dependencia de llamadas telefonicas y mensajes manuales al operador.
  2. Proactividad ante desvios: Detectar automaticamente desvios de ruta, paradas prolongadas, excesos de velocidad y otros eventos criticos antes de que impacten el servicio al cliente.
  3. ETA confiable: Ofrecer a coordinadores y clientes un tiempo estimado de arribo dinamico y actualizado continuamente con base en la posicion real de la unidad.
  4. Satisfaccion del cliente: Brindar al cliente acceso directo a la posicion de su envio y eventos relevantes del viaje a traves del portal.
  5. Trazabilidad completa: Mantener un historial detallado de todas las posiciones y eventos de cada viaje para analisis posterior, reportes y resolucion de disputas.
  6. Seguridad de la carga: Alertar inmediatamente sobre situaciones de riesgo como ingreso a zonas peligrosas, boton de panico o apertura de puertas no autorizada.

Alcance

Incluido

  • Ingestion y almacenamiento de posiciones GPS con particionamiento mensual
  • CRUD de geocercas circulares y poligonales con PostGIS
  • Evaluacion automatica de posiciones contra geocercas activas
  • Calculo y recalculo dinamico de ETA por viaje y por parada
  • Sistema de alertas configurable con 11 tipos y 3 niveles de severidad
  • Reglas de alerta configurables por tenant con condiciones JSONB
  • Flujo de atencion de alertas (leida, atendida, resolucion)
  • Dashboard de flota en tiempo real con mapa interactivo
  • Historial de recorrido por viaje con metricas
  • Generacion de reportes de recorrido
  • Integracion con dispositivos GPS via IMEI/proveedor
  • Actualizaciones en tiempo real via WebSocket
  • Row Level Security (RLS) por tenant en todas las tablas

Excluido

  • Optimizacion automatica de rutas (MAA-019)
  • App movil del operador (componente transversal, no exclusivo de tracking)
  • Notificaciones omnicanal avanzadas (WhatsApp/SMS) - solo configuracion de destinatarios
  • Integracion EDI con clientes (MAA-020)
  • Procesamiento de datos de temperatura y cadena de frio (fase posterior)

Metricas de Exito

Metrica Objetivo
Latencia de ingestion GPS < 5 segundos desde recepcion hasta persistencia
Evaluacion de geocercas < 2 segundos por posicion procesada
Recalculo de ETA Cada 5 minutos para viajes activos
Tiempo de deteccion de alertas < 30 segundos desde evento desencadenante
Disponibilidad del mapa de flota 99.5% uptime
Cobertura de tracking 100% de viajes activos con posicion actualizada cada 2 minutos

Historias de Usuario

ID Titulo SP Prioridad Sprint
US-MAI006-001 Ver posicion actual de unidad en mapa 5 P0 Por asignar
US-MAI006-002 Configurar geocercas 8 P0 Por asignar
US-MAI006-003 Recibir alerta de entrada/salida geocerca 5 P0 Por asignar
US-MAI006-004 Consultar ETA dinamico del viaje 8 P0 Por asignar
US-MAI006-005 Ver historial de ruta recorrida 5 P1 Por asignar
US-MAI006-006 Configurar alertas por tipo de evento 5 P1 Por asignar
US-MAI006-007 Detectar desvio de ruta 8 P1 Por asignar
US-MAI006-008 Ver dashboard de flota en tiempo real 5 P1 Por asignar
US-MAI006-009 Generar reporte de recorrido 3 P2 Por asignar
US-MAI006-010 Integrar dispositivo GPS 5 P1 Por asignar
Total 57

Distribucion por Prioridad

Prioridad Historias Story Points Descripcion
P0 4 26 Funcionalidades criticas: posicion en mapa, geocercas, alertas geocerca, ETA
P1 4 23 Funcionalidades importantes: historial, configuracion alertas, desvio ruta, dashboard
P2 1 3 Funcionalidades deseables: reporte de recorrido
P1 1 5 Infraestructura: integracion dispositivo GPS

Dependencias

Internas (otros modulos ERP Transportistas)

Modulo Dependencia Tipo
MAI-001 Fundamentos Auth, RBAC, multi-tenancy Bloqueante
MAI-003 Ordenes de Transporte Viaje (viaje_id), Paradas (parada_id) Bloqueante
MAI-011 Gestion de Flota Unidad (unidad_id), Operador (operador_id) Bloqueante

Externas (infraestructura/servicios)

Servicio Dependencia Tipo
PostgreSQL + PostGIS Extension PostGIS habilitada, funciones ST_*, indices GIST Bloqueante
WebSocket Gateway NestJS WebSocket (Socket.IO o ws) para actualizaciones en tiempo real Bloqueante
Proveedor GPS/Telematica API o webhook de proveedor para ingestion de posiciones Requerido para produccion
Servicio de Mapas Libreria de mapas frontend (Leaflet, Mapbox GL) para visualizacion Requerido para frontend

Riesgos

Riesgo Impacto Probabilidad Mitigacion
Alto volumen de datos GPS Alto Alta Particionamiento mensual de posiciones_gps, indices optimizados, politica de retencion
Latencia en evaluacion de geocercas Medio Media Indices GIST de PostGIS, cache de geocercas activas en Redis, evaluacion asincrona
Conectividad intermitente del dispositivo GPS Medio Alta Buffer local en dispositivo, reconciliacion por timestamp_gps vs timestamp_servidor
Multiples proveedores GPS con formatos distintos Medio Alta Capa de abstraccion (adapter pattern) por proveedor, normalizacion a schema unificado
Sobrecarga de alertas (alert fatigue) Medio Media Reglas configurables por tenant, agrupacion de alertas repetidas, cooldown configurable

Notas Tecnicas

  • PostGIS: El indice idx_posicion_geo utiliza ST_SetSRID(ST_MakePoint(longitud, latitud), 4326) para indexar posiciones espacialmente. Las geocercas poligonales se almacenan directamente como GEOMETRY(POLYGON, 4326) con indice GIST en idx_geocerca_geo.
  • Particionamiento: Se crean particiones mensuales de posiciones_gps (ejemplo: posiciones_gps_2026_01, posiciones_gps_2026_02, posiciones_gps_2026_03). Se requiere un proceso automatizado para crear particiones futuras.
  • RLS: Todas las tablas del schema tracking implementan Row Level Security con politica tenant_id = current_setting('app.tenant_id')::uuid para aislamiento multi-tenant.
  • JSONB: Los campos condiciones en reglas_alerta, datos y evidencias en eventos, y notificaciones_enviadas en alertas utilizan JSONB para flexibilidad y consultas indexables.

EPIC-MAI-006 Tracking en Tiempo Real - ERP Transportistas v1.0.0