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

docs

Browse Source
This commit is contained in:
Ismail Ali
2025-05-27 19:41:17 +02:00
parent 257341475c
commit 97fbb6fdc1
86 changed files with 1452 additions and 1185 deletions
Download Patch File Download Diff File Expand all files Collapse all files

123
docs/components/DataSheet.md
View File

@@ -1,123 +0,0 @@
# Komponenten-Dokumentation: `DataSheet.js`
## Zweck
Die Komponente `DataSheet` dient als Kontrollzentrale für die interaktive Kartenanwendung. Sie bietet Funktionen für:
- Auswahl von Bereichen ("Stationen") aus einem Dropdown-Menü
- Steuerung der Sichtbarkeit von Layern wie POIs und Polyline (z. B. Kabelstrecken)
- Aktivierung des Editiermodus
- Steuerung von Layer-Zuständen über Redux und Recoil
---
## Position im UI
Die Komponente wird als Floating-Panel oben rechts auf der Karte angezeigt. Sie hat eine feste Breite (min/max) und ist als "Sidebar-Lightbox" implementiert.
---
## Abhängigkeiten
### Redux
- `gisStationsStaticDistrictSlice`
- `gisSystemStaticSlice`
- `mapLayersSlice`
- `polylineLayerVisibleSlice`
- `gisStationsStaticSlice`
* `poiLayerVisibleSlice`
* `zoomTriggerSlice`
* `selectedAreaSlice`
### Hooks
- `useInitGisStationsStatic()`
---
## Funktionalität im Überblick
### 1. **Bereiche Dropdown**
- Gefüllt aus `GisStationsStatic.Points`
- Wird aktualisiert, wenn sich die Redux-Daten ändern
- Bei Auswahl wird `selectedAreaState` aktualisiert
### 2. **Systemlayer-Checkboxen**
- Daten kommen aus `GisSystemStatic`
- Jeder Eintrag hat `Name` und einen intern generierten `key`
- Sichtbarkeit wird über `mapLayersState` verwaltet
- Zustand wird in `localStorage` gespeichert
### 3. **TALAS-Untermenu**
- Bei Systemname "TALAS" wird eine Untergruppe angezeigt:
- Checkbox für Polyline (Kabelstrecken)
- Sichtbarkeit auch in `localStorage`
### 4. **POI-Checkbox**
- Redux-Slice `poiLayerVisibleSlice`
- Sichtbarkeit von POI-Layern auf der Karte
### 5. **EditModeToggle**
- Eine separate Komponente
- Aktiviert/Deaktiviert den Bearbeitungsmodus (z. B. für Kontextmenü-Einträge)
- Bei aktivem EditMode sind Checkboxen deaktiviert
---
## Lokale Speicherwerte (localStorage)
Folgende Werte werden zwischen Sitzungen gespeichert:
| Key | Zweck |
| --------------------- | ---------------------------------- |
| `poiVisible` | Sichtbarkeit POI-Layer |
| `polylineVisible` | Sichtbarkeit Kabelstrecken |
| `mapLayersVisibility` | Sichtbarkeitsstatus für alle Layer |
| `editMode` | Status des Bearbeitungsmodus |
---
## Bekannte Besonderheiten
- **Fallbacks** für Redux-Selector: z. B. `|| []` bei leeren Listen
- **Fehlerprüfung** für `GisStationsStatic.Points` im useEffect
- **Doppelte Initialisierung von stationListing** (einmal aus `Points`, einmal aus `District`)
---
## Voraussetzungen für korrekte Funktion
- API-Endpunkt `/GisStationsStatic?idMap=...` muss korrekte Struktur liefern: `{ Points: [...] }`
- Redux Store muss korrekt initialisiert sein
- Hook `useInitGisStationsStatic` muss beim Mount ausgeführt werden
---
## Weiterführende Dateien
- `/hooks/useMapComponentState.js`
- `/components/EditModeToggle.js`
- Redux-Slices unter `/redux/slices/`
---
## Speicherort für Dokumentation
Empfohlenes Ziel: `/docs/DataSheet.md`
---
---
## Hinweis zur Umstellung
Diese Komponente wurde ursprünglich mit Recoil entwickelt.
Seit Version `1.1.96` ist der Zustand vollständig auf **Redux Toolkit** umgestellt.
Die Recoil-Atoms wurden entfernt und durch Redux-Slices ersetzt.

60
docs/components/MapComponent.md
View File

