erp-transportistas-v2/docs/02-definicion-modulos/MAI-006-tracking/historias-usuario/US-MAI006-014-cambiar-proveedor-gps.md

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:

// 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