rckrdmrd/erp-transportistas-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
6ed7f9e2ec
erp-transportistas-v2/docs/02-definicion-modulos/MAI-006-tracking/historias-usuario/US-MAI006-011-configurar-dispositivo-gps.md
Adrian Flores Cortes 6ed7f9e2ec [BACKUP] Pre-restructure workspace backup 2026-01-29 
- Updated docs and inventory files
- Added new architecture docs

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-29 17:35:54 -06:00

5.4 KiB
Raw Blame History

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