# 🌍 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://<ip>/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

---

## 📦 Drittanbieter-Abhängigkeiten

| Paket / Bibliothek              | Version        | Zweck / Verwendung                             | Speicherort / Modul                   |
| ------------------------------- | -------------- | ---------------------------------------------- | ------------------------------------- |
| `react`                         | ^18.3.1        | UI-Framework                                   | `/components`                         |
| `next`                          | ^14.2.5        | Routing, Build, API-Routen                     | Root, `/pages`                        |
| `redux`, `@reduxjs/toolkit`     | ^5.0.1, ^2.5.1 | Zustandverwaltung (statt Recoil)               | `/redux/`, `store.js`                 |
| `leaflet`                       | ^1.9.4         | Interaktive Kartenvisualisierung               | `MapComponent.js`, Marker, Polylinien |
| `leaflet-contextmenu`           | ^1.4.0         | Kontextmenüs in Leaflet                        | Kontextmenü auf Karte                 |
| `tailwindcss`                   | ^3.4.7         | CSS-Utility-Framework                          | `styles/`, UI-Komponenten             |
| `react-toastify`                | ^10.0.5        | Benachrichtigungen im UI                       | z. B. bei Fehlern                     |
| `overlapping-marker-spiderfier` | ^0.2.7         | Marker-Darstellung bei Überlappung             | `checkOverlappingMarkers`             |
| `mysql`                         | ^2.18.1        | MySQL-Kommunikation in API                     | `pages/api/`, `services/database/`    |
| `nssm.exe`                      | 2.24           | Windows-Service zur Ausführung von `npm start` | für Serverbetrieb                     |
| `WebService TALAS`              | intern         | Datenquelle für GIS- und Geräteinformationen   | `services/webservice/`, IIS-Aufruf    |

→ vollständige Liste: siehe `package.json`

---

## 🧰 Erstinstallation auf Server (z. B. Windows IIS)

### Voraussetzungen

- Windows Server mit IIS
- Sicherstellen, dass alle TALAS.web API-Endpunkte(WebService) erreichbar sind
- Node.js & npm installiert (z. B. v18–20)
- MySQL (lokal oder erreichbar)
- Port 3000 freigegeben (Firewall)
- IIS-Datei `mapTypC.aspx` vorhanden in C:\inetpub\wwwroot\talas5\MessagesMap\
- Browser: Chrome ab Version 125.0.6420.142 empfohlen
- 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`

### Schritt-für-Schritt Anleitung

---

## 🔗 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!
  ```
  `http://10.10.0.13/talas5/MessagesMap/mapTypC.aspx?m=12&u=484`
  ```

---

1. **Projekt lokal klonen und bauen:**

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

   ```

2. **ZIP-Paket vorbereiten (lokal):**

   - `.next/`, `public/`, `node_modules/`
   - `.env.local`, `package.json`
   - optional: `nssm.exe`, `StartNodeApp.bat`, `Start-Dev.ps1`

3. **Auf Server kopieren nach:**

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

4. **Kartenmaterial hinzufügen (falls nicht vorhanden):**

   ```
   C:\inetpub\wwwroot\talas5\TileMap\
   ```

5. **Konfiguration `.env.local` anpassen:**

   ```env
   DB_HOST=localhost wenn die Datenbank auf dem selben Server ist
   DB_USER=Datenbankbenutzername
   DB_PASSWORD=Datenbankbenutzerpasswort
   DB_NAME=Datenbank Name
   DB_PORT=Datenbank Port
   NEXT_PUBLIC_BASE_PATH=/talas5 ->je nachdem , ob das leer ist oder andere Verzeichnisname hat
   NEXT_PUBLIC_API_PORT_MODE=prod  -> in Produktionsumgebung
   NEXT_PUBLIC_USE_MOCKS=false -> in Produktionsumgebung

   Beispiel
   ```

   ```env
   DB_HOST=localhost DB_USER=root DB_PASSWORD="root#$" DB_NAME=talas_v5 DB_PORT=3306

   NEXT_PUBLIC_API_PORT_MODE=prod NEXT_PUBLIC_USE_MOCKS=false NEXT_PUBLIC_BASE_PATH=/talas5
   ```

