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

4
.env.local
View File

@@ -12,8 +12,8 @@ NEXT_PUBLIC_DEBUG_LOG=true
#auf dem Entwicklungsrechner dev läuft auf Port 3000 und auf dem Server prod auf Port 80, aber der WebService ist immer auf PORT 80 #auf dem Entwicklungsrechner dev läuft auf Port 3000 und auf dem Server prod auf Port 80, aber der WebService ist immer auf PORT 80
NEXT_PUBLIC_API_PORT_MODE=dev NEXT_PUBLIC_API_PORT_MODE=prod
NEXT_PUBLIC_USE_MOCKS=true NEXT_PUBLIC_USE_MOCKS=false
# Der Unterordner talas5 gleich hinter der IP-Adresse (oder Servername) muss konfigurierbar sein. # Der Unterordner talas5 gleich hinter der IP-Adresse (oder Servername) muss konfigurierbar sein.
# Es muss auch möglich sein kein Unterorder anzugeben (z.B. nur http://talasserver/). # Es muss auch möglich sein kein Unterorder anzugeben (z.B. nur http://talasserver/).

287
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 NodeMap ist eine modulare Kartenanwendung zur Visualisierung und Bearbeitung von GIS-Daten, POIs und
Gerätestatus in einer interaktiven Leaflet-Karte. 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 > 🖥 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) > 📦 MySQL 8.0 läuft lokal in einem Docker-Container (nur für Entwicklung)
> 🗄 In der Produktionsumgebung läuft ein echter Windows-MySQL-Dienst > 🗄 Produktionsumgebung: TALAS.web und MySQL Server unter Windows Server
## 📌 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).
--- ---
@@ -40,40 +29,21 @@ npm run dev
- Windows-Produktionsserver (offline, kein Internet) - Windows-Produktionsserver (offline, kein Internet)
- Kommunikation nur im lokalen Netzwerk - Kommunikation nur im lokalen Netzwerk
- Nutzerzugriff per VPN + Remote Desktop (RDP) - Nutzerzugriff per VPN + Remote Desktop (RDP)
- Integration per iFrame in TALAS V5 / TALAS.web - Integration per iFrame in TALAS.web
--- ---
## 🔄 Wie funktioniert das System? ## 🔄 Wie funktioniert das System?
1. TALAS ruft die App mit URL auf: `http://<ip>/talas5/MessagesMap/mapTypC.aspx?m=12&u=484` 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 2. Die App liest `m` und `u` aus der URL m(IdMap) u(IdUser)
3. `MapComponent` lädt POIs, Linien, Rechte entsprechend 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) 4. API-Endpunkte kommunizieren lokal mit Datenbankserver (MySQL)
5. Interaktive Bearbeitung (POI hinzufügen, verschieben, löschen) ist möglich 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) ## 🧰 Erstinstallation auf Server (z. B. Windows IIS)
### Voraussetzungen ### Voraussetzungen
@@ -89,23 +59,22 @@ npm run dev
vorhanden, müssen keine mapTiles manuell kopiert werden mapTiles auf dem server einzufügen: vorhanden, müssen keine mapTiles manuell kopiert werden mapTiles auf dem server einzufügen:
`C:\inetpub\wwwroot\talas5\TileMap` `C:\inetpub\wwwroot\talas5\TileMap`
### Schritt-für-Schritt Anleitung
--- ---
## 🔗 Integration in TALAS.web ## 🔗 Integration in TALAS.web
- Die App wird in einem **iFrame** geladen - 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 - 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` `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 ```bash
git clone http://10.10.0.12:3000/ISA/nodeMap git clone http://10.10.0.12:3000/ISA/nodeMap
@@ -117,9 +86,11 @@ npm run dev
2. **ZIP-Paket vorbereiten (lokal):** 2. **ZIP-Paket vorbereiten (lokal):**
- `.next/`, `public/`, `node_modules/` - Verzeichnisse `.next/`, `public/`, `node_modules/`
- `.env.local`, `package.json` - Dateien `.env.production`, `package.json`
- optional: `nssm.exe`, `StartNodeApp.bat`, `Start-Dev.ps1` - 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:** 3. **Auf Server kopieren nach:**
@@ -133,40 +104,28 @@ npm run dev
C:\inetpub\wwwroot\talas5\TileMap\ C:\inetpub\wwwroot\talas5\TileMap\
``` ```
5. **Konfiguration `.env.local` anpassen:** 5. **.env.production konfigurieren**
```env Die Datei `.env.production` enthält alle benötigten Verbindungs- und Betriebsvariablen wie z. B.
DB_HOST=localhost wenn die Datenbank auf dem selben Server ist Datenbank-Zugang, Pfade und Mock-Option.
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 ➡ Vollständige Anleitung & Beispieldatei:
``` [📄 docs/guide/env.md](docs/guide/env.md)
```env 6. **Dienst registrieren falls nicht vorhanden**
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 - Mit `nssm.exe` Windows-Dienst „nodeMapService“ erstellen
- Ziel: `StartNodeApp.bat` - 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 ```bash
npm start npm start in Terminal für Debugging
``` ```
oder Dienst starten
8. **Im Browser testen:** 8. **Im Browser testen:**
``` ```
http://<ip>/talas5/MessagesMap/mapTypC.aspx?m=IdMap&u=IdUser http://<ip>/talas5/MessagesMap/mapTypC.aspx?m=IdMap&u=IdUser
@@ -185,101 +144,9 @@ oder Dienst starten
### Empfohlener Ablauf für kleines Update: ### 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 2. Dienst oder `npm start` neu starten
3. Im Browser testen: `?m=...&u=...` 3. Im Browser testen: ` http://<ip>/talas5/MessagesMap/mapTypC.aspx?m=IdMap&u=IdUser`
---
### 🔧 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(...)
```
--- ---
@@ -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 ## 🏷 Versionierung
wird mit husky Bibliothek automatisch erhöht bei "git commit message" 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 ## 💾 Setup: Installationen & Tools
| Tool | Version | Link | | Tool | Version | Link |
@@ -387,7 +181,26 @@ dargestellt.
> - Die IP im Scriptteil von `MapTypC.aspx` ist aktuell (z. B. `10.10.0.13`) > - 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 > - `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: | Thema | Link |
[📄 docs/PROJECT_STRUCTURE.md](docs/PROJECT_STRUCTURE.md) | ------------------------- | ------------------------------------------------------- |
| 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
---

