[31b88f42] Update documentation and infrastructure for staff locations and ORS integration

heatmap-tool/README.md

@@ -5,7 +5,12 @@ Eine Webanwendung zur Visualisierung von Excel-Daten (XLSX) auf einer Deutschlan
 ## Features
 
 *   **Excel Upload:** Lädt beliebige `.xlsx` Dateien. Erkennt automatisch die PLZ-Spalte (oder fragt nach, wenn unklar).
-*   **Datenschutz:** Daten werden nur temporär im RAM des Containers verarbeitet. Keine Datenbank.
+*   **Personal-Standorte:** Fest hinterlegte Standorte von Vertrieblern (Blau) und Technikern (Orange) können unabhängig von Excel-Daten eingeblendet werden.
+*   **Einzugsgebiete (Isochronen):**
+    *   Visualisierung der Erreichbarkeit basierend auf echter Fahrtzeit über das Straßennetz (via OpenRouteService).
+    *   Berücksichtigt Autobahnen und Straßentypen (verzerrte Polygone statt perfekter Kreise).
+    *   **Fallback:** Automatisches Umschalten auf ein mathematisches Kreis-Modell (Radius = Zeit * Geschwindigkeit), falls kein API-Key vorhanden ist.
+*   **Interaktive Planung:** Schieberegler für Fahrtzeit (bis 60 Min.) und Durchschnittsgeschwindigkeit zur Simulation von Reichweiten.
 *   **Visualisierung:**
     *   **Punkte-Karte:** Kreise pro PLZ, Radius = Anzahl der Einträge. Mit Marker-Clustering beim Herauszoomen.
     *   **Heatmap:** Klassische Dichte-Darstellung.
@@ -16,27 +21,33 @@ Eine Webanwendung zur Visualisierung von Excel-Daten (XLSX) auf einer Deutschlan
 
 Das Projekt ist vollständig in den **GTM-Engine Stack** integriert.
 
-1.  Container starten (im Root-Verzeichnis):
+1.  **API Key konfigurieren:** Für echte Fahrtzeiten (Isochronen) einen kostenlosen Key auf [openrouteservice.org](https://openrouteservice.org/) erstellen und in der `.env` hinterlegen:
+    ```env
+    ORS_API_KEY=dein_key_hier
+    ```
+
+2.  Container starten (im Root-Verzeichnis):
     ```bash
     docker-compose up -d --build heatmap-frontend heatmap-backend
     ```
 
-2.  Anwendung öffnen:
-    *   **URL:** `https://<DEINE-IP>:8090/heatmap/` (via Nginx Gateway)
-    *   **Login:** Basic Auth (`admin` / `gemini`)
-
 ## Architektur
 
 *   **Frontend:** React 19, Vite, Leaflet (`react-leaflet`, `react-leaflet-cluster`, `react-leaflet-heatmap-layer-v3`).
     *   **Interner Port:** 80 (Nginx)
     *   **Routing:** `/heatmap/` (via Gateway)
-*   **Backend:** Python FastAPI, Pandas (für Excel-Processing).
+*   **Backend:** Python FastAPI, Pandas, Requests (für ORS API).
     *   **Interner Port:** 8000
 *   **Kommunikation:** Nginx (Frontend) leitet `/api/` Anfragen an das Backend weiter.
 
 ## Lessons Learned & Known Issues (WICHTIG!)
 
-### 1. Docker Networking & Nginx Proxy
+### 1. OpenRouteService (ORS) API Limits
+*   **Limit:** Der kostenlose "Free Tier" erlaubt Isochronen bis maximal **60 Minuten**.
+*   **Fehler:** Anfragen über 60 Min. resultieren in einem `400 Bad Request`. Das Frontend ist daher auf diesen Wert begrenzt.
+*   **Debouncing:** Da API-Calls kontingentiert sind (500/Tag), werden Isochronen erst nach einer kurzen Pause (800ms) beim Schieben des Reglers angefordert.
+
+### 2. Docker Networking & Nginx Proxy
 *   **Integration:** Das Tool läuft nun hinter einem zentralen Nginx-Gateway.
 *   **Pfad-Anpassung:** `vite.config.ts` nutzt `base: '/heatmap/'`, damit Assets korrekt geladen werden.
 *   **API-Routing:** Das Frontend-Nginx (`nginx.conf`) proxied `/api/` an `http://heatmap-backend:8000`. Dies verhindert `405 Method Not Allowed` Fehler bei POST-Requests, die sonst vom statischen Server abgefangen würden.