205 lines
8.8 KiB
Markdown
205 lines
8.8 KiB
Markdown
# 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
|