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

13 KiB

Raw Permalink Blame History

REQUERIMIENTOS.md - MAI-006 Tracking en Tiempo Real

Modulo: MAI-006 | Version: 1.0.0 | Actualizado: 2026-01-27 Referencia: REQ-GIRO-TRANSPORTISTA.md (Secciones 4.5, 4.13)

Requerimientos Funcionales

RF-MAI006-001: Ingestion de Posiciones GPS

Prioridad: P0 | Origen: RF-4.5.1

El sistema debe recibir y almacenar posiciones GPS provenientes de dispositivos de telematica. Cada posicion debe incluir como minimo: latitud (DECIMAL 10,7), longitud (DECIMAL 10,7), velocidad en km/h, timestamp del GPS y la unidad asociada. Opcionalmente puede incluir: altitud, rumbo (0-360 grados), odometro, estado del motor (encendido/apagado), 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. Si la unidad esta asociada a un viaje activo, se debe registrar el viaje_id.

Tabla DDL: tracking.posiciones_gps Indices: idx_posicion_unidad_fecha (unidad_id, timestamp_gps), idx_posicion_viaje (viaje_id WHERE NOT NULL), idx_posicion_geo GIST (ST_SetSRID(ST_MakePoint(longitud, latitud), 4326))

RF-MAI006-002: Consulta de Posicion Actual

Prioridad: P0 | Origen: RF-4.5.1, RF-4.13.1

El sistema debe permitir obtener la ultima posicion conocida de una unidad, incluyendo: latitud, longitud, velocidad, rumbo, timestamp GPS, estado del motor y viaje asociado. La consulta se resuelve obteniendo el registro mas reciente de tracking.posiciones_gps para la unidad indicada, ordenando por timestamp_gps DESC LIMIT 1. El endpoint debe soportar consulta individual por unidad y consulta masiva de toda la flota del tenant.

RF-MAI006-003: Registro de Eventos de Tracking

Prioridad: P0 | Origen: RF-4.5.2

El sistema debe registrar eventos de tracking durante la ejecucion de un viaje. Cada evento se almacena en tracking.eventos con: viaje_id (obligatorio), tipo_evento, fuente (OPERADOR, SISTEMA, USUARIO), ubicacion (latitud, longitud, direccion), timestamp del evento, datos especificos en JSONB, parada asociada (si aplica), generado_por_id y tipo, evidencias en JSONB, y observaciones. Los eventos pueden ser generados automaticamente por el sistema (geocercas, alertas) o manualmente por el operador a traves de la app movil.

Tabla DDL: tracking.eventos Indices: idx_evento_viaje (viaje_id), idx_evento_tipo (tenant_id, tipo_evento), idx_evento_fecha (timestamp_evento)

RF-MAI006-004: CRUD de Geocercas

Prioridad: P0 | Origen: RF-4.5.4

El sistema debe permitir crear, consultar, actualizar y desactivar geocercas. Cada geocerca se almacena en tracking.geocercas con: codigo (unico por tenant), nombre, tipo (CLIENTE, PROVEEDOR, PATIO, ZONA_RIESGO, CASETA, GASOLINERA, PUNTO_CONTROL, OTRO). Las geocercas pueden ser circulares (centro_latitud, centro_longitud, radio_metros) o poligonales (poligono GEOMETRY POLYGON 4326). Cada geocerca configura: alerta_entrada (boolean), alerta_salida (boolean), tiempo_permanencia_minutos (alerta si excede), color de visualizacion, estado activa/inactiva, y opcionalmente un cliente asociado y direccion.

Tabla DDL: tracking.geocercas Indices: idx_geocerca_tenant (tenant_id), idx_geocerca_tipo (tenant_id, tipo), idx_geocerca_geo GIST (poligono), idx_geocerca_codigo UNIQUE (tenant_id, codigo)

RF-MAI006-005: Evaluacion Automatica de Geocercas

Prioridad: P0 | Origen: RF-4.5.4

El sistema debe evaluar automaticamente cada posicion GPS recibida contra las geocercas activas del tenant. Para geocercas circulares, se utiliza ST_DWithin comparando la posicion con el punto centro y el radio en metros. Para geocercas poligonales, se utiliza ST_Contains verificando si la posicion esta dentro del poligono. Cuando una unidad ingresa o abandona una geocerca, el sistema debe generar automaticamente un evento en tracking.eventos y, si la geocerca tiene configurada la alerta correspondiente (alerta_entrada o alerta_salida), generar una alerta en tracking.alertas.

RF-MAI006-006: Generacion de Alertas

Prioridad: P0 | Origen: RF-4.5.5