1
TODO.md
View File

@@ -9,6 +9,7 @@
## 🔧 Offene Aufgaben ## 🔧 Offene Aufgaben
- [ ] TODO: GMA auf 13er ist anders als in der Entwicklungsumgebung, Tooltip wird nicht angezeigt
- [ ] TODO: In editMode ohne Rechte kann noch die Linien Stützpunkte positioniert werden, es soll - [ ] TODO: In editMode ohne Rechte kann noch die Linien Stützpunkte positioniert werden, es soll
das nicht! das nicht!
- [ ] TODO: In editMode ohne Rechte kann noch den Bereich positioniert werden, es soll das nicht! - [ ] TODO: In editMode ohne Rechte kann noch den Bereich positioniert werden, es soll das nicht!

2
config/appVersion.js
View File

@@ -1,2 +1,2 @@
// /config/appVersion // /config/appVersion
export const APP_VERSION = "1.1.233"; export const APP_VERSION = "1.1.234";

94
docs/guide/dependencies.md Normal file
View File

@@ -0,0 +1,94 @@
<!-- /docs/guide/dependencies.md-->
# 📂 Abhängigkeiten in NodeMap (Stand: 2025)
Diese Datei listet alle Drittanbieter-Abhängigkeiten aus der Datei `package.json` mit einer kurzen
Erklärung, wofür sie im Projekt verwendet werden.
---
## ✨ Frameworks & Tooling
| Paket | Zweck & Beschreibung |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| **next** | Hauptframework (Next.js) zur Erstellung von React-basierten SSR/SSG-Apps. |
| **react** / **react-dom** | Grundlage für UI-Komponenten im Projekt. |
| **tailwindcss** / **postcss** / **autoprefixer** | Styling mit Tailwind. PostCSS verarbeitet CSS, Autoprefixer fügt vendor-spezifische Präfixe hinzu. |
| **dotenv** | Ermöglicht das Einlesen von `.env`-Dateien zur Laufzeit auf dem Server. |
---
## 🌐 Leaflet & Karten
| Paket | Zweck & Beschreibung |
| ----------------------------------------- | ------------------------------------------------------------ |
| **leaflet** | Basiskartenbibliothek zur Darstellung interaktiver Karten. |
| **leaflet-contextmenu** | Kontextmenüs per Rechtsklick in Leaflet. |
| **leaflet-control-geocoder** | Steuerelement für Suche/Geokodierung in Karten. |
| **leaflet.smooth_marker_bouncing** | Animation für Marker-Bounces (visuelles Feedback). |
| **overlapping-marker-spiderfier-leaflet** | Marker-Overlapping-Management mit Spiderfy-Effekt bei Klick. |
---
## 🪄 Zustand & Redux
| Paket | Zweck & Beschreibung |
| --------------------------- | ----------------------------------------------------- |
| **@reduxjs/toolkit** | Vereinfachte Redux-Nutzung mit Slices & Thunks. |
| **redux** / **react-redux** | Core-State-Management in React-Komponenten. |
| **redux-thunk** | Middleware zur Verarbeitung von asynchronen Aktionen. |
---
## 🦜 UI & Styling
| Paket | Zweck & Beschreibung |
| --------------------------------------- | --------------------------------------------------- |
| **@mui/icons-material** | UI-Icons aus der Material UI Sammlung. |
| **@emotion/react**, **@emotion/styled** | Styled Components-Engine, benötigt für MUI Styling. |
| **@heroicons/react** | React-Icons im Hero-Stil für UI. |
| **react-select** | Erweiterte Dropdown-Komponente mit Suchfunktion. |
| **react-toastify** | Benachrichtigungs-Tool für Toast-Meldungen. |
---
## 📁 Daten & Kommunikation
| Paket | Zweck & Beschreibung |
| -------------------------------- | --------------------------------------------------------- |
| **axios** | HTTP-Client zur API-Kommunikation (z. B. zu Webservices). |
| **cookies** | Zugriff & Verwaltung von Cookies auf Server/Client. |
| **ws** | WebSocket-Kommunikation mit z. B. GMA-Live-Daten. |
| **xml2js** / **fast-xml-parser** | Parsen von XML-Antworten aus Webservices. |
| **mysql** / **mysql2** | Zugriff auf MySQL-Datenbanken. |
---
## 🚫 Sicherheit & Netzwerk
| Paket | Zweck & Beschreibung |
| ------------------------- | --------------------------------------------------------- |
| **http-proxy-middleware** | API-Routing & Proxy-Zugriff z. B. für lokale Entwicklung. |
| **nextjs-cors** | CORS-Konfiguration für Next.js API-Routen. |
---
## 🎓 Entwicklung & Test (nur devDependencies)
| Paket | Zweck & Beschreibung |
| ----------------------------------------------------------------- | ------------------------------------------- |
| **cypress** | End-to-End-Testing. |
| **jest-environment-jsdom** / **jest-fetch-mock** / **jest-junit** | Unit- & Integrationstests. |
| **identity-obj-proxy** | Mocking für CSS-Module im Jest-Testkontext. |
| **node-fetch**, **node-mocks-http** | HTTP-Mocks für Tests. |
| **husky** | Git-Hook-Management (Pre-Commit etc.). |
| **raw-loader** | Import von Rohdaten (z. B. SVG) in Webpack. |
---
## 📄 Weitere Tools & Hilfen
| Paket | Zweck & Beschreibung |
| ---------------- | ------------------------------------------------- |
| **prepare** | Wird durch Husky benötigt zum Setup von Hooks. |
| **bump-version** | Interner Versionsbump-Script für `appVersion.js`. |

