nodeMap/README.md

# 🌍 NodeMap – Interaktive Kartenvisualisierung mit Leaflet & React

NodeMap ist eine modulare Kartenanwendung zur Visualisierung und Bearbeitung von GIS-Daten, POIs und Gerätestatus in einer interaktiven Leaflet-Karte.  
Die Anwendung ist mit **Next.js**, **React**, **Redux Toolkit**, **Tailwind CSS** und **Leaflet** umgesetzt.

---

> Diese README richtet sich an Entwickler, Administratoren und fortgeschrittene Benutzer.  
> Sie enthält technische Einrichtung, Systemüberblick, Benutzeranleitung und Hinweise zur Webservice-Integration.

> 🖥 Entwicklung & Test unter Windows 11 mit Node.js v18.17.1 und IIS  
> 📦 MySQL 8.0 läuft lokal in einem Docker-Container (nur für Entwicklung)  
> 🗄 In der Produktionsumgebung läuft ein echter Windows-MySQL-Dienst

## 📌 Ziel des Projekts in 30 Sekunden

Diese Anwendung dient der Visualisierung und Bearbeitung von Karteninhalten (POIs, Gerätestatus) innerhalb von TALAS V5.  
Sie funktioniert vollständig lokal und offline auf Windows-Servern – gesteuert über URL-Parameter `?m=` (Map-ID) und `?u=` (User-ID).

---

## 🧰 Erste Schritte für Entwickler

```bash
git clone http://10.10.0.12:3000/ISA/nodeMap
cd nodeMap
npm install
npm run dev
```

---

## 🧭 Zielumgebung

- Windows-Produktionsserver (offline, kein Internet)
- Kommunikation nur im lokalen Netzwerk
- Nutzerzugriff per VPN + Remote Desktop (RDP)
- Integration per iFrame in TALAS V5 / TALAS.web

---

## 🔄 Wie funktioniert das System?

1. TALAS ruft die App mit URL auf: `http://10.10.0.13/talas5/MessagesMap/mapTypC.aspx?m=12&u=484`
2. Die App liest `m` und `u` aus der URL
3. `MapComponent` lädt POIs, Linien, Rechte entsprechend
4. API-Endpunkte kommunizieren lokal mit Datenbankserver (MySQL)
5. Interaktive Bearbeitung (POI hinzufügen, verschieben, löschen) ist möglich

---

## 🚀 Funktionen

- Leaflet-basierte interaktive Karte
- Rechtebasierte UI durch URL-Parameter (`?m`, `?u`)
- POI hinzufügen, bearbeiten, verschieben, löschen
- Gerätestatus und Layeranzeige
- Intervallbasierte Datenaktualisierung
- Integration als iFrame in TALAS.web
- Versionsanzeige über `.env.local`
- Testdaten per Mock-API möglich (nur in der Entwicklungsumgebung)

---

## 🧱 Projektstruktur

