Ismail/nodeMap
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(docs): README.md optimiert und technische Dokumentation ausgelagert

Browse Source 
- README.md für Offline-Betrieb und Kundenserver überarbeitet (ohne npm install)
- Benutzeranleitung und technische Themen nach /docs/guide/ ausgelagert
- Neue Dateien: env.md, mock-data.md, webservices.md, redux-zustand.md, project-structure.md, dependencies.md, user-guide.md
- Tabellenstruktur und Verlinkungen im README modernisiert
- Fokus auf klare Trennung: Entwickler-Doku vs. Kundenbereitstellung
This commit is contained in:
ISA
2025-06-05 08:59:38 +02:00
parent f4342e17ef
commit 40cb07b485
11 changed files with 327 additions and 241 deletions
Download Patch File Download Diff File Expand all files Collapse all files

289
README.md
View File

@@ -1,4 +1,4 @@
# 🌍 NodeMap – Interaktive Kartenvisualisierung mit Leaflet & React
# 🌍 NodeMap – Kartenvisualisierung für TALAS.web (Next.js, Leaflet, Redux)
NodeMap ist eine modulare Kartenanwendung zur Visualisierung und Bearbeitung von GIS-Daten, POIs und
Gerätestatus in einer interaktiven Leaflet-Karte.
@@ -7,20 +7,9 @@ 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).
> 🗄 Produktionsumgebung: TALAS.web und MySQL Server unter Windows Server
---
@@ -40,40 +29,21 @@ npm run dev
- Windows-Produktionsserver (offline, kein Internet)
- Kommunikation nur im lokalen Netzwerk
- Nutzerzugriff per VPN + Remote Desktop (RDP)
- Integration per iFrame in TALAS V5 / TALAS.web
- Integration per iFrame in 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
1. TALAS.web ruft die App unter URL auf: `http://<ip>/talas5/MessagesMap/mapTypC.aspx?m=12&u=484`
2. Die App liest `m` und `u` aus der URL m(IdMap) u(IdUser)
3. `MapComponent` lädt POIs, Linien, Rechte, Geräte und Bereiche aus WebService von TALAS.web
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
@@ -89,23 +59,22 @@ npm run dev
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
- Startet über `?m=X&u=Y` für Map-/User-ID
- 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:**
### Schritt-für-Schritt Anleitung
1. **Projekt lokal klonen und kompilieren:**
```bash
git clone http://10.10.0.12:3000/ISA/nodeMap
@@ -117,9 +86,11 @@ npm run dev
2. **ZIP-Paket vorbereiten (lokal):**
- `.next/`, `public/`, `node_modules/`
- `.env.local`, `package.json`
- optional: `nssm.exe`, `StartNodeApp.bat`, `Start-Dev.ps1`
- Verzeichnisse `.next/`, `public/`, `node_modules/`
- Dateien `.env.production`, `package.json`
- optional: `nssm.exe`, `StartNodeApp.bat`, `Start-Dev.ps1` um Windows Dienst zu erstellen
Download:
[nssm](https://littwinsystemtechnik.sharepoint.com/:f:/r/sites/LittwinSystemtechnik/Freigegebene%20Dokumente/Projekte/Masterkarte%20V2%20setup%20files?csf=1&web=1&e=Sm1wwt)
3. **Auf Server kopieren nach:**
@@ -133,40 +104,28 @@ npm run dev
C:\inetpub\wwwroot\talas5\TileMap\
```
5. **Konfiguration `.env.local` anpassen:**
5. **.env.production konfigurieren**
```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
Die Datei `.env.production` enthält alle benötigten Verbindungs- und Betriebsvariablen wie z. B.
Datenbank-Zugang, Pfade und Mock-Option.
Beispiel
```
➡ Vollständige Anleitung & Beispieldatei:
[📄 docs/guide/env.md](docs/guide/env.md)
```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**
6. **Dienst registrieren falls nicht vorhanden**
- Mit `nssm.exe` Windows-Dienst „nodeMapService“ erstellen
- Ziel: `StartNodeApp.bat`
- Anleitung:
[nssm](https://littwinsystemtechnik.sharepoint.com/:f:/r/sites/LittwinSystemtechnik/Freigegebene%20Dokumente/Projekte/Masterkarte%20V2%20setup%20files?csf=1&web=1&e=Sm1wwt)
7. **Starten:**
7. **Starten:**
Dienst starten oder
```bash
npm start
npm start in Terminal für Debugging
```
oder Dienst starten
8. **Im Browser testen:**
```
http://<ip>/talas5/MessagesMap/mapTypC.aspx?m=IdMap&u=IdUser
@@ -185,101 +144,9 @@ oder Dienst starten
### Empfohlener Ablauf für kleines Update:
1. `.next/` vom neuen Build kopieren
1. `.next/` Verzeichnis nach Kompilieren kopieren und auf dem Server einfügen
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(...)
```
3. Im Browser testen: ` http://<ip>/talas5/MessagesMap/mapTypC.aspx?m=IdMap&u=IdUser`
---
@@ -291,14 +158,6 @@ NEXT_PUBLIC_USE_MOCKS=false
---
## 🧩 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"
@@ -307,71 +166,6 @@ wird mit husky Bibliothek automatisch erhöht bei "git commit message"
---
---
## 🧭 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 |
@@ -387,7 +181,26 @@ dargestellt.
> - 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
## 📁 Dokumentation & technische Leitfäden
➡ Die vollständige und kommentierte Projektstruktur findest du hier:
[📄 docs/PROJECT_STRUCTURE.md](docs/PROJECT_STRUCTURE.md)
| Thema | Link |
| ------------------------- | ------------------------------------------------------- |
| Benutzeranleitung | [docs/guide/user-guide.md](docs/guide/user-guide.md) |
| Projektstruktur | [project-structure.md](docs/guide/project-structure.md) |
| Webservices (TALAS) | [webservices.md](docs/guide/webservices.md) |
| Umgebungsvariablen | [env.md](docs/guide/env.md) |
| Mockdaten-Modus | [mock-data.md](docs/guide/mock-data.md) |
| Zustandverwaltung (Redux) | [redux-zustand.md](docs/guide/redux-zustand.md) |
| Abhängigkeiten | [dependencies.md](docs/guide/dependencies.md) |
---
## 🧰 Fehlerbehandlung
- **App startet leer?** → `.env.production` prüfen
- **Kartenkacheln fehlen?** → `public/mapTiles/` korrekt eingebunden?
- **Keine Marker sichtbar?** → Webservice erreichbar?
- Seite neu laden, wenn POIs nicht korrekt geladen werden
- Port 3000 freigeben
---