39
docs/guide/env.md Normal file
View File

@@ -0,0 +1,39 @@
<!-- /docs/guide/env.md-->
# 🌐 Umgebungsvariablen (`.env.local` / `.env.production`)
NodeMap verwendet Umgebungsvariablen zur Steuerung von API-Verhalten, Serverpfaden und Moduswahl
(Mock oder Produktion).
## 📂 Speicherort
- **Lokal**: `.env.local` (für Entwicklung)
- **Produktion**: `.env.production` (für `npm run build` & `npm start`)
## 🔧 Wichtige Variablen
| Variable | Beispielwert | Beschreibung |
| --------------------------- | ------------------- | --------------------------------------------------------------------- |
| `DB_HOST` | `localhost` | Adresse des Datenbankservers (MySQL) |
| `DB_PORT` | `3306` | Port für die Datenbankverbindung |
| `DB_NAME` | `talas` | Datenbankname |
| `DB_USER` | `root` | Benutzername für MySQL |
| `DB_PASSWORD` | `geheim` | Passwort für MySQL |
| `NEXT_PUBLIC_API_PORT_MODE` | `prod` oder `dev` | Steuert API-Routing bei Services (z. B. Portwechsel für lokal) |
| `NEXT_PUBLIC_USE_MOCKS` | `true` oder `false` | Aktiviert den Mockdaten-Modus über `/api/mocks/...` |
| `NEXT_PUBLIC_BASE_PATH` | `/talas5` oder leer | Optionaler Pfad, falls App unter Subpfad läuft (z. B. IIS) |
| `NEXT_PUBLIC_DEBUG` | `true` oder `false` | Aktiviert zusätzliche `console.log` Ausgaben für Debugging im Browser |
## 📦 Beispiel `.env.production`
```env
DB_HOST=localhost
DB_PORT=3306
DB_NAME=talas
DB_USER=root
DB_PASSWORD=geheim
NEXT_PUBLIC_API_PORT_MODE=prod
NEXT_PUBLIC_USE_MOCKS=false
NEXT_PUBLIC_BASE_PATH=/talas5
NEXT_PUBLIC_DEBUG=false
```

