# 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:**
  ```json
  {
    "trackingIntensivo": true,
    "intervaloSegundos": 10,
    "aplicarEnEstados": ["EN_TRANSITO", "EN_DESTINO"]
  }
  ```

---

*US-MAI006-015 - ERP Transportistas v1.0.0*