El sistema debe generar alertas automaticas almacenadas en tracking.alertas con: tipo (tipo_alerta: 11 valores posibles), severidad (INFO, WARNING, CRITICAL), referencias (unidad_id, viaje_id, geocerca_id, operador_id), ubicacion, titulo, mensaje, datos especificos en JSONB, y timestamp. Las alertas se crean con estado leida=FALSE y atendida=FALSE. Al ser leida se registra leida_por y leida_fecha. Al ser atendida se registra atendida_por, atendida_fecha y resolucion (texto). El campo notificaciones_enviadas (JSONB) registra los canales por los que se notifico.

Tabla DDL: tracking.alertas Indices: idx_alerta_tenant, idx_alerta_unidad, idx_alerta_viaje, idx_alerta_no_atendida (WHERE atendida = FALSE), idx_alerta_fecha

RF-MAI006-007: Configuracion de Reglas de Alerta

Prioridad: P1 | Origen: RF-4.5.5

El sistema debe permitir configurar reglas de alerta en tracking.reglas_alerta. Cada regla define: nombre, descripcion, tipo_alerta que genera, severidad por defecto, condiciones en JSONB (ejemplo: {"velocidad_max": 100, "tiempo_parada_max_min": 30, "temp_min": -18, "temp_max": -15}), aplicabilidad (todas las unidades o lista especifica de unidades_ids UUID[]), canales de notificacion (email, SMS, push), lista de destinatarios en JSONB, y estado activa/inactiva. El sistema evalua las reglas activas del tenant al procesar cada posicion GPS o evento relevante.

Tabla DDL: tracking.reglas_alerta Indices: idx_regla_tenant (tenant_id), idx_regla_tipo (tipo_alerta WHERE activa = TRUE)

RF-MAI006-008: Calculo de ETA Dinamico

Prioridad: P0 | Origen: RF-4.5.3, RF-4.3.6

El sistema debe calcular y recalcular periodicamente el tiempo estimado de arribo (ETA) para cada viaje activo. Cada calculo se almacena en tracking.eta_calculado con: viaje_id, parada_id (opcional, para ETA por parada), eta_original (programado), eta_actual (recalculado), eta_anterior (para comparacion), distancia_restante_km, tiempo_restante_minutos, factor_trafico (multiplicador decimal), factor_clima (multiplicador decimal), estado (EN_TIEMPO, ADELANTADO, RETRASADO), y minutos_diferencia respecto al eta_original. El calculo considera la posicion actual de la unidad, la distancia restante y los factores de ajuste.

Tabla DDL: tracking.eta_calculado Indices: idx_eta_viaje (viaje_id), idx_eta_fecha (calculado_at)

RF-MAI006-009: Historial de Recorrido

Prioridad: P1 | Origen: RF-4.5.1

El sistema debe permitir consultar el historial completo de posiciones GPS de una unidad o viaje en un rango de fechas. La consulta se ejecuta sobre tracking.posiciones_gps filtrando por unidad_id o viaje_id y rango de timestamp_gps. El resultado debe incluir las posiciones ordenadas cronologicamente y permitir la reconstruccion visual del recorrido en mapa. El sistema debe calcular metricas derivadas: distancia total recorrida, velocidad promedio, velocidad maxima, tiempo en movimiento, tiempo detenido, y numero de paradas.

RF-MAI006-010: Deteccion de Desvio de Ruta

Prioridad: P1 | Origen: RF-4.5.5

El sistema debe detectar cuando una unidad se desvia de la ruta planeada. Se compara la posicion GPS actual contra el corredor de la ruta esperada (buffer geometrico alrededor de la ruta planeada). Si la posicion cae fuera del corredor definido, se genera una alerta de tipo DESVIO_RUTA con severidad WARNING o CRITICAL segun la distancia de desvio. La deteccion utiliza funciones PostGIS como ST_Distance y ST_Buffer para calcular la distancia entre la posicion y la geometria de la ruta.

RF-MAI006-011: Dashboard de Flota en Tiempo Real

Prioridad: P1 | Origen: RF-4.5.1, RF-4.13.1

El sistema debe proporcionar un dashboard de flota con mapa interactivo mostrando la posicion actual de todas las unidades del tenant. El dashboard debe incluir: visualizacion en mapa con iconos por estado (en movimiento, detenida, con alerta), filtros por estado de viaje, tipo de unidad y operador, contadores de unidades en movimiento/detenidas/con alertas/fuera de cobertura, lista de alertas activas no atendidas, y panel de detalle al seleccionar una unidad. Las actualizaciones se transmiten via WebSocket para evitar polling constante.

RF-MAI006-012: Reporte de Recorrido

Prioridad: P2 | Origen: RF-4.5.1