72
docs/guide/mock-data.md Normal file
View File

@@ -0,0 +1,72 @@
# 🧪 Mockdaten-Modus (`NEXT_PUBLIC_USE_MOCKS=true`)
Dieses Projekt unterstützt einen optionalen **Mockdaten-Modus**, um Entwicklung und Tests ohne
Backend/Webservice durchzuführen.
---
## 🔍 Zweck & Nutzen
- Schneller Entwicklungsstart ohne aktive Serververbindung
- Stabilere Testszenarien mit festen JSON-Daten
- Vollständige Isolation von Backend-Fehlern während der UI-Entwicklung
---
## ⚙️ Aktivierung
Mockdaten werden aktiviert durch folgende Umgebungsvariable:
```env
NEXT_PUBLIC_USE_MOCKS=true
```
Diese Variable wird in `.env.local` gesetzt und **nicht** für die Produktionsumgebung verwendet.
Im Produktivbetrieb steht:
```env
NEXT_PUBLIC_USE_MOCKS=false
```
---
## 🧩 Funktionsweise
Wenn `NEXT_PUBLIC_USE_MOCKS=true` gesetzt ist:
- Statt realer Webservices werden Endpunkte unter `/pages/api/mocks/webservice/*.js` aufgerufen
- Diese geben vorbereitete JSON-Dateien unter `/mockData/*.json` zurück
---
## 📂 Beispiel-Aufruf im Mockmodus
```ts
// Beispiel aus fetchGisSystemStaticService.js
const url = useMocks
? "/api/mocks/webservice/GisSystemStatic"
: `${apiUrl}/WebServiceMap.asmx/GisSystemStatic`;
```
---
## 🛡️ Sicherheit & Versionskontrolle
- Alle `.json`-Dateien im Ordner `/mockData/` sind über `.gitignore` vom Repository ausgeschlossen
- So wird verhindert, dass versehentlich sensible Testdaten veröffentlicht werden
---
## 💡 Hinweise
- Mockdaten sollen nur die wichtigsten API-Schnittstellen simulieren
- Bei Änderungen am Datenmodell sollten auch die Mockdaten aktualisiert werden
- Eine zentrale Thunk- & Service-Logik entscheidet automatisch, ob `mock` oder `real`
---
## 🔗 Weitere Informationen
- [📄 Umgebungsvariablen](env.md)
- [📄 Webservices im Detail](webservices.md)
- [📄 Zustandverwaltung (Redux)](redux-zustand.md)

0
docs/PROJECT_STRUCTURE.md → docs/guide/project-structure.md
View File

18
docs/guide/redux-zustand.md Normal file
View File

@@ -0,0 +1,18 @@
<!-- /docs/guide/redux-zustand.md-->
## 🧠 Zustand: Redux
Die Anwendung verwendet vollständig **Redux Toolkit** für die globale Zustandverwaltung.
- 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 :
- 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!

15
docs/guide/user-guide.md Normal file
View File

@@ -0,0 +1,15 @@
<!-- /docs/quide/user-guide.md -->
## 🧭 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)“

34
docs/guide/webservices.md Normal file
View File

@@ -0,0 +1,34 @@
## 📡 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.production` 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 in der Karte dargestellt.
➡ Damit alles funktioniert, müssen:
- der IIS laufen
- der `WebServiceMap.asmx` erreichbar sein