```bash
components/     → UI-Komponenten inkl. Karte und Layer-Control-Panel (`MapLayersControlPanel`)

📦components
 ┣ 📂contextmenu
 ┃ ┣ 📜CoordinatePopup.js
 ┃ ┗ 📜useMapContextMenu.js
 ┣ 📂gisPolylines
 ┃ ┣ 📂icons
 ┃ ┃ ┣ 📜CircleIcon.js
 ┃ ┃ ┣ 📜EndIcon.js
 ┃ ┃ ┣ 📜StartIcon.js
 ┃ ┃ ┗ 📜SupportPointIcons.js
 ┃ ┗ 📜PolylineContextMenu.js
 ┣ 📂icons
 ┃ ┗ 📂devices
 ┃ ┃ ┗ 📂overlapping
 ┃ ┃ ┃ ┗ 📜PlusRoundIcon.js
 ┣ 📂mainComponent
 ┃ ┣ 📂hooks
 ┃ ┃ ┗ 📜useInitializeMap.js
 ┃ ┗ 📜MapComponent.js
 ┣ 📂pois
 ┃ ┣ 📜AddPOIModal.js
 ┃ ┗ 📜PoiUpdateModal.js
 ┣ 📂uiWidgets
 ┃ ┣ 📂mapLayersControlPanel
 ┃ ┃ ┣ 📜EditModeToggle.js
 ┃ ┃ ┗ 📜MapLayersControlPanel.js
 ┃ ┣ 📜CoordinateInput.js
 ┃ ┗ 📜VersionInfoModal.js
 ┗ 📜TestScript.js


config/         → zentrale Variablen (.env.local)

hooks/          → eigene React-Hooks

utils/          → POI- und Linienverarbeitung

lib/            → Formatierungen, Umrechnungen

public/         → mapTiles, Bilder, Icons

pages/          → Next.js Seiten & Routen

scripts/        → lokale Tools (nur Dev)

redux/          → globale Zustände (Slices)
📦redux
 ┣ 📂slices
 ┃ ┣ 📂database
 ┃ ┃ ┣ 📜addPoiSlice.js
 ┃ ┃ ┣ 📜gisLinesSlice.js
 ┃ ┃ ┣ 📜locationDevicesFromDBSlice.js
 ┃ ┃ ┣ 📜locationDevicesSlice.js
 ┃ ┃ ┣ 📜poiIconsDataSlice.js
 ┃ ┃ ┣ 📜poiTypesSlice.js
 ┃ ┃ ┣ 📜poiTypSlice.js
 ┃ ┃ ┗ 📜priorityConfigSlice.js
 ┃ ┣ 📂webservice
 ┃ ┃ ┣ 📜gisLinesStatusSlice.js
 ┃ ┃ ┣ 📜gisStationsMeasurementsSlice.js
 ┃ ┃ ┣ 📜gisStationsStaticDistrictSlice.js
 ┃ ┃ ┣ 📜gisStationsStatusDistrictSlice.js
 ┃ ┃ ┣ 📜gisSystemStaticSlice.js
 ┃ ┃ ┗ 📜userRightsSlice.js
 ┃ ┣ 📜addPoiOnPolylineSlice.js
 ┃ ┣ 📜currentPoiSlice.js
 ┃ ┣ 📜lineVisibilitySlice.js
 ┃ ┣ 📜mapLayersSlice.js
 ┃ ┣ 📜poiLayerVisibleSlice.js
 ┃ ┣ 📜poiReadFromDbTriggerSlice.js
 ┃ ┣ 📜polylineContextMenuSlice.js
 ┃ ┣ 📜polylineEventsDisabledSlice.js
 ┃ ┣ 📜polylineLayerVisibleSlice.js
 ┃ ┣ 📜readPoiMarkersStoreSlice.js
 ┃ ┣ 📜selectedAreaSlice.js
 ┃ ┣ 📜selectedDeviceSlice.js
 ┃ ┣ 📜selectedPoiSlice.js
 ┃ ┣ 📜urlParameterSlice.js
 ┃ ┗ 📜zoomTriggerSlice.js
 ┣ 📂thunks
 ┃ ┣ 📂database
 ┃ ┃ ┣ 📜addPoiThunk.js
 ┃ ┃ ┣ 📜fetchGisLinesThunk.js
 ┃ ┃ ┣ 📜fetchLocationDevicesThunk.js
 ┃ ┃ ┣ 📜fetchPoiIconsDataThunk.js
 ┃ ┃ ┣ 📜fetchPoiTypThunk.js
 ┃ ┃ ┗ 📜fetchPriorityConfigThunk.js
 ┃ ┗ 📂webservice
 ┃ ┃ ┣ 📜fetchGisLinesStatusThunk.js
 ┃ ┃ ┣ 📜fetchGisStationsMeasurementsThunk.js
 ┃ ┃ ┣ 📜fetchGisStationsStaticDistrictThunk.js
 ┃ ┃ ┣ 📜fetchGisStationsStatusDistrictThunk.js
 ┃ ┃ ┣ 📜fetchGisSystemStaticThunk.js
 ┃ ┃ ┗ 📜fetchUserRightsThunk.js
 ┗ 📜store.js

services/       → API-Kommunikation, Mock-Logik
📦services
 ┣ 📂database
 ┃ ┣ 📜addPoiService.js
 ┃ ┣ 📜fetchDeviceNameByIdService.js
 ┃ ┣ 📜fetchGisLinesService.js
 ┃ ┣ 📜fetchLocationDevicesService.js
 ┃ ┣ 📜fetchPoiDataByIdService.js
 ┃ ┣ 📜fetchPoiDataService.js
 ┃ ┣ 📜fetchPoiIconsDataService.js
 ┃ ┣ 📜fetchPoiTypService.js
 ┃ ┣ 📜fetchPriorityConfigService.js
 ┃ ┗ 📜updateLocationInDatabaseService.js
 ┣ 📂utils
 ┃ ┗ 📜fetchWithTimeout.js
 ┗ 📂webservice
 ┃ ┣ 📜fetchGisLinesStatusService.js
 ┃ ┣ 📜fetchGisStationsMeasurementsService.js
 ┃ ┣ 📜fetchGisStationsStaticDistrictService.js
 ┃ ┣ 📜fetchGisStationsStatusDistrictService.js
 ┃ ┣ 📜fetchGisSystemStaticService.js
 ┃ ┗ 📜fetchUserRightsService.js
```

