# US-MAI006-014: Cambiar proveedor GPS

## Metadata

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

## Historia de Usuario

**Como** gerente de operaciones de una empresa transportista,
**quiero** poder migrar de un proveedor GPS a otro sin perder historico de posiciones,
**para** cambiar de servicio de telematica cuando encuentre una mejor opcion o mejores condiciones comerciales.

## Descripcion Detallada

Las empresas de transporte pueden necesitar cambiar de proveedor de telematica por diversas razones: mejores tarifas, mejor cobertura, funcionalidades adicionales, o consolidacion de proveedores. La migracion debe ser transparente para la operacion: el historico de posiciones debe permanecer intacto, las geocercas y alertas deben seguir funcionando, y el cambio debe poder hacerse gradualmente (unidad por unidad o toda la flota).

El sistema soporta multiples proveedores simultaneamente, lo que permite una migracion gradual: se pueden activar dispositivos del nuevo proveedor en algunas unidades mientras otras siguen con el proveedor anterior. El campo `proveedor_gps` en cada posicion almacena el origen del dato, permitiendo trazar el historial aunque haya cambios de proveedor.

El proceso de migracion incluye: configuracion del nuevo proveedor a nivel tenant, actualizacion del mapping de dispositivos (IMEI -> device_id_externo del nuevo proveedor), periodo de prueba en paralelo, y finalmente desactivacion del proveedor anterior.

## Criterios de Aceptacion

### Escenario 1: Configurar nuevo proveedor GPS

**Dado** que el tenant actualmente usa Traccar como proveedor GPS,
**Cuando** el administrador configura Samsara como proveedor adicional (ingresando API key y configuracion),
**Entonces** el sistema valida las credenciales contra el API de Samsara, almacena la configuracion de forma segura (credenciales encriptadas), y muestra mensaje de "Proveedor configurado exitosamente".

### Escenario 2: Actualizar dispositivo a nuevo proveedor

**Dado** que el dispositivo de la Unidad T-001 usaba Traccar (device_id_externo: "123") y ahora tiene un dispositivo Samsara (device_id: "sam-456"),
**Cuando** el administrador actualiza el dispositivo con: proveedor = "samsara", device_id_externo = "sam-456",
**Entonces** el sistema actualiza el registro del dispositivo, las nuevas posiciones llegan desde Samsara con `proveedor_gps = 'samsara'`, y el historial anterior permanece con `proveedor_gps = 'traccar'`.

### Escenario 3: Periodo de ejecucion en paralelo

**Dado** que algunas unidades usan Traccar y otras Samsara,
**Cuando** se consulta el dashboard de flota,
**Entonces** todas las unidades se muestran en el mapa independientemente del proveedor, con indicador visual del proveedor actual de cada unidad.

### Escenario 4: Consultar historial con multiples proveedores

**Dado** que la Unidad T-001 tiene posiciones de Traccar (enero-junio) y Samsara (julio-diciembre),
**Cuando** el usuario consulta el historial de todo el ano,
**Entonces** el sistema muestra todas las posiciones ordenadas cronologicamente, pudiendo filtrar por proveedor si se desea.

### Escenario 5: Desactivar proveedor anterior

**Dado** que todas las unidades del tenant ya fueron migradas a Samsara,
**Cuando** el administrador desactiva la configuracion de Traccar,
**Entonces** el sistema deja de procesar webhooks de Traccar para ese tenant, el historial de posiciones de Traccar permanece intacto, y se libera la configuracion (credenciales borradas de forma segura).

### Escenario 6: Verificar conectividad de nuevo proveedor

**Dado** que el administrador configuro un nuevo proveedor,
**Cuando** solicita verificar la conectividad,
**Entonces** el sistema intenta listar dispositivos desde el API del proveedor y muestra: numero de dispositivos encontrados, estado de conexion, y cualquier error de autenticacion o configuracion.

## Tareas Tecnicas

- **Database:** Crear tabla `tracking.tenant_gps_providers` con campos: tenant_id, proveedor, config (JSONB encriptado), activo, verificado_at, created_at, updated_at. Permitir multiples proveedores activos por tenant.
- **Backend:** Crear `TenantGpsProviderService` con metodos: addProvider(), updateProvider(), removeProvider(), verifyConnection(), listProviders(). Crear endpoint `/api/tracking/providers` con CRUD.
- **Security:** Implementar encriptacion de credenciales sensibles (API keys, passwords) usando el servicio de vault o encriptacion AES con clave de ambiente.
- **Migration Tool:** Crear herramienta/script para actualizar masivamente los dispositivos al cambiar de proveedor: mapeo de device_id_externo antiguo a nuevo.
- **Frontend:** Crear seccion "Proveedores GPS" en configuracion del tenant. Mostrar lista de proveedores con estado (activo, verificado), permitir agregar/editar/eliminar. Agregar indicador de proveedor en el listado de dispositivos.
- **Tests:** Tests de configuracion de multiples proveedores. Tests de migracion de dispositivos. Tests de consulta de historial multi-proveedor.

## Dependencias

- **Depende de:** US-MAI006-011 (configurar dispositivo), MAI-001 (tenant settings), Integracion GPS Multi-Provider
- **Bloquea:** Ninguna

## Notas Tecnicas

- **Endpoints:**
  - `GET /api/tracking/providers` - Listar proveedores del tenant
  - `POST /api/tracking/providers` - Agregar proveedor
  - `PUT /api/tracking/providers/:provider` - Actualizar configuracion
  - `DELETE /api/tracking/providers/:provider` - Desactivar proveedor
  - `POST /api/tracking/providers/:provider/verify` - Verificar conectividad

- **Estructura de configuracion por proveedor:**

```typescript
// Traccar
{
  provider: 'traccar',
  config: {
    apiUrl: 'https://traccar.example.com/api',
    wsUrl: 'wss://traccar.example.com/api/socket',
    email: 'admin@example.com',
    password: 'encrypted...'
  }
}

// Samsara
{
  provider: 'samsara',
  config: {
    apiKey: 'encrypted...',
    webhookSecret: 'encrypted...'
  }
}
```

- **Webhook routing:** Al recibir webhook, identificar tenant por API key o firma, no por URL
- **Auditoria:** Registrar todos los cambios de proveedor en audit log
- **Rollback:** Mantener configuracion anterior por 30 dias despues de desactivar para posible rollback

---

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