sf-app-platform/docs/location-ui-endpoints-map.md

Location — Mapa de UI, Botones y Endpoints

Qué ve el usuario al entrar al tab de Localización

Carga inicial (automática al entrar)

Al navegar al tab, se ejecutan 3 llamadas HTTP en paralelo:

Endpoint	Método	Descripción
GET /devices/{deviceUUID}/geofences	GET	Carga las zonas de seguridad del dispositivo
GET /devices/{deviceUUID}/frequent-places	GET	Carga los lugares frecuentes del dispositivo
GET /devices/identificator/{did}/positions?page=1&pageSize=5&orderBy=positionDate DESC	GET	Carga las últimas 5 posiciones para mostrar el marcador actual

Además se inicia un timer de polling que cada N segundos (frecuencia del dispositivo, mínimo 60s) vuelve a llamar al endpoint de posiciones.

---

Controles sobre el mapa

Esquina superior izquierda

1. Selector de estilo de mapa (icono de capas)

• Acción: Cambia el tile layer del mapa (Standard, Voyager, Light, Dark, Satellite)
• Endpoint: Ninguno — solo cambia el URL del tile server localmente

2. Selector de frecuencia GPS (icono de timer)

• Acción: Al expandir, muestra las opciones de frecuencia (ej: 5min, 10min, 30min, 1h). Al seleccionar una:
• Endpoint: Se ejecuta a través del deviceSettingsUpdateProvider que llama:
  • PUT /devices/{deviceUUID} — actualiza settings.frequency del dispositivo
  • Internamente envía un comando al dispositivo para cambiar su frecuencia de reporte

---

Esquina superior derecha

3. Botón de refrescar (icono ↻)

• Acción: Fuerza una actualización de la posición del dispositivo
• Endpoint:
  • GET /devices/identificator/{did}/positions?page=1&pageSize=5&orderBy=positionDate DESC

4. Botón de ajustes GPS (icono ⚙️)

Abre un diálogo modal con las siguientes opciones:

4.1 "Lista" (Ver listas)

• Acción: Abre un bottom sheet con 3 tabs: Geofences, Lugares frecuentes, Historial
• Endpoint: Ninguno — usa los datos ya cargados en memoria

4.2 "Añadir zona de seguridad"

• Acción: Entra en modo de colocación. El usuario mueve el mapa y confirma. Luego ajusta el radio con un slider. Finalmente introduce nombre y descripción.
• Endpoint al confirmar:
  • POST /geofences — body: { deviceId, name, description, latitude, longitude, radius, isActive: true }
• Endpoint al editar (desde info card):
  • PUT /geofences/{geofenceId} — body: { name, description, latitude, longitude, radius }
• Endpoint al eliminar (desde info card o lista):
  • DELETE /geofences/{geofenceId}

4.3 "Añadir lugar frecuente"

• Acción: Entra en modo de colocación. El usuario mueve el mapa y confirma. Introduce nombre.
• Endpoint al confirmar:
  • POST /frequent-places — body: { deviceId, name, lat, lng }
• Endpoint al editar:
  • PUT /frequent-places/{frequentPlaceId} — body: { name, lat, lng, wifiList }
• Endpoint al eliminar:
  • DELETE /frequent-places/{frequentPlaceId}

4.4 "Compartir ubicación"

• Acción: Abre el share sheet nativo con la ubicación actual (nombre del dispositivo + dirección + link de Google Maps)
• Endpoint: Ninguno — usa la posición ya cargada

4.5 "Centrar en dispositivo"

• Acción: Anima el mapa hacia la última posición conocida del dispositivo
• Endpoint: Ninguno — usa la posición ya cargada

4.6 "Seguir dispositivo" (toggle)

• Acción: Activa/desactiva el modo "seguir" — cuando llega una nueva posición, el mapa se centra automáticamente
• Endpoint: Ninguno — solo cambia el comportamiento del timer de polling

4.7 "Mostrar/ocultar zonas de seguridad" (toggle)

• Acción: Muestra u oculta los círculos y marcadores de geofences en el mapa
• Endpoint: Ninguno — solo cambia visibilidad en UI

4.8 "Mostrar/ocultar lugares frecuentes" (toggle)

• Acción: Muestra u oculta los marcadores de lugares frecuentes
• Endpoint: Ninguno — solo cambia visibilidad en UI

4.9 "Historial de posiciones"

• Acción: Abre un date range picker. Al seleccionar rango de fechas:
• Endpoint:
  • GET /devices/identificator/{did}/positions?page=1&pageSize=1000&filters=[positionDate gte/lte]&orderBy=positionDate ASC
  • Pagina automáticamente hasta obtener todas las posiciones del rango (loop hasta totalPages)

4.10 "Mostrar/ocultar ruta del historial" (toggle)

