Files

ISA 5362cb2605 docs: aktualisiere README.md für MapLayersControlPanel Komponente

- Abschnitt "Benutzeranleitung" beschreibt jetzt Layer-Steuerung präziser
- Projektstruktur ergänzt für bessere Verständlichkeit
- Funktion "Sichtbarkeit steuern" explizit genannt

2025-05-22 07:03:47 +02:00

12 KiB

Raw Blame History

🌍 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?

TALAS ruft die App mit URL auf: http://10.10.0.13/talas5/MessagesMap/mapTypC.aspx?m=12&u=484
Die App liest m und u aus der URL
MapComponent lädt POIs, Linien, Rechte entsprechend
API-Endpunkte kommunizieren lokal mit Datenbankserver (MySQL)
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`)
config/         → zentrale Variablen (.env.local)
hooks/          → eigene React-Hooks
redux/          → globale Zustände (Slices)
services/       → API-Kommunikation, Mock-Logik
utils/          → POI- und Linienverarbeitung
lib/            → Formatierungen, Umrechnungen
public/         → mapTiles, Bilder, Icons
pages/          → Next.js Seiten & Routen
scripts/        → lokale Tools (nur Dev)

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

🧪 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, config.js, [...]path.js und MapComponent.js müssen IP und API-Endpunkte korrekt konfiguriert haben
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:

Build erstellen
Führe npm run build in der Entwicklungsumgebung aus
Build-Dateien sammeln
Kopiere folgende Ordner/Dateien in einen neuen Ordner:
- .next/
- node_modules/
- public/
- package.json
- .env.local
IP-Adresse aktualisieren
Verwende „Find in Files“ in VSCode, um z. B. 10.10.0.13 durch neue Server-IP zu ersetzen
ZIP erstellen
Packe den Build-Ordner als ZIP (z. B. nodeMap_V1.1.62.zip)
ZIP auf Server hochladen
ZIP entpacken auf dem Server
z. B. nach: C:\inetpub\wwwroot/talas5/nodeMap V1.1.62
Dienst beenden (falls aktiv)
Beende NodeMapService, falls dieser noch npm run dev nutzt
Backup vom alten nodeMap-Ordner erstellen
Benenne z. B. um in nodeMap_Alt_1.1.56
Neuen Ordner umbenennen → nodeMap
Wechsle in neuen Ordner
```
cd C:\inetpub\wwwroot/talas5/nodeMap
```
App starten Windows Server Dienst "nodeMapService" starten oder in Terminal
```
npm start
```

Testen im Browser

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

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

12 KiB Raw Blame History Unescape Escape