# US-MAI006-011: Configurar dispositivo GPS

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | US-MAI006-011 |
| **Epica** | EPIC-MAI-006 - Tracking en Tiempo Real |
| **Modulo** | tracking |
| **Prioridad** | P1 |
| **Story Points** | 5 |
| **Sprint** | Por asignar |
| **Estado** | Backlog |

## Historia de Usuario

**Como** jefe de flota de una empresa transportista,
**quiero** vincular un dispositivo GPS a una unidad de transporte,
**para** poder rastrear la ubicacion de la unidad en tiempo real y registrar su historial de posiciones.

## Descripcion Detallada

La configuracion de dispositivos GPS es fundamental para habilitar el tracking de unidades. El jefe de flota debe poder registrar la informacion del dispositivo (IMEI, proveedor, modelo) y asociarlo a una unidad especifica de la flota. Un dispositivo solo puede estar asociado a una unidad a la vez, pero puede reasignarse cuando se requiera (por ejemplo, al dar de baja una unidad o al reemplazar un dispositivo danado).

El sistema debe soportar multiples proveedores GPS (Traccar, Wialon, Samsara, Geotab) y permitir configurar el identificador del dispositivo en el sistema del proveedor para que las posiciones entrantes se asocien correctamente a la unidad.

Al vincular un dispositivo, el sistema debe intentar obtener la ultima posicion conocida del proveedor para verificar la conectividad. El usuario puede configurar el intervalo de reporte esperado (por ejemplo, cada 30 segundos) que se utilizara para detectar cuando un dispositivo deja de reportar.

## Criterios de Aceptacion

### Escenario 1: Vincular nuevo dispositivo GPS a unidad

**Dado** que el jefe de flota tiene permisos de gestion de flota y existe una unidad sin dispositivo GPS asignado,
**Cuando** selecciona la unidad, ingresa el IMEI del dispositivo, selecciona el proveedor GPS, ingresa el ID externo (en el sistema del proveedor), selecciona el intervalo de reporte y confirma la vinculacion,
**Entonces** el sistema crea el registro en `tracking.gps_devices` con los datos ingresados, marca el dispositivo como activo, y muestra mensaje de exito con la informacion del dispositivo vinculado.

### Escenario 2: Validacion de IMEI unico por tenant

**Dado** que ya existe un dispositivo con IMEI "352093088937641" registrado para el tenant,
**Cuando** el usuario intenta registrar otro dispositivo con el mismo IMEI,
**Entonces** el sistema muestra error indicando que el IMEI ya esta registrado y no permite la creacion.

### Escenario 3: Verificar conectividad al vincular

**Dado** que el usuario esta vinculando un dispositivo con proveedor "traccar",
**Cuando** confirma la vinculacion,
**Entonces** el sistema intenta obtener la ultima posicion del dispositivo desde el proveedor y muestra: (a) "Dispositivo conectado - Ultima posicion: [fecha/hora]" si obtiene respuesta exitosa, o (b) "Dispositivo sin conexion reciente - Verificar configuracion" si no obtiene posicion.

### Escenario 4: Reasignar dispositivo a otra unidad

**Dado** que existe un dispositivo GPS actualmente asignado a la Unidad A,
**Cuando** el usuario selecciona el dispositivo y lo reasigna a la Unidad B,
**Entonces** el sistema actualiza el `unidad_id` del dispositivo, registra el cambio en el historial (audit log), y las nuevas posiciones se asocian a la Unidad B.

### Escenario 5: Desactivar dispositivo GPS

**Dado** que existe un dispositivo GPS activo asignado a una unidad,
**Cuando** el usuario desactiva el dispositivo,
**Entonces** el sistema marca `activo = FALSE`, deja de procesar posiciones de ese IMEI, y la unidad queda disponible para asignar otro dispositivo.

## Tareas Tecnicas

- **Database:** Verificar que existe la tabla `tracking.gps_devices` con campos: id, tenant_id, unidad_id, imei, proveedor, device_id_externo, nombre, modelo, sim_numero, sim_operador, intervalo_segundos, activo, ultima_posicion_at. Crear indices idx_gps_device_tenant, idx_gps_device_imei (unique), idx_gps_device_unidad.
- **Backend:** Crear entity `GpsDevice` mapeada a `tracking.gps_devices`. Crear `GpsDeviceService` con metodos: create(), findByImei(), findByUnidad(), update(), deactivate(), verifyConnectivity(). Crear `GpsDeviceController` con endpoints CRUD. Crear DTOs: CreateGpsDeviceDto, UpdateGpsDeviceDto.
- **Frontend:** Crear componente `GpsDeviceForm` con campos: unidadId (selector), imei, proveedor (dropdown: traccar, wialon, samsara, geotab, manual), deviceIdExterno, nombre, modelo, simNumero, simOperador, intervaloSegundos (default 30). Agregar seccion de dispositivo GPS en la ficha de unidad.
- **Integration:** Implementar metodo `verifyConnectivity()` que llame al adapter del proveedor para obtener ultima posicion.
- **Tests:** Tests unitarios del servicio. Tests de integracion de endpoints. Tests de validacion de IMEI unico.

## Dependencias

- **Depende de:** MAI-011 (Gestion de Flota - unidades), MAI-001 (Auth - permisos)
- **Bloquea:** US-MAI006-012 (recibir posiciones), US-MAI006-014 (cambiar proveedor)

## Notas Tecnicas

- **Endpoint:** POST `/api/tracking/gps-devices`
- **Entity:** `GpsDevice` -> `tracking.gps_devices`
- **RLS:** Politica `tenant_isolation_gps_devices` filtra por `tenant_id = current_setting('app.tenant_id')::uuid`
- **Proveedores soportados:** traccar, wialon, samsara, geotab, manual
- **IMEI:** Unique constraint por tenant (un mismo IMEI puede existir en diferentes tenants)
- **Intervalo default:** 30 segundos
- **Soft delete:** Se desactiva con `activo = FALSE`, no se elimina fisicamente

---

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