• Acción: Muestra u oculta la línea de ruta del historial cargado
• Endpoint: Ninguno — solo cambia visibilidad en UI

---

Panel de acciones expandible (esquina derecha, debajo del GPS)

Cuando el usuario pulsa el botón "⋮" (tres puntos) se expande un panel vertical con:

5. Botón lista (icono 📋)

• Mismo que 4.1 — abre bottom sheet con listas

6. Botón añadir geofence (icono 📍+)

• Mismo que 4.2 — entra en modo colocación de geofence

7. Botón añadir lugar frecuente (icono 🏠+)

• Mismo que 4.3 — entra en modo colocación de lugar frecuente

8. Botón compartir (icono ↗)

• Mismo que 4.4 — share sheet con ubicación

9. Botón refrescar (icono ↻)

• Mismo que 3 — fuerza refresh de posiciones

10. Botón centrar (icono ⊕)

• Mismo que 4.5 — centra en dispositivo

11. Botón seguir (icono GPS)

• Mismo que 4.6 — toggle de seguimiento

---

Parte inferior del mapa

12. Banner de dispositivo (swipeable)

• Acción: Muestra el dispositivo seleccionado con nombre, batería, última posición. Se puede swipear para cambiar de dispositivo.
• Al cambiar de dispositivo:
  • GET /devices/identificator/{newDid}/positions?page=1&pageSize=5&orderBy=positionDate DESC — carga posiciones del nuevo dispositivo
  • GET /devices/{newDeviceUUID}/geofences — carga geofences del nuevo dispositivo
  • GET /devices/{newDeviceUUID}/frequent-places — carga lugares frecuentes del nuevo dispositivo
  • Se reinicia el timer de polling con la frecuencia del nuevo dispositivo

13. Botón centrar en dispositivo (icono ⊕, sobre el banner)

• Solo aparece si no hay historial activo
• Mismo que 4.5

---

Controles especiales (aparecen según el modo)

Modo colocación (geofence o lugar frecuente)

• Banner superior: "Mueve el mapa para elegir la ubicación" + botón Cancelar + botón Confirmar
• Centro de la pantalla: Cruz/icono de marcador

Modo ajuste de radio (solo geofence)

• Slider inferior: Ajusta el radio del círculo (se ve el preview en el mapa)
• Botones: Cancelar / Confirmar

Modo historial — Animación reveal

• Barra de progreso inferior: Muestra el progreso de la animación de revelado de posiciones
• Botón Skip: Salta al final de la animación

Modo historial — Player de navegación

• Controles inferior: ◀ Anterior | ▶/⏸ Play/Pause | Siguiente ▶
• Botón cerrar: Sale del modo historial
• Play/Pause: Auto-avanza cada 3 segundos por las posiciones del historial

---

Info cards (aparecen al tocar un marcador)

Al tocar un marcador de geofence

• Muestra: nombre, descripción, radio, coordenadas, estado (activa/inactiva)
• Botón Editar: Entra en modo edición (reposicionar + ajustar radio + renombrar)
  • PUT /geofences/{id}
• Botón Eliminar: Confirmación → elimina
  • DELETE /geofences/{id}

Al tocar un marcador de lugar frecuente

• Muestra: nombre, coordenadas, redes WiFi
• Botón Editar: Entra en modo edición (reposicionar + renombrar)
  • PUT /frequent-places/{id}
• Botón Eliminar: Confirmación → elimina
  • DELETE /frequent-places/{id}

Al tocar un punto del historial

• Muestra: fecha/hora, tipo de posición, dirección, coordenadas

---

Resumen de endpoints

Endpoint	Método	Cuándo se llama
GET /devices/{uuid}/geofences	GET	Carga inicial + cambio de dispositivo
POST /geofences	POST	Crear zona de seguridad
PUT /geofences/{id}	PUT	Editar zona de seguridad
DELETE /geofences/{id}	DELETE	Eliminar zona de seguridad
GET /devices/{uuid}/frequent-places	GET	Carga inicial + cambio de dispositivo
POST /frequent-places	POST	Crear lugar frecuente
PUT /frequent-places/{id}	PUT	Editar lugar frecuente
DELETE /frequent-places/{id}	DELETE	Eliminar lugar frecuente
GET /devices/identificator/{did}/positions	GET	Posición actual (pageSize=5, DESC) + historial (pageSize=1000, ASC, con filtros de fecha) + polling periódico
PUT /devices/{uuid}	PUT	Cambiar frecuencia GPS (via deviceSettingsUpdateProvider)

Polling automático

• Frecuencia: La que tenga configurada el dispositivo (mínimo 60 segundos)
• Endpoint: GET /devices/identificator/{did}/positions?page=1&pageSize=5&orderBy=positionDate DESC
• Condición: No se ejecuta si el dispositivo está desconectado
• Se reinicia: Al cambiar de dispositivo o al cambiar la frecuencia manualmente