@@ -1,60 +0,0 @@
# 🗺️ MapComponent – Webservice-Parameter
## 🔄 URL-Parameter vom Aufrufer (z. B. TALAS.web)
Die Anwendung wird mit Kurzparametern aufgerufen:
```
http://[SERVER]:3000/?m=12&u=484
```
| Parameter | Bedeutung |
| --------- | -------------------------- |
| `m` | Map-ID (intern: `idMap`) |
| `u` | User-ID (intern: `idUser`) |
Diese Parameter werden im Code wie folgt gelesen:
```js
const params = new URLSearchParams(window.location.search);
const idMap = params.get("m");
const idUser = params.get("u");
```
---
## 🔁 Webservice-Proxy intern
Die Next.js API-Routen übernehmen die Umwandlung zu den Webservices:
```js
// Beispiel: /pages/api/gisSystemStatic.js
const targetUrl = `http://.../WebServiceMap.asmx/GisSystemStatic?idMap=${idMap}&idUser=${idUser}`;
```
➡ Die Konvertierung `m → idMap` und `u → idUser` erfolgt **nur im Backend (API-Routen)**
---
## 🧠 Hinweis für Entwickler
- `m` und `u` **immer** aus der URL im Client lesen
- Niemals `idMap` oder `idUser` direkt im Frontend erwarten
- Alle Webservice-Zugriffe im Frontend laufen über interne API-Routen `/api/...`
- Beispiel-Aufruf:
```js
fetch(`/api/gisSystemStatic?m=${idMap}&u=${idUser}`);
```
---
## 🌐 Beispiele aus der Praxis
| Umgebung | URL-Aufruf-Beispiel |
| --------------------- | ------------------------------------------------------------- |
| Entwicklungs-PC | http://10.10.0.70:3000/?m=12&u=484 |
| Test-Server via TALAS | http://10.10.0.13/talas5/MessagesMap/mapTypeC.aspx?m=12&u=484 |
---
Diese Konvention ist essenziell für einheitliche Übergabe und Backend-Kompatibilität.

44
docs/components/TestScript.md
View File

@@ -0,0 +1,44 @@
<!-- /docs/components/TestScript.md -->
# 🧪 TestScript.js
Ein einfaches React-Testskript zur Laufzeitüberprüfung von Codefragmenten in `setupPolylines.js`.
## Zweck
Dieses Skript durchsucht die geladene `setupPolylines.js`-Datei (per `raw-loader`) nach bestimmten Kontextmenüeinträgen:
- „Stützpunkt entfernen“
- „Stützpunkt hinzufügen“
## Vorgehen
- Lädt `setupPolylines.js` als Text via `!!raw-loader!`
- Nutzt reguläre Ausdrücke zur Prüfung
- Gibt Ergebnisse farblich formatiert in der Konsole aus
## Ausgaben
| Zustand | Beschreibung |
|-------------|-----------------------------------------------------|
| ✅ Test bestanden | Der gesuchte Text wurde gefunden |
| ❌ Test fehlgeschlagen | Der gesuchte Text fehlt in der Datei |
| ℹ️ Info | Neutrale Zusatzinformationen in der Konsole |
## Besonderheiten
- Kein visuelles UI – Rückmeldung nur über `console.log`
- Eignet sich als Dev-Hilfe für Refactoring oder PR-Checks
## Beispielausgabe
```plaintext
✔ Test bestanden: Der Text für 'Stützpunkt entfernen' wurde gefunden.
ℹ️ Info: Überprüfung abgeschlossen.
```
## Hinweise
- Wird automatisch beim Mount (via `useEffect`) ausgeführt
- `return null` → keine sichtbare Ausgabe

31
docs/components/contextmenu/CoordinatePopup.md Normal file
View File

@@ -0,0 +1,31 @@
<!-- /docs/components/contextmenu/CoordinatePopup.md -->
# 📌 CoordinatePopup.js
Zeigt ein modales Fenster mit Koordinateninformationen an, z. B. aus einem Kontextmenü heraus.
## Features
- Darstellung eines Koordinatenwerts (`lat,lng`)
- Kopieren in die Zwischenablage (Clipboard API + Fallback)
- Modal zentriert mit Tailwind CSS
- Zwei Buttons: „Kopieren“ und „Schließen“
## Props
| Name | Typ | Beschreibung |
|-------------|-----------|------------------------------------|
| `isOpen` | `boolean` | Steuert Sichtbarkeit des Modals |
| `coordinates` | `string` | Zu zeigende Koordinaten (z. B. `"53.2,8.1"`) |
| `onClose` | `function` | Wird bei Klick auf „Schließen“ ausgelöst |
## Design
- Tailwind-Klassen für zentriertes Layout (`fixed`, `inset-0`, `z-50`)
- Leicht animierter Button-Hover
## Interne Logik
- Nutzt `navigator.clipboard.writeText` oder Fallback mit `document.execCommand("copy")`
- Stoppt Event-Bubbling, um Klick außerhalb zu erkennen

36
docs/components/contextmenu/useMapContextMenu.md Normal file
View File

@@ -0,0 +1,36 @@
<!-- /docs/components/contextmenu/useMapContextMenu.md -->
# 🖱️ useMapContextMenu.js
Initialisiert Kontextmenüeinträge für die Leaflet-Karte.
Wird typischerweise in `initializeMap()` oder `MapComponent` verwendet.
## Kontextmenüeinträge
| Eintrag | Funktion |
|---------------------|------------------------------------------------|
| Koordinaten anzeigen | Öffnet `CoordinatePopup` mit aktueller Position |
| Reinzoomen | Zoomt 3 Stufen näher an das Zentrum heran |
| Rauszoomen | Zoomt 3 Stufen heraus |
| Hier zentrieren | Verschiebt Kartenzentrum auf Klickposition |
| POI hinzufügen | (nur bei `editMode=true`) öffnet POI-Dialog |
## Parameter
```js
addItemsToMapContextMenu(
map,
menuItemAdded,
setMenuItemAdded,
setShowCoordinatesModal,
setShowPoiModal,
setPopupCoordinates,
openPopupWithCoordinates
)
```
## Besonderheiten
- Prüft auf `localStorage.editMode` für POI-Eintrag
- FlyTo-Animationen für Zoom-Vorgänge mit dynamischer Dauer
- Modularer Aufbau: `openPopupWithCoordinates` wird extern übergeben

34
docs/components/gisPolylines/PolylineContextMenu.md Normal file
View File

@@ -0,0 +1,34 @@
<!-- /docs/components/gisPolylines/PolylineContextMenu.md -->
# 📐 PolylineContextMenu.js
Ein einfaches benutzerdefiniertes Kontextmenü zur Interaktion mit Linien (Polylinien) auf der Karte.
## Zweck
Das Menü erlaubt folgende Interaktionen:
- ➕ „Stützpunkt hinzufügen“
- ➖ „Stützpunkt entfernen“
- ❌ „Schließen“
Wird dynamisch positioniert anhand der Klickkoordinaten (`position.x`, `position.y`).
## Props
| Prop | Typ | Beschreibung |
|---------------|-----------|----------------------------------------------------|
| `position` | `{x, y}` | Position in Pixelkoordinaten (z. B. von Mausereignis) |
| `onAddPoint` | `function`| Handler für „Stützpunkt hinzufügen“ |
| `onRemovePoint` | `function` | Handler für „Stützpunkt entfernen“ |
| `onClose` | `function`| Handler zum Schließen des Menüs |
## Styling
- Absolut positioniertes `div`
- Weißer Hintergrund, schwarzer Rahmen
- Kein Tailwind – purer Inline-Style
## Verwendung
Eingebettet z. B. in `setupPolylines.js` oder `PolylineLayerManager`, um rechte Mausklicks auf Linien zu behandeln.

16
docs/components/gisPolylines/icons/CircleIcon.md Normal file
View File

@@ -0,0 +1,16 @@
<!-- /docs/components/gisPolylines/icons/CircleIcon.md -->
# 🔘 CircleIcon.js
Ein einfacher, grauer runder Marker als Stützpunkt in einer Polyline.
## Eigenschaften
- Stil: grauer Kreis mit schwarzem Rand
- Größe: 10×10 px, IconSize 25×25 px (wegen Klickfläche)
- Klasse: `custom-circle-icon`
## Verwendung
Wird in Polylinien als Zwischenpunkt gesetzt. Inaktiv, aber sichtbar.

15
docs/components/gisPolylines/icons/EndIcon.md Normal file
View File

@@ -0,0 +1,15 @@
<!-- /docs/components/gisPolylines/icons/EndIcon.md -->
# 🔲 EndIcon.js
Ein Viereck zur Markierung des Endpunkts einer Polyline.
## Eigenschaften
- Stil: graues Quadrat mit schwarzem Rand
- Größe: 14×14 px
- Klasse: `custom-end-icon`
## Verwendung
Wird am letzten Punkt einer Linie gesetzt, z. B. `lineData.coordinates[line.length - 1]`

15
docs/components/gisPolylines/icons/StartIcon.md Normal file
View File

@@ -0,0 +1,15 @@
<!-- /docs/components/gisPolylines/icons/StartIcon.md -->
# 🔺 StartIcon.js
Ein SVG-Dreieck zur Markierung des Startpunkts einer Polyline.
## Eigenschaften
- Schwarzes Dreieck mit grauem Overlay (Polygon SVG)
- Größe: 18×18 px
- Klasse: `custom-start-icon`
## Verwendung
Wird am ersten Punkt einer Polyline platziert.

20
docs/components/gisPolylines/icons/SupportPointIcons.md Normal file
View File

@@ -0,0 +1,20 @@
<!-- /docs/components/gisPolylines/icons/SupportPointIcons.md -->
# ➕➖ SupportPointIcons.js
Definiert zwei Icons für interaktive Stützpunkte in einer Polyline:
## AddSupportPointIcon
- Grüner Kreis mit weißem Rand und Pluszeichen
- `iconSize`: 24×24 px
## RemoveSupportPointIcon
- Roter Kreis mit weißem Rand und Minuszeichen
- `iconSize`: 24×24 px
## Verwendung
- Hinzufügen/Entfernen von Zwischenpunkten in der Bearbeitungsansicht (editMode)
- Marker erscheinen z. B. bei Maus-Hover oder per Kontextmenü

26
docs/components/icons/devices/overlapping/PlusRoundIcon.md Normal file
View File

@@ -0,0 +1,26 @@
<!-- /docs/components/icons/devices/overlapping/PlusRoundIcon.md -->
# ➕ PlusRoundIcon.js
Ein einfaches Leaflet-Icon, das ein rundes Pluszeichen darstellt.
Wird für zusätzliche UI-Markierungen auf Geräten oder überlappenden Icons verwendet.
## Eigenschaften
| Attribut | Wert |
|--------------|--------------------|
| `iconUrl` | `/img/plus_round.png` |
| `iconSize` | `[22, 22]` |
| `iconAnchor` | `[25, 55]` |
| `className` | `absolute top-0 left-0 z-10` (Tailwind)
## Verwendung
- Dient als Overlay-Symbol, z. B. für „Gerät hinzufügen“ oder zur Darstellung über bestehenden Icons
- Durch die `z-10`-Klasse immer im Vordergrund sichtbar
- Kombinierbar mit OverlappingMarkerSpiderfier oder Marker-Gruppen
## Hinweis
- Die Bilddatei `/img/plus_round.png` muss vorhanden sein
- Kann bei Bedarf dynamisch durch ein anderes Icon ersetzt werden

71
docs/components/mainComponent/MapComponent.md Normal file
View File

@@ -0,0 +1,71 @@
<!-- /docs/components/mainComponent/MapComponent.md -->
# 🗺️ MapComponent.js
Die zentrale React-Komponente zur Darstellung und Steuerung der Leaflet-Karte.
Bindet alle Marker, Layer, POIs, Linien und das Kontextmenü dynamisch ein.
---
## 🎯 Zweck
- Initialisiert die Leaflet-Karte (`useInitializeMap`)
- Bindet Marker & Polylinien über Redux und eigene Hooks
- Steuerung über Redux-Slices wie `selectedArea`, `zoomTrigger`, `polylineVisible`
- Kontextmenüs für Karte, POIs, Polylinien
- Unterstützung für Editierfunktionen über `editMode` (localStorage)
---
## 🧱 Hauptbestandteile
- `useEffect`-Hooks zum Laden und Aktualisieren von:
- Kartenlayern, POIs, Linien, Rechte, Systeme, Positionen
- Marker-Logik für 15+ Layergruppen (TALAS, ECI, GMA, etc.)
- Marker-Overlapping mit `OverlappingMarkerSpiderfier`
- Kontextmenüs (Karte & Polylinie)
- UI-Komponenten:
- `MapLayersControlPanel`
- `CoordinateInput`
- `CoordinatePopup`
- `AddPOIModal`, `PoiUpdateModal`, `VersionInfoModal`
---
## 🧠 Zustand & Redux
Verwendet umfangreiche Redux-Slices zur Steuerung von:
- Linienstatus, POI-Typen, POI-Icons
- Gerätesysteme & Rechte
- Sichtbarkeit einzelner Layergruppen
- Aktuelle Selektion (Area, Gerät, POI)
---
## 🔧 Lokale Steuerung
- EditMode wird aus `localStorage` gelesen
- Karte speichert Zoom & Center dauerhaft im Browser
- Kontextmenü-Einträge ändern sich je nach Rechten & Modus
---
## 🧪 Besonderheiten
- Fehlerbehandlung für `contextmenu`-Fehler eingebaut → Auto-Neuladen
- Alle Marker-Updates mit Overlapping-Check & Z-Index-Steuerung
- Linien enthalten dynamische Tooltips mit `tooltipContents`
- Initiale Datenabfrage über Redux-Thunk-Kaskade
---
## 🔗 Abhängigkeiten
- Leaflet, OverlappingMarkerSpiderfier, React-Toastify
- Redux Toolkit (Thunks + Selectors)
- Tailwind CSS für visuelles Layout
---
📄 Pfad: `/components/mainComponent/MapComponent.js`

53
docs/components/mainComponent/hooks/useInitializeMap.md Normal file
View File

@@ -0,0 +1,53 @@
<!-- /docs/components/mainComponent/hooks/useInitializeMap.md -->
# 🪄 useInitializeMap.js
Custom React-Hook zur Initialisierung der Leaflet-Karte.
Ermöglicht die einfache Übergabe aller nötigen Parameter und abstrahiert die `initializeMap(...)`-Logik.
---
## 📦 Zweck
- Führt `initializeMap(...)` nur **einmal** aus, wenn `mapRef` existiert und `map === null`
- Kapselt die Initialisierung in ein `useEffect`
---
## 🔧 Parameter
| Name | Typ | Beschreibung |
|--------------------------|------------|---------------------------------------------------|
| `map` | `LeafletMap` (Zustand) | Wird initialisiert, wenn `null` |
| `mapRef` | `ref` | Referenz auf `<div id="map">` |
| `setMap` | `function` | Callback zum Setzen der Karteninstanz |
| `setOms` | `function` | Callback für OverlappingMarkerSpiderfier |
| `setMenuItemAdded` | `function` | Wird genutzt, um mehrfaches Menü-Setup zu verhindern |
| `addItemsToMapContextMenu` | `function` | Logik zum Hinzufügen von Kontextmenüeinträgen |
| `hasRights` | `boolean` | Steuerung, ob POI-Menüs angezeigt werden dürfen |
| `setPolylineEventsDisabled` | `function` | Aktiviert/Deaktiviert Polyline-Events global |
---
## 🌐 Verwendung
In `MapComponent.js`:
```js
useInitializeMap(
map,
mapRef,
setMap,
setOms,
setMenuItemAdded,
addItemsToMapContextMenu,
hasRights,
(value) => dispatch(setDisabled(value))
);
```
---
## 📁 Quelle
Wrappt `initializeMap()` aus `/utils/initializeMap.js`

28
docs/components/pois/AddPOIModal.md Normal file
View File

@@ -0,0 +1,28 @@
<!-- /docs/components/pois/AddPOIModal.md -->
# ➕ AddPOIModal.js
Zeigt ein modales Formular an, um einen neuen POI auf der Karte zu erstellen.
Die Koordinaten (`latlng`) werden automatisch übernommen.
## Funktionen
- POI-Name, Typ und zugehöriges Gerät auswählbar
- Koordinatenanzeige (`lat`, `lng`)
- Dynamisches Laden der Gerätedaten und POI-Typen
- Fehleranzeige bei fehlgeschlagenem Speichern
- Löst `addPoiThunk` + Refresh-Trigger (`incrementTrigger`) aus
## Props
| Prop | Typ | Beschreibung |
|----------|-----------|--------------------------------------------------|
| `onClose` | `function` | Schließt das Modal |
| `map` | `Leaflet` | (optional) zum Schließen evtl. offener Popups |
| `latlng` | `object` | Koordinaten für den neuen POI |
## Redux
- `fetchPoiTypThunk`, `fetchPoiIconsDataThunk`
- `addPoiThunk`, `resetAddPoiStatus`

29
docs/components/pois/PoiUpdateModal.md Normal file
View File

@@ -0,0 +1,29 @@
<!-- /docs/components/pois/PoiUpdateModal.md -->
# ✏️ PoiUpdateModal.js
Ein Dialog zur Aktualisierung oder Löschung bestehender POIs.
## Features
- Zeigt aktuellen Namen, Beschreibung, Gerät und Typ
- Gerät und Typ auswählbar via `react-select`
- Unterstützt Löschen und Speichern von POIs
- Eingebundene Sicherheitsabfrage bei Löschen
## Props
| Prop | Typ | Beschreibung |
|------------|-----------|---------------------------------------|
| `onClose` | `function`| Schließt das Modal |
| `poiData` | `object` | Bestehende POI-Daten zur Bearbeitung |
## Redux
- `updatePoiThunk`, `deletePoiThunk`
- `fetchLocationDevicesThunk`, `fetchPoiTypThunk`
## Technisches
- Dynamische Gerätegruppenfilterung basierend auf `mapLayersVisibility`
- Formfelder mit `react-select` für bessere UX