El sistema debe generar reportes de recorrido por viaje con: ruta trazada en mapa, tabla de eventos con timestamps y ubicaciones, metricas de velocidad (promedio, maxima, distribucion), tiempos de parada por ubicacion, distancia planeada vs real, cumplimiento de geocercas (entradas/salidas con hora), alertas generadas durante el viaje, y ETA vs hora real de arribo. El reporte debe ser exportable en formato PDF.

RF-MAI006-013: Integracion de Dispositivo GPS

Prioridad: P1 | Origen: RF-4.5.1

El sistema debe soportar la ingestion de posiciones desde multiples proveedores de GPS/telematica. Cada posicion incluye el campo proveedor_gps (VARCHAR 50) y el imei (VARCHAR 50) del dispositivo. El sistema debe implementar una capa de abstraccion (adapter pattern) que normalice los datos de diferentes proveedores al esquema unificado de tracking.posiciones_gps. La asociacion entre IMEI y unidad se gestiona externamente (modulo flota MAI-011).

RF-MAI006-014: Notificaciones en Tiempo Real

Prioridad: P1 | Origen: RF-4.5.6

El sistema debe transmitir actualizaciones en tiempo real a traves de WebSocket. Se implementan dos canales: (1) canal de posiciones de flota (/ws/tracking/flota) que emite la ultima posicion de cada unidad cuando se actualiza, y (2) canal de alertas (/ws/tracking/alertas) que emite alertas nuevas al momento de generarse. Los canales estan segregados por tenant_id. Las reglas de alerta definen adicionalmente si se envia notificacion por email, SMS y/o push a los destinatarios configurados.

RF-MAI006-015: Aislamiento Multi-Tenant (RLS)

Prioridad: P0 | Origen: Transversal

Todas las tablas del schema tracking deben tener Row Level Security habilitado con politica de aislamiento por tenant: USING (tenant_id = current_setting('app.tenant_id')::uuid). Las tablas con RLS son: posiciones_gps, eventos, geocercas, alertas, reglas_alerta, eta_calculado. Ningun usuario debe poder acceder a datos de un tenant distinto al configurado en la sesion de base de datos.

Requerimientos No Funcionales

RNF-MAI006-001: Rendimiento de Ingestion

La ingestion de posiciones GPS debe procesar al menos 1,000 posiciones por segundo sin degradacion del rendimiento. El particionamiento mensual de posiciones_gps y los indices optimizados garantizan el rendimiento de escritura y lectura.

RNF-MAI006-002: Latencia de Evaluacion

La evaluacion de geocercas debe completarse en menos de 2 segundos por posicion procesada, incluyendo la verificacion contra todas las geocercas activas del tenant. Los indices GIST de PostGIS optimizan las consultas espaciales.

RNF-MAI006-003: Escalabilidad de Almacenamiento

El sistema debe soportar al menos 12 meses de historico de posiciones GPS sin degradacion significativa en consultas. La estrategia de particionamiento mensual permite la eliminacion selectiva de particiones antiguas y la creacion automatica de nuevas.

RNF-MAI006-004: Disponibilidad WebSocket

Los canales WebSocket de tracking y alertas deben mantener una disponibilidad del 99.5%. Se debe implementar reconexion automatica en el cliente frontend en caso de desconexion.

RNF-MAI006-005: Seguridad de Datos GPS

Los datos de posicion GPS son informacion sensible. Solo usuarios autorizados del tenant con los permisos adecuados (RBAC) pueden acceder a datos de tracking. Las politicas RLS proporcionan la primera capa de aislamiento a nivel de base de datos.

Trazabilidad con Requerimientos del Giro

RF del Giro	RF del Modulo	Cobertura
RF-4.5.1 Integracion GPS/Telematica	RF-MAI006-001, RF-MAI006-013	Completa
RF-4.5.3 ETA dinamico	RF-MAI006-008	Completa
RF-4.5.4 Geocercas (geofencing)	RF-MAI006-004, RF-MAI006-005	Completa
RF-4.5.5 Alertas	RF-MAI006-006, RF-MAI006-007, RF-MAI006-010	Completa
RF-4.5.6 Comunicacion omnicanal	RF-MAI006-014	Parcial (configuracion de canales; implementacion de WhatsApp/SMS en modulo externo)
RF-4.13.1 Tracking portal cliente	RF-MAI006-002, RF-MAI006-011	Parcial (datos disponibles; portal en MAI-015)
RF-4.3.6 Simulacion de ruta y ETA	RF-MAI006-008, RF-MAI006-010	Parcial (ETA dinamico si; simulacion previa en MAI-004)

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

13 KiB Raw Permalink Blame History