429 lines
16 KiB
Markdown
429 lines
16 KiB
Markdown
# Piano di Implementazione: Geolocalizzazione e Calcolo Bounds
|
|
|
|
## Panoramica
|
|
|
|
Questo documento descrive il piano per implementare le seguenti funzionalità nell'Ingress Dashboard:
|
|
|
|
1. **Geolocalizzazione dell'utente** al primo caricamento dell'applicazione
|
|
2. **Calcolo del center** della viewport della mappa
|
|
3. **Calcolo del radius** in metri in base allo zoom della mappa per coprire l'intera viewport
|
|
4. **Integrazione dei parametri center e radius** nell'API
|
|
|
|
## Architettura Proposta
|
|
|
|
### Componenti Coinvolti
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ App.tsx │
|
|
│ ┌────────────────────────────────────────────────────────┐ │
|
|
│ │ Stato: center, radius, plexts, loading, filters │ │
|
|
│ │ │ │
|
|
│ │ loadData() → fetchPlexts(center, radius, filters) │ │
|
|
│ └────────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
│ props: onCenterChange, onRadiusChange
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ PlayerMap.tsx │
|
|
│ ┌────────────────────────────────────────────────────────┐ │
|
|
│ │ useMapGeolocation() │ │
|
|
│ │ - map.locate() al mount │ │
|
|
│ │ - onLocationFound → setView(lat, lng, zoom) │ │
|
|
│ │ │ │
|
|
│ │ useMapBounds() │ │
|
|
│ │ - onMoveEnd → calcola center e radius │ │
|
|
│ │ - onZoomEnd → calcola center e radius │ │
|
|
│ │ - invoca callbacks onCenterChange, onRadiusChange │ │
|
|
│ └────────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
│ params: center, radius, filters
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ api.ts │
|
|
│ ┌────────────────────────────────────────────────────────┐ │
|
|
│ │ fetchPlexts(base_url, endpoint, creds, { │ │
|
|
│ │ center: [lat, lng], │ │
|
|
│ │ radius: meters, │ │
|
|
│ │ timestamp_from, timestamp_to, │ │
|
|
│ │ player_name, limit │ │
|
|
│ │ }) │ │
|
|
│ └────────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Dettagli di Implementazione
|
|
|
|
### 1. Aggiornamento dei Tipi (`src/types.ts`)
|
|
|
|
Aggiungere le interfacce per i nuovi parametri:
|
|
|
|
```typescript
|
|
export interface MapCenter {
|
|
lat: number;
|
|
lng: number;
|
|
}
|
|
|
|
export interface MapBoundsParams {
|
|
center: [number, number]; // [lat, lng]
|
|
radius: number; // metri
|
|
}
|
|
```
|
|
|
|
### 2. Aggiornamento dell'API (`src/api.ts`)
|
|
|
|
Modificare la funzione `fetchPlexts` per accettare i nuovi parametri:
|
|
|
|
```typescript
|
|
export async function fetchPlexts(
|
|
base_url: string,
|
|
endpoint: string,
|
|
creds: string,
|
|
params?: {
|
|
center?: [number, number]; // [lat, lng]
|
|
radius?: number; // metri
|
|
timestamp_from?: number;
|
|
timestamp_to?: number;
|
|
player_name?: string;
|
|
limit?: number;
|
|
}
|
|
): Promise<ApiResponse>
|
|
```
|
|
|
|
I parametri `center` e `radius` verranno aggiunti alla query string.
|
|
|
|
### 3. Hook Personalizzato: `useMapGeolocation`
|
|
|
|
Creare un nuovo file `src/hooks/useMapGeolocation.ts`:
|
|
|
|
```typescript
|
|
import { useEffect } from 'react';
|
|
import { useMap } from 'react-leaflet';
|
|
|
|
interface UseMapGeolocationOptions {
|
|
enableHighAccuracy?: boolean;
|
|
timeout?: number;
|
|
maximumAge?: number;
|
|
zoom?: number;
|
|
}
|
|
|
|
export function useMapGeolocation(options: UseMapGeolocationOptions = {}) {
|
|
const map = useMap();
|
|
|
|
useEffect(() => {
|
|
map.locate({
|
|
setView: true,
|
|
maxZoom: options.zoom || 13,
|
|
enableHighAccuracy: options.enableHighAccuracy ?? true,
|
|
timeout: options.timeout || 10000,
|
|
maximumAge: options.maximumAge || 0,
|
|
});
|
|
|
|
const onLocationFound = (e: any) => {
|
|
console.log('Location found:', e.latlng);
|
|
};
|
|
|
|
const onLocationError = (e: any) => {
|
|
console.error('Location error:', e.message);
|
|
// Fallback to default location
|
|
map.setView([45.57, 12.36], 12);
|
|
};
|
|
|
|
map.on('locationfound', onLocationFound);
|
|
map.on('locationerror', onLocationError);
|
|
|
|
return () => {
|
|
map.off('locationfound', onLocationFound);
|
|
map.off('locationerror', onLocationError);
|
|
};
|
|
}, [map, options]);
|
|
}
|
|
```
|
|
|
|
### 4. Hook Personalizzato: `useMapBounds`
|
|
|
|
Creare un nuovo file `src/hooks/useMapBounds.ts`:
|
|
|
|
```typescript
|
|
import { useEffect } from 'react';
|
|
import { useMap } from 'react-leaflet';
|
|
import L from 'leaflet';
|
|
|
|
interface UseMapBoundsOptions {
|
|
onCenterChange?: (center: [number, number]) => void;
|
|
onRadiusChange?: (radius: number) => void;
|
|
debounceMs?: number;
|
|
}
|
|
|
|
/**
|
|
* Calcola il raggio in metri dai bounds della mappa
|
|
* Il raggio è la distanza dal centro al bordo della viewport
|
|
*/
|
|
function calculateRadiusFromBounds(map: L.Map): number {
|
|
const bounds = map.getBounds();
|
|
const center = bounds.getCenter();
|
|
const northEast = bounds.getNorthEast();
|
|
|
|
// Calcola la distanza dal centro al bordo nord-est
|
|
const radius = center.distanceTo(northEast);
|
|
|
|
return Math.round(radius);
|
|
}
|
|
|
|
export function useMapBounds(options: UseMapBoundsOptions = {}) {
|
|
const map = useMap();
|
|
const { onCenterChange, onRadiusChange, debounceMs = 500 } = options;
|
|
|
|
useEffect(() => {
|
|
let timeoutId: NodeJS.Timeout | null = null;
|
|
|
|
const updateBounds = () => {
|
|
const center = map.getCenter();
|
|
const radius = calculateRadiusFromBounds(map);
|
|
|
|
if (onCenterChange) {
|
|
onCenterChange([center.lat, center.lng]);
|
|
}
|
|
if (onRadiusChange) {
|
|
onRadiusChange(radius);
|
|
}
|
|
};
|
|
|
|
const onMoveEnd = () => {
|
|
if (timeoutId) {
|
|
clearTimeout(timeoutId);
|
|
}
|
|
timeoutId = setTimeout(updateBounds, debounceMs);
|
|
};
|
|
|
|
const onZoomEnd = () => {
|
|
if (timeoutId) {
|
|
clearTimeout(timeoutId);
|
|
}
|
|
timeoutId = setTimeout(updateBounds, debounceMs);
|
|
};
|
|
|
|
// Calcola bounds iniziali
|
|
updateBounds();
|
|
|
|
map.on('moveend', onMoveEnd);
|
|
map.on('zoomend', onZoomEnd);
|
|
|
|
return () => {
|
|
if (timeoutId) {
|
|
clearTimeout(timeoutId);
|
|
}
|
|
map.off('moveend', onMoveEnd);
|
|
map.off('zoomend', onZoomEnd);
|
|
};
|
|
}, [map, onCenterChange, onRadiusChange, debounceMs]);
|
|
}
|
|
```
|
|
|
|
### 5. Aggiornamento di `PlayerMap.tsx`
|
|
|
|
Aggiungere le nuove funzionalità:
|
|
|
|
```typescript
|
|
import { MapContainer, TileLayer, Marker, Popup } from "react-leaflet";
|
|
import MarkerClusterGroup from "react-leaflet-cluster";
|
|
import L from "leaflet";
|
|
import { useMapGeolocation } from "../hooks/useMapGeolocation";
|
|
import { useMapBounds } from "../hooks/useMapBounds";
|
|
|
|
interface PlayerMapProps {
|
|
plexts: Plext[];
|
|
onCenterChange?: (center: [number, number]) => void;
|
|
onRadiusChange?: (radius: number) => void;
|
|
}
|
|
|
|
// Componente interno per gli hooks
|
|
function MapContent({ onCenterChange, onRadiusChange }: {
|
|
onCenterChange?: (center: [number, number]) => void;
|
|
onRadiusChange?: (radius: number) => void;
|
|
}) {
|
|
useMapGeolocation({ zoom: 13 });
|
|
useMapBounds({ onCenterChange, onRadiusChange, debounceMs: 500 });
|
|
return null;
|
|
}
|
|
|
|
export function PlayerMap({ plexts, onCenterChange, onRadiusChange }: PlayerMapProps) {
|
|
// ... codice esistente per i marker ...
|
|
|
|
return (
|
|
<div className="map-container" style={{ height: "600px", width: "100%" }}>
|
|
<MapContainer
|
|
center={[45.57, 12.36]} // Default fallback
|
|
zoom={12}
|
|
style={{ height: "100%", width: "100%" }}
|
|
scrollWheelZoom={true}
|
|
>
|
|
<MapContent onCenterChange={onCenterChange} onRadiusChange={onRadiusChange} />
|
|
<TileLayer ... />
|
|
<MarkerClusterGroup ...>
|
|
{/* markers */}
|
|
</MarkerClusterGroup>
|
|
</MapContainer>
|
|
</div>
|
|
);
|
|
}
|
|
```
|
|
|
|
### 6. Aggiornamento di `App.tsx`
|
|
|
|
Aggiungere lo stato per center e radius e passarlo all'API:
|
|
|
|
```typescript
|
|
export function App() {
|
|
const [data, setData] = useState<ApiResponse>({ count: 0, plexts: [] });
|
|
const [loading, setLoading] = useState(true);
|
|
const [timestampFrom, setTimestampFrom] = useState<Date | null>(null);
|
|
const [timestampTo, setTimestampTo] = useState<Date | null>(null);
|
|
const [playerName, setPlayerName] = useState<string>("all");
|
|
const [limit, setLimit] = useState<number>(100);
|
|
const [mapCenter, setMapCenter] = useState<[number, number]>([45.57, 12.36]);
|
|
const [mapRadius, setMapRadius] = useState<number>(10000); // Default 10km
|
|
|
|
const loadData = async () => {
|
|
try {
|
|
const params = {
|
|
center: mapCenter,
|
|
radius: mapRadius,
|
|
timestamp_from: timestampFrom ? timestampFrom.getTime() : undefined,
|
|
timestamp_to: timestampTo ? timestampTo.getTime() : undefined,
|
|
player_name: playerName !== "all" ? playerName : undefined,
|
|
limit,
|
|
};
|
|
const result = await fetchPlexts(
|
|
process.env.PUBLIC_API_BASE_URL || "",
|
|
process.env.PUBLIC_API_ENDPOINT || "",
|
|
process.env.PUBLIC_API_AUTH_CREDENTIALS || "",
|
|
params
|
|
);
|
|
setData(result);
|
|
} catch (error) {
|
|
console.error("Error loading data:", error);
|
|
} finally {
|
|
setLoading(false);
|
|
}
|
|
};
|
|
|
|
useEffect(() => {
|
|
loadData();
|
|
const interval = setInterval(loadData, 60000);
|
|
return () => clearInterval(interval);
|
|
}, [timestampFrom, timestampTo, playerName, limit, mapCenter, mapRadius]);
|
|
|
|
// ... resto del codice ...
|
|
|
|
return (
|
|
// ...
|
|
<PlayerMap
|
|
plexts={data.plexts}
|
|
onCenterChange={setMapCenter}
|
|
onRadiusChange={setMapRadius}
|
|
/>
|
|
// ...
|
|
);
|
|
}
|
|
```
|
|
|
|
## Diagramma di Flusso
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
A[App Mount] --> B[PlayerMap Render]
|
|
B --> C[MapContainer Initialize]
|
|
C --> D[useMapGeolocation Hook]
|
|
D --> E{Geolocation Available?}
|
|
E -->|Yes| F[map.locate]
|
|
E -->|No| G[Use Default Center]
|
|
F --> H[locationfound Event]
|
|
H --> I[map.setView to User Location]
|
|
I --> J[useMapBounds Hook]
|
|
J --> K[Calculate Initial Center & Radius]
|
|
K --> L[onCenterChange Callback]
|
|
L --> M[App State Updated]
|
|
M --> N[loadData with center & radius]
|
|
N --> O[fetchPlexts API Call]
|
|
O --> P[Update Data State]
|
|
P --> Q[Re-render Map with New Data]
|
|
|
|
J --> R[User Moves/Zooms Map]
|
|
R --> S[moveend/zoomend Events]
|
|
S --> T[Debounced Update]
|
|
T --> U[Recalculate Center & Radius]
|
|
U --> L
|
|
```
|
|
|
|
## Considerazioni Tecniche
|
|
|
|
### Geolocalizzazione
|
|
|
|
1. **Permessi**: L'utente deve concedere il permesso di geolocalizzazione. Se rifiuta, usare la posizione di default.
|
|
2. **Timeout**: Impostare un timeout ragionevole (es. 10 secondi) per evitare attese infinite.
|
|
3. **Fallback**: Se la geolocalizzazione fallisce, mantenere la posizione di default (Veneto region: [45.57, 12.36]).
|
|
4. **Privacy**: Non memorizzare la posizione dell'utente in modo persistente.
|
|
|
|
### Calcolo del Radius
|
|
|
|
1. **Formula**: Il raggio viene calcolato come la distanza dal centro al bordo nord-est della viewport usando `center.distanceTo(northEast)`.
|
|
2. **Unità**: Il raggio è espresso in metri.
|
|
3. **Debouncing**: Aggiungere un debouncing di 500ms per evitare chiamate API eccessive durante lo spostamento della mappa.
|
|
|
|
### Performance
|
|
|
|
1. **Debouncing**: Usare debouncing per gli eventi `moveend` e `zoomend` per ridurre le chiamate API.
|
|
2. **Refresh Interval**: Mantenere l'intervallo di refresh di 60 secondi per i dati.
|
|
3. **Lazy Loading**: I dati vengono caricati solo quando necessario (al cambio di filtri o posizione).
|
|
|
|
### API Integration
|
|
|
|
1. **Parametri**: I parametri `center` e `radius` vengono aggiunti alla query string dell'API.
|
|
2. **Formato**: `center` come `[lat, lng]` e `radius` come numero intero in metri.
|
|
3. **Compatibilità**: Mantenere la compatibilità con i parametri esistenti.
|
|
|
|
## Dipendenze
|
|
|
|
### Nuove Dipendenze (se necessarie)
|
|
|
|
Non sono richieste nuove dipendenze. React-Leaflet e Leaflet forniscono già tutte le funzionalità necessarie.
|
|
|
|
### Dipendenze Esistenti
|
|
|
|
- `react-leaflet`: Per la mappa e gli hooks
|
|
- `leaflet`: Per le funzioni di calcolo della distanza
|
|
- `react`: Per gli hooks e la gestione dello stato
|
|
|
|
## Rischi e Mitigazioni
|
|
|
|
| Rischio | Mitigazione |
|
|
|---------|-------------|
|
|
| Geolocalizzazione non disponibile | Fallback a posizione di default |
|
|
| Troppo chiamate API durante pan/zoom | Debouncing di 500ms |
|
|
| Calcolo radius impreciso | Usare `distanceTo` di Leaflet per precisione |
|
|
| Performance con molti marker | Clustering già implementato |
|
|
| Permessi geolocalizzazione negati | Gestire errore e usare default |
|
|
|
|
## Criteri di Successo
|
|
|
|
1. ✅ L'applicazione geolocalizza l'utente al primo caricamento
|
|
2. ✅ Il center della mappa viene calcolato e passato all'API
|
|
3. ✅ Il radius viene calcolato in metri e copre l'intera viewport
|
|
4. ✅ I dati vengono aggiornati quando la mappa viene spostata/zoomata
|
|
5. ✅ L'API riceve correttamente i parametri center e radius
|
|
6. ✅ L'esperienza utente rimane fluida (nessun lag eccessivo)
|
|
7. ✅ Il fallback funziona correttamente se la geolocalizzazione fallisce
|
|
|
|
## Ordine di Esecuzione
|
|
|
|
1. Aggiornare i tipi in `src/types.ts`
|
|
2. Aggiornare l'API in `src/api.ts`
|
|
3. Creare l'hook `useMapGeolocation.ts`
|
|
4. Creare l'hook `useMapBounds.ts`
|
|
5. Aggiornare `PlayerMap.tsx`
|
|
6. Aggiornare `App.tsx`
|
|
7. Testare l'integrazione completa
|