rckrdmrd/erp-transportistas-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
e5e816887b
erp-transportistas-v2/docs/02-definicion-modulos/MAI-006-tracking/REQUERIMIENTOS.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

167 lines
13 KiB
Markdown
Raw 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*
Reference in New Issue View Git Blame Copy Permalink