# 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