---

## ⚙ Lokale Entwicklung

```bash
npm install
npm run dev
```

> 🔧 Nur für Entwicklung. Kein VPN, kein iFrame nötig.  
> API-Aufrufe ggf. via Mockdaten.

---

## 🖥 Installation auf Server (Test oder Produktion)

### 1. Build erstellen

```bash
npm install
npm run build
```

### 2. Dateien übertragen nach:

```
C:\inetpub\wwwroot/talas5/nodeMap
```

Beinhaltet:

- `.next/`, `node_modules/`, `public/`
- `package.json`, `.env.local`
  -Zum Erstellen des Windows-Dienstes nodeMapService werden folgende Dateien benötigt: nssm.exe, nssm Installation.md, Start-Dev.ps1 und StartNodeApp.bat

### 3. Starten

Erstellte Windows Dienst "nodeMapService" starten oder im Terminal

```bash
npm start
```

---

## 🔁 Code-Update

Wenn keine neuen Bibliotheken installiert wurden mit npm install:

- `.next/` ersetzen
- `.env.local` bei Änderung

---

## 🌐 Portfreigabe

- Anwendung läuft auf Port `3000`
- Muss in Windows-Firewall freigegeben sein
- Kein Zugriff über `localhost` im Netzwerk – **nur über IP**

Beispiel:

