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

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)

136
docs/guide/project-structure.md Normal file
View File

@@ -0,0 +1,136 @@
## 🧱 Projektstruktur
```bash
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/ → Bilder, Icons, mapTiles sind nicht im nodeMap Projekt Verzeichnis sondern in TALAS Verzeichnis
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
```

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