diff --git a/.env.local b/.env.local index 8ba22df24..1ae3ed34f 100644 --- a/.env.local +++ b/.env.local @@ -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 -NEXT_PUBLIC_API_PORT_MODE=dev -NEXT_PUBLIC_USE_MOCKS=true +NEXT_PUBLIC_API_PORT_MODE=prod +NEXT_PUBLIC_USE_MOCKS=false # 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/). diff --git a/README.md b/README.md index 6c93d5c34..ee3b8b8a8 100644 --- a/README.md +++ b/README.md @@ -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:///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:///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:///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-` 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:///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 + +--- diff --git a/TODO.md b/TODO.md index 2de7e940f..5d6e88719 100644 --- a/TODO.md +++ b/TODO.md @@ -9,6 +9,7 @@ ## 🔧 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 das nicht! - [ ] TODO: In editMode ohne Rechte kann noch den Bereich positioniert werden, es soll das nicht! diff --git a/config/appVersion.js b/config/appVersion.js index 707d52729..fe30128f9 100644 --- a/config/appVersion.js +++ b/config/appVersion.js @@ -1,2 +1,2 @@ // /config/appVersion -export const APP_VERSION = "1.1.233"; +export const APP_VERSION = "1.1.234"; diff --git a/docs/guide/dependencies.md b/docs/guide/dependencies.md new file mode 100644 index 000000000..da54205ec --- /dev/null +++ b/docs/guide/dependencies.md @@ -0,0 +1,94 @@ + + +# 📂 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`. | diff --git a/docs/guide/env.md b/docs/guide/env.md new file mode 100644 index 000000000..ef644da44 --- /dev/null +++ b/docs/guide/env.md @@ -0,0 +1,39 @@ + + +# 🌐 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 +``` diff --git a/docs/guide/mock-data.md b/docs/guide/mock-data.md new file mode 100644 index 000000000..250f618b1 --- /dev/null +++ b/docs/guide/mock-data.md @@ -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) diff --git a/docs/PROJECT_STRUCTURE.md b/docs/guide/project-structure.md similarity index 100% rename from docs/PROJECT_STRUCTURE.md rename to docs/guide/project-structure.md diff --git a/docs/guide/redux-zustand.md b/docs/guide/redux-zustand.md new file mode 100644 index 000000000..4f584bed5 --- /dev/null +++ b/docs/guide/redux-zustand.md @@ -0,0 +1,18 @@ + + +## 🧠 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-` 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! diff --git a/docs/guide/user-guide.md b/docs/guide/user-guide.md new file mode 100644 index 000000000..74cff1dfa --- /dev/null +++ b/docs/guide/user-guide.md @@ -0,0 +1,15 @@ + + +## 🧭 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)“ diff --git a/docs/guide/webservices.md b/docs/guide/webservices.md new file mode 100644 index 000000000..825b65d75 --- /dev/null +++ b/docs/guide/webservices.md @@ -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