```
`http://10.10.0.13/talas5/MessagesMap/mapTypC.aspx?m=12&u=484`
```

---

## 🔗 Integration in TALAS.web

- Die App wird in einem **iFrame** geladen
- Startet über `?m=X&u=Y` für Map-/User-IDs
- Rechte und Inhalte werden automatisch geladen
- Kein statischer Export (`npm run export`) notwendig!

---

## 🔐 Konfiguration – `.env.local`

```env
NEXT_PUBLIC_APP_VERSION=1.1.59
NEXT_PUBLIC_USE_MOCK_API=true
```

- Nur `NEXT_PUBLIC_...` ist im Browser sichtbar
- Keine Passwörter oder vertraulichen Daten mit `NEXT_PUBLIC_` speichern – diese sind im Browser sichtbar

---

## 🧠 Zustand: Redux (ehemals Recoil)

Die Anwendung verwendet vollständig **Redux Toolkit** für die globale Zustandverwaltung.  
Alle ehemaligen Recoil-Atoms wurden erfolgreich in Redux-Slices überführt.

> Recoil wurde vollständig entfernt, um die Skalierbarkeit und Wartbarkeit zu verbessern.

### Gründe für Redux statt Recoil:

- Bessere Nachvollziehbarkeit durch zentrale Store-Struktur
- Unterstützung für DevTools, Logging, Debugging
- Einheitliche Behandlung von Status, auch bei komplexen Komponenten

➡ Neue Features bitte ausschließlich mit Redux umsetzen!

---

## 🧪 Mockdaten (nur Entwicklung)

```env
NEXT_PUBLIC_USE_MOCK_API=true
```

→ Lädt `/api/mockData/...` statt echtem Server.

---

## 🧰 Fehler & Debug

- Fehler per Toast oder `console.log`
- Logging möglich:

```bash
npm start > log.txt 2>&1
```

- Nur aktiv bei:

```js
if (process.env.NEXT_PUBLIC_DEBUG === 'true') console.log(...)
```

---

## ✅ Tests & Qualitätssicherung

- **E2E-Tests:** Cypress (nur in der Entwicklungsumgebung)
- **Unit-Tests:** Aktuell keine Jest-Tests aufgrund Leaflet-Komplexität
- **Empfehlung:** Manuelle Tests nach jedem Deployment durchführen (Checkliste vorbereiten)

---

## 🧩 Abhängigkeiten

- Next.js, React, Redux Toolkit, Leaflet
- Tailwind CSS, Toastify
- Full list → `package.json`

---

## 🏷 Versionierung

```env
NEXT_PUBLIC_APP_VERSION=1.1.59
```

→ Wird in der Fußzeile angezeigt.

---

## 🧪 Beispiel `.env.local`

```env
NEXT_PUBLIC_APP_VERSION=1.1.59
NEXT_PUBLIC_USE_MOCK_API=true
```

---

## 🛠 Zusätzliche Hinweise

### Voraussetzungen

- Node.js und npm müssen installiert sein: https://nodejs.org
- MySQL Datenbank läuft in einem Docker-Container (lokal bei Entwicklung)
- TALAS V5/TALAS.web ist im IIS lokal installiert

### Leaflet mapTiles

- Damit nicht ausversehen mapTiles gelöscht werden beim Code Update, werden die hier eingefügt, wenn vorhanden, müssen keine mapTiles manuell kopiert werden mapTiles auf dem server einzufügen:  
  `C:\inetpub\wwwroot\talas5\TileMap`

### Serverkonfiguration

- Port 3000 muss freigegeben sein
- .env.local, MapComponent.js und alle Services verwenden dynamische API-Endpunkte basierend auf window.location und NEXT_PUBLIC_API_PORT_MODE
- Die Anwendung wird über einen `nssm` Windows-Service gestartet (optional)
- Browser: Chrome ab Version 125.0.6420.142 empfohlen

---

## 🧭 Benutzeranleitung

- **Station öffnen:** Rechte Maustaste → "Station öffnen" oder "Station öffnen (Tab)"
- **POI hinzufügen:** Rechtsklick → "POI hinzufügen" → Formular ausfüllen
- **POI bearbeiten/löschen:** Kontextmenü verwenden
- **POI verschieben:** Drag & Drop des Markers, automatische DB-Aktualisierung
- **Koordinaten anzeigen:** Kontextmenüoption nutzen
- **Zoom:** Mausrad oder Kontextmenüoption
- **Layer steuern:** GIS-Geräte-Layer (z. B. TALAS, WAGO, GMA) ein-/ausblenden über Checkboxen im rechten Panel (`MapLayersControlPanel`)
- **Station auswählen:** Dropdown oben rechts
- **Zentrieren:** Rechtsklick → "Hier zentrieren"

---

## 🧰 Fehlerbehandlung

- Seite neu laden, wenn POIs nicht korrekt geladen werden
- Sicherstellen, dass alle API-Endpunkte erreichbar sind
- `.env.local` prüfen
- Port 3000 freigeben

---

## 📂 Erweiterte Verzeichnisstruktur

- `/styles/`: Tailwind- und CSS-Dateien
- `/store/`: Recoil-Atome (teilweise durch Redux ersetzt)
- `/api/`: POI-spezifische Endpunkte wie `addLocation.js`, `updateLocation.js`, `locations.js`
- `/config/config.js`: zentrale Konfigurationswerte (API, Server-IP, etc.)

---

## 📡 Webservice-Anbindung (Backend: TALAS.web)

NodeMap verwendet verschiedene Webservices, die von **TALAS V5/TALAS.web** im IIS bereitgestellt werden.  
Diese Services liefern dynamische GIS-, Geräte- und Statusdaten für die MapComponent.

### URL des Webservice:

```
http://localhost/talas5/ClientData/WebServiceMap.asmx
```

> 🔧 In `.env.local` oder `config.js` muss die Adresse je nach Umgebung angepasst werden (z. B. `http://10.10.0.13/talas5/...`)

### Verfügbare Methoden (Auszug):

| Endpunkt                    | Zweck / Datenquelle                        |
| --------------------------- | ------------------------------------------ |
| `CablesStatic`              | Liste aller Stränge                        |
| `GetIconsStatic`            | Liste aller Icons                          |
| `GisLinesStatus`            | Liste aller Status der Linien              |
| `GisStationsMeasurements`   | Liste aller Messungen der Geräte           |
| `GisStationsStaticDistrict` | Liste aller Geraete einer bestimmten Karte |
| `GisStationsStatusDistrict` | Liste aller Statis der Geräte              |
| `GisSystemStatic`           | Liste aller angezeigten Systeme            |