6. **Optional: Dienst registrieren**

- Mit `nssm.exe` Windows-Dienst „nodeMapService“ erstellen
- Ziel: `StartNodeApp.bat`

7. **Starten:**

   ```bash
   npm start
   ```

oder Dienst starten

8. **Im Browser testen:**
   ```
   http://<ip>/talas5/MessagesMap/mapTypC.aspx?m=IdMap&u=IdUser
   z.B.
   http://<ip>/talas5/MessagesMap/mapTypC.aspx?m=12&u=484
   ```

---

## 🔁 Update-Richtlinien

| Art                | Ersetzte Dateien                   | Bemerkung                    |
| ------------------ | ---------------------------------- | ---------------------------- |
| **Kleines Update** | `.next/`                           | `node_modules` nicht nötig   |
| **Großes Update**  | alle Dateien (wie Neuinstallation) | Dienst ggf. neu registrieren |

### Empfohlener Ablauf für kleines Update:

1. `.next/` vom neuen Build kopieren
2. Dienst oder `npm start` neu starten
3. Im Browser testen: `?m=...&u=...`

---

### 🔧 Konfigurierbarer Basispfad (basePath)

Standardmäßig wird angenommen, dass die Anwendung unter einem Unterverzeichnis wie `/talas5`
läuft.  
Der Basispfad kann nun über `.env.local` konfiguriert werden:

```env
NEXT_PUBLIC_BASE_PATH=/talas5
```

Wenn die Anwendung direkt unter der IP erreichbar sein soll (z. B. http://10.10.0.13/), kann der
Pfad leer gelassen werden:

```env
NEXT_PUBLIC_BASE_PATH=
```

## 🚀 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
- Testdaten möglich (nur in der Entwicklungsumgebung)
- Rechtsklick auf Geräte-Marker öffnet ein Kontextmenü mit:
  - „Station öffnen (Tab)“
  - Koordinaten anzeigen
  - Zoom & Zentrieren

---

---

## 🧠 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.

- Dynamische Gerätegruppen (Layer) werden automatisch über `IdSystem` aus `GisSystemStatic`
  initialisiert
- Layer-Steuerung erfolgt über `system-<IdSystem>` Keys im Redux `mapLayersSlice`
- Marker für Geräte werden über Vergleich `System` ↔ `IdSystem` angezeigt

### 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!

---

## 📄 Dokumentation

Eine technische API-Dokumentation befindet sich im Verzeichnis `/docs/`  
Beispiel:

- [`priorityConfig.md`](docs/pages/api/talas_v5_DB/priorityConfig.md):  
  Dokumentiert die Prioritätskonfiguration für Meldungsanzeige und Marker-Sortierung.

- [`device-layer-connection.md`](docs/architecture/device-layer-connection.md):  
   Beschreibt den technischen Ablauf vom GIS-System zum Marker über `System` ↔ `IdSystem`

---

## 🧪 Mockdaten (nur in der Entwicklung)

Nur in der Entwicklungsumgebung könnte NEXT_PUBLIC_USE_MOCKS auf true gesetzt werden. In
Produktionsumgebung muss NEXT_PUBLIC_USE_MOCKS=false sein

```env
NEXT_PUBLIC_USE_MOCKS=false
```

---

## 🧰 Fehler & Debug

- Fehler per Toast, alert oder `console.log`
- Logging Kann aktiviert oder deaktiviert werden in .env.local:

  ```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

wird mit husky Bibliothek automatisch erhöht bei "git commit message"

→ Wird in der Fußzeile angezeigt.

---

---

## 🧭 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"
- **Geräte-Kontextmenü:** Rechtsklick auf Marker → „Station öffnen (Tab)“

---

## 🧰 Fehlerbehandlung

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

---

## 📡 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

---

## 💾 Setup: Installationen & Tools

| 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

## 📁 Projektstruktur

➡ Die vollständige und kommentierte Projektstruktur findest du hier:  
[📄 docs/PROJECT_STRUCTURE.md](docs/PROJECT_STRUCTURE.md)