add geo location
This commit is contained in:
Matteo Rosati
428
plans/geolocation-and-bounds-implementation.md
Normal file
428
plans/geolocation-and-bounds-implementation.md
Normal file
@@ -0,0 +1,428 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user