Die Webservices liefern JSON und werden im Frontend über `services/*.js` abgefragt.  
Die Daten werden verarbeitet, zwischengespeichert und z. T. über Redux oder Recoil in der Karte dargestellt.

➡ Damit alles funktioniert, müssen:

- der IIS laufen
- der `WebServiceMap.asmx` erreichbar sein
- die IP in `.env.local` korrekt gesetzt sein

---

## 🔁 🧳 Standard-Deployment-Ablauf auf dem Server

### Zielverzeichnis:

```
C:\inetpub\wwwroot/talas5/nodeMap
```

### Schritte:

1. **Build erstellen**  
   Führe `npm run build` in der Entwicklungsumgebung aus

2. **Build-Dateien sammeln**  
   Kopiere folgende Ordner/Dateien in einen neuen Ordner:

   - `.next/`
   - `node_modules/`
   - `public/`
   - `package.json`
   - `.env.local`

3. **IP-Adresse aktualisieren**  
   Verwende „Find in Files“ in VSCode, um z. B. `10.10.0.13` durch neue Server-IP zu ersetzen

4. **ZIP erstellen**  
   Packe den Build-Ordner als ZIP (z. B. `nodeMap_V1.1.62.zip`)

5. **ZIP auf Server hochladen**

6. **ZIP entpacken auf dem Server**  
   z. B. nach: `C:\inetpub\wwwroot/talas5/nodeMap V1.1.62`

7. **Dienst beenden (falls aktiv)**  
   Beende `NodeMapService`, falls dieser noch `npm run dev` nutzt

8. **Backup vom alten nodeMap-Ordner erstellen**  
   Benenne z. B. um in `nodeMap_Alt_1.1.56`

9. **Neuen Ordner umbenennen → `nodeMap`**

10. **Wechsle in neuen Ordner**

    ```powershell
    cd C:\inetpub\wwwroot/talas5/nodeMap
    ```

11. **App starten**
    Windows Server Dienst "nodeMapService" starten
    oder in Terminal

    ```bash
    npm start
    ```

12. **Testen im Browser**

    ```url
    http://10.10.0.13/talas5/MessagesMap/mapTypC.aspx?m=12&u=484
    ```

13. Bei erst Installation auf dem Server Windows-Dienst `NodeMapService` auf dem Server erstellen
    mit nssm.exe
    > Der Dienst führt Batch-Skript `StartNodeApp.bat` aus.  
    > `StartNodeApp.bat` führt `Start-Dev.ps1` aus
    > `Start-Dev.ps1`führt `npm start` aus

---

## 💾 Setup: Installationen & Tools

Für die lokale Entwicklung bitte folgende Tools manuell installieren:

| Tool     | Version  | Link                                                                                                                                                                           |
| -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Node.js  | 20.12.1  | [nodejs](https://littwinsystemtechnik.sharepoint.com/:f:/r/sites/LittwinSystemtechnik/Freigegebene%20Dokumente/Projekte/Masterkarte%20V2%20setup%20files?csf=1&web=1&e=Sm1wwt) |
| Chrome   | optional | [Chrome](https://littwinsystemtechnik.sharepoint.com/:f:/r/sites/LittwinSystemtechnik/Freigegebene%20Dokumente/Projekte/Masterkarte%20V2%20setup%20files?csf=1&web=1&e=Sm1wwt) |
| NSSM.exe | 2.24     | [nssm](https://littwinsystemtechnik.sharepoint.com/:f:/r/sites/LittwinSystemtechnik/Freigegebene%20Dokumente/Projekte/Masterkarte%20V2%20setup%20files?csf=1&web=1&e=Sm1wwt)   |

> Hinweis: Die Datei `MapTypC.aspx` in TALAS lädt NodeMap als iFrame über Port 3000.  
> Wenn die Seite nicht angezeigt wird, bitte sicherstellen:
>
> - Port 3000 ist in der Firewall freigegeben
> - Die IP im Scriptteil von `MapTypC.aspx` ist aktuell (z. B. `10.10.0.13`)
> - `npm start` läuft oder der Windows-Dienst `NodeMapService` ist aktiv