erp-transportistas-v2/docs/02-definicion-modulos/MAI-006-tracking/historias-usuario/US-MAI006-015-configurar-intervalo-tracking.md

US-MAI006-015: Configurar intervalo de tracking

Metadata

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

Historia de Usuario

Como jefe de flota de una empresa transportista, quiero ajustar la frecuencia con la que se reportan las posiciones GPS de cada unidad, para optimizar el balance entre precision del tracking, consumo de datos y costo del servicio de telematica.

Descripcion Detallada

El intervalo de tracking determina cada cuanto tiempo un dispositivo GPS envia su posicion al servidor. Un intervalo mas corto (por ejemplo, 10 segundos) proporciona tracking mas preciso pero consume mas datos y puede tener mayor costo con algunos proveedores. Un intervalo mas largo (por ejemplo, 5 minutos) reduce costos pero ofrece menor precision en el tracking.

El sistema permite configurar el intervalo a diferentes niveles:

1. Nivel tenant: Intervalo por defecto para todas las unidades
2. Nivel dispositivo: Intervalo especifico para un dispositivo particular
3. Nivel viaje: Intervalo temporal durante un viaje activo (por ejemplo, tracking mas frecuente durante entregas)

La configuracion del intervalo puede requerir comunicacion con el dispositivo GPS (si el proveedor lo soporta) o simplemente establecer la expectativa de frecuencia (para alertas de "sin senal"). Algunos proveedores permiten configurar el intervalo remotamente, otros requieren configuracion manual en el dispositivo.

Criterios de Aceptacion

Escenario 1: Configurar intervalo por defecto del tenant

Dado que el administrador accede a la configuracion de tracking del tenant, Cuando establece el intervalo por defecto en 60 segundos, Entonces el sistema guarda la configuracion, aplica el nuevo intervalo a todos los dispositivos sin configuracion especifica, y actualiza el umbral de "sin senal" (5 * 60 = 300 segundos).

Escenario 2: Configurar intervalo especifico por dispositivo

Dado que el jefe de flota quiere tracking mas frecuente para la unidad T-001 (carga de alto valor), Cuando configura el intervalo del dispositivo en 15 segundos, Entonces el dispositivo tiene prioridad sobre la configuracion del tenant, las alertas de "sin senal" se ajustan a 75 segundos (5 * 15), y si el proveedor lo soporta, se envia comando de configuracion al dispositivo.

Escenario 3: Activar modo tracking intensivo durante viaje

Dado que un viaje tiene configurado "tracking intensivo" (intervalo 10 segundos), Cuando el viaje cambia a estado EN_TRANSITO, Entonces el sistema aplica temporalmente el intervalo de 10 segundos al dispositivo de la unidad asignada, y al finalizar el viaje (ENTREGADO/CERRADO) restaura el intervalo normal.

Escenario 4: Validar intervalo minimo y maximo

Dado que el usuario intenta configurar un intervalo de 5 segundos (menor al minimo permitido de 10 segundos), Cuando intenta guardar la configuracion, Entonces el sistema muestra error "El intervalo minimo es 10 segundos" y no guarda el cambio.

Dado que el usuario intenta configurar un intervalo de 10 minutos (mayor al maximo permitido de 5 minutos), Cuando intenta guardar la configuracion, Entonces el sistema muestra error "El intervalo maximo es 300 segundos (5 minutos)" y no guarda el cambio.

Escenario 5: Ver intervalo efectivo de cada dispositivo

Dado que el jefe de flota consulta el listado de dispositivos GPS, Cuando visualiza la lista, Entonces cada dispositivo muestra: intervalo configurado, fuente de la configuracion (tenant/dispositivo/viaje), y estado de sincronizacion con el proveedor (si aplica).

Escenario 6: Sincronizar configuracion con proveedor

Dado que el dispositivo usa Traccar y el proveedor soporta configuracion remota de intervalo, Cuando el usuario cambia el intervalo a 30 segundos, Entonces el sistema envia el comando de configuracion a Traccar, espera confirmacion, y muestra estado "Configuracion sincronizada" o "Pendiente de sincronizar" si el dispositivo esta offline.

Tareas Tecnicas

• Database: Agregar campos en tracking.gps_devices: intervalo_configurado_segundos INTEGER DEFAULT NULL, intervalo_sincronizado BOOLEAN DEFAULT FALSE, intervalo_sincronizado_at TIMESTAMPTZ. Agregar en tenant_settings: tracking.default_interval_seconds (default 30).
• Backend: Crear IntervalConfigurationService con metodos: setTenantDefault(), setDeviceInterval(), setTripInterval(), getEffectiveInterval(), syncWithProvider(). Agregar endpoint PATCH /api/tracking/gps-devices/:id/interval.
• Provider Integration: Implementar metodo setDeviceInterval(deviceId, seconds) en los adapters que lo soporten (Traccar, Samsara, Geotab). Para proveedores que no lo soporten (Wialon, Manual), solo actualizar configuracion local.
• Trip Integration: Modificar servicio de viajes para aplicar intervalo temporal cuando viaje tiene configuracion de tracking intensivo.
• Frontend: Agregar campo "Intervalo (segundos)" en formulario de dispositivo GPS. Agregar seccion en configuracion de tenant para intervalo por defecto. Mostrar badge de "intervalo temporal" cuando un viaje tiene tracking intensivo activo.
• Tests: Tests de jerarquia de configuracion (viaje > dispositivo > tenant). Tests de sincronizacion con proveedores. Tests de limites minimo/maximo.

Dependencias

• Depende de: US-MAI006-011 (configurar dispositivo), MAI-001 (tenant settings)
• Bloquea: Ninguna

Notas Tecnicas

• Limites de intervalo:

Limite	Valor	Motivo
Minimo	10 segundos	Evitar saturacion de BD y APIs
Maximo	300 segundos	Garantizar visibilidad minima
Default	30 segundos	Balance costo/precision

• Jerarquia de configuracion (mayor a menor prioridad):

  1. Intervalo de viaje activo (temporal)
  2. Intervalo especifico del dispositivo
  3. Intervalo por defecto del tenant
  4. Intervalo por defecto del sistema (30 segundos)

• Formula de umbral "sin senal":

  umbral_sin_senal = intervalo_efectivo * 5
  

• Soporte de proveedores:

Proveedor	Config remota	Metodo
Traccar	Si	Device settings API
Samsara	Si	Vehicle settings API
Geotab	Si	Device parameters API
Wialon	Parcial	Depende del dispositivo
Manual	No	N/A

• Configuracion de tracking intensivo en viaje:

  {
    "trackingIntensivo": true,
    "intervaloSegundos": 10,
    "aplicarEnEstados": ["EN_TRANSITO", "EN_DESTINO"]
  }
  

---

US-MAI006-015 - ERP Transportistas v1.0.0