🌍 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

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

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
 ┃ ┃ ┣ 📂pois
 ┃ ┃ ┃ ┣ 📜addPoiOnPolylineSlice.js
 ┃ ┃ ┃ ┣ 📜addPoiSlice.js
 ┃ ┃ ┃ ┣ 📜currentPoiSlice.js
 ┃ ┃ ┃ ┣ 📜poiIconsDataSlice.js
 ┃ ┃ ┃ ┣ 📜poiLayerVisibleSlice.js
 ┃ ┃ ┃ ┣ 📜poiReadFromDbTriggerSlice.js
 ┃ ┃ ┃ ┣ 📜poiTypesSlice.js
 ┃ ┃ ┃ ┣ 📜poiTypSlice.js
 ┃ ┃ ┃ ┣ 📜readPoiMarkersStoreSlice.js
 ┃ ┃ ┃ ┗ 📜selectedPoiSlice.js
 ┃ ┃ ┣ 📂polylines
 ┃ ┃ ┃ ┣ 📜gisLinesSlice.js
 ┃ ┃ ┃ ┣ 📜polylineContextMenuSlice.js
 ┃ ┃ ┃ ┣ 📜polylineEventsDisabledSlice.js
 ┃ ┃ ┃ ┗ 📜polylineLayerVisibleSlice.js
 ┃ ┃ ┣ 📜locationDevicesFromDBSlice.js
 ┃ ┃ ┣ 📜locationDevicesSlice.js
 ┃ ┃ ┗ 📜priorityConfigSlice.js
 ┃ ┣ 📂webservice
 ┃ ┃ ┣ 📜gisLinesStatusSlice.js
 ┃ ┃ ┣ 📜gisStationsMeasurementsSlice.js
 ┃ ┃ ┣ 📜gisStationsStaticDistrictSlice.js
 ┃ ┃ ┣ 📜gisStationsStatusDistrictSlice.js
 ┃ ┃ ┣ 📜gisSystemStaticSlice.js
 ┃ ┃ ┗ 📜userRightsSlice.js
 ┃ ┣ 📜lineVisibilitySlice.js
 ┃ ┣ 📜mapLayersSlice.js
 ┃ ┣ 📜selectedAreaSlice.js
 ┃ ┣ 📜selectedDeviceSlice.js
 ┃ ┣ 📜urlParameterSlice.js
 ┃ ┗ 📜zoomTriggerSlice.js
 ┣ 📂thunks
 ┃ ┣ 📂database
 ┃ ┃ ┣ 📂pois
 ┃ ┃ ┃ ┣ 📜addPoiThunk.js
 ┃ ┃ ┃ ┣ 📜deletePoiThunk.js
 ┃ ┃ ┃ ┣ 📜fetchPoiIconsDataThunk.js
 ┃ ┃ ┃ ┣ 📜fetchPoiTypThunk.js
 ┃ ┃ ┃ ┗ 📜updatePoiThunk.js
 ┃ ┃ ┣ 📂polylines
 ┃ ┃ ┃ ┗ 📜fetchGisLinesThunk.js
 ┃ ┃ ┣ 📜fetchLocationDevicesThunk.js
 ┃ ┃ ┣ 📜fetchPriorityConfigThunk.js
 ┃ ┃ ┗ 📜getDeviceIdByNameThunk.js
 ┃ ┗ 📂webservice
 ┃ ┃ ┣ 📜fetchGisLinesStatusThunk.js
 ┃ ┃ ┣ 📜fetchGisStationsMeasurementsThunk.js
 ┃ ┃ ┣ 📜fetchGisStationsStaticDistrictThunk.js
 ┃ ┃ ┣ 📜fetchGisStationsStatusDistrictThunk.js
 ┃ ┃ ┣ 📜fetchGisSystemStaticThunk.js
 ┃ ┃ ┗ 📜fetchUserRightsThunk.js
 ┗ 📜store.js

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

---

⚙ Lokale Entwicklung

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

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

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

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!

🧩 Ausnahme:
Der Hook /hooks/layers/useAreaMarkersLayer.js verwendet bewusst einen lokalen fetch(),
da die Marker-Objekte direkt mit Leaflet (L.marker(...)) erzeugt und verwaltet werden.
Diese Marker sind UI-spezifisch und nicht zustandsfähig im Redux-Store.
Das Aktualisieren der Marker-Koordinaten beim Drag-and-Drop erfolgt aber vollständig über Redux (updateAreaThunk()).

---

🧪 Mockdaten (nur Entwicklung)

NEXT_PUBLIC_USE_MOCK_API=true

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

---

🧰 Fehler & Debug

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

npm start > log.txt 2>&1

• Nur aktiv bei:

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

NEXT_PUBLIC_APP_VERSION=1.1.59

→ Wird in der Fußzeile angezeigt.

---

🧪 Beispiel .env.local

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

    cd C:\inetpub\wwwroot/talas5/nodeMap
    

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

    npm start
    

12. Testen im Browser

    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.ps1fü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
Chrome	optional	Chrome
NSSM.exe	2.24	nssm

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