From 4a7328167c4411ab2f75488b5a43aebd64d1c10f Mon Sep 17 00:00:00 2001 From: ISA Date: Tue, 24 Jun 2025 06:58:56 +0200 Subject: [PATCH] docs: docs/README --- .env.development | 2 +- .env.production | 2 +- README.md | 4 + docs/README.md | 228 +++++++++++++++------------------------------- package-lock.json | 4 +- package.json | 2 +- 6 files changed, 82 insertions(+), 160 deletions(-) diff --git a/.env.development b/.env.development index 6029e2543..c32e76c3d 100644 --- a/.env.development +++ b/.env.development @@ -25,4 +25,4 @@ NEXT_PUBLIC_USE_MOCKS=true NEXT_PUBLIC_BASE_PATH=/talas5 # Oder leer lassen für direkten Zugriff -> NEXT_PUBLIC_BASE_PATH= # App-Versionsnummer -NEXT_PUBLIC_APP_VERSION=1.1.281 +NEXT_PUBLIC_APP_VERSION=1.1.282 diff --git a/.env.production b/.env.production index 3ab865cd8..3b140df56 100644 --- a/.env.production +++ b/.env.production @@ -26,4 +26,4 @@ NEXT_PUBLIC_BASE_PATH=/talas5 # Oder leer lassen für direkten Zugriff -> NEXT_PUBLIC_BASE_PATH= # App-Versionsnummer -NEXT_PUBLIC_APP_VERSION=1.1.281 \ No newline at end of file +NEXT_PUBLIC_APP_VERSION=1.1.282 \ No newline at end of file diff --git a/README.md b/README.md index 9ec2d4dba..cad33f93e 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,10 @@ NodeMap ist eine modulare Kartenanwendung zur Visualisierung und Bearbeitung von GIS-Daten, POIs und Gerätestatus in einer interaktiven Leaflet-Karte. +> 📘 Für Entwickler: +> Die technische Dokumentation (Architektur, Redux, Komponenten, etc.) befindet sich in: +> [`/docs/README.md`](docs/README.md) + ## 🌍 Live-Vorschau der Karte ![Startansicht der NodeMap Karte](docs/screenshots/overview1.png) diff --git a/docs/README.md b/docs/README.md index 6bd36d755..8133ea575 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,21 +1,32 @@ -# 🚀 NodeMap – Einstieg für Entwickler +# 📘 NodeMap – Entwicklerdokumentation -NodeMap ist eine modulare Kartenanwendung zur Visualisierung und Bearbeitung von GIS-Daten, POIs und -Gerätestatus in einer interaktiven Leaflet-Karte. +Willkommen in der Entwicklerdokumentation für **NodeMap** – einer modularen Kartenanwendung zur +Visualisierung und Bearbeitung von GIS-Daten, POIs und Gerätestatus in einer interaktiven +Leaflet-Karte. -## 🌍 Live-Vorschau der Karte - -![Startansicht der NodeMap Karte](http://10.10.0.12:3000/ISA/nodeMap/media/branch/main/docs/screenshots/overview1.png) +Diese Anleitung führt dich **Schritt für Schritt** durch die wichtigsten Bereiche für lokale +Entwicklung, Architekturverständnis und Erweiterung. --- -> 🖥 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) -> 🗄 Produktionsumgebung: TALAS.web und MySQL Server unter Windows Server +## 📚 Inhaltsverzeichnis + +- [📘 NodeMap – Entwicklerdokumentation](#-nodemap--entwicklerdokumentation) + - [📚 Inhaltsverzeichnis](#-inhaltsverzeichnis) + - [🔍 Projektüberblick](#-projektüberblick) + - [🧱 Projektstruktur \& Setup](#-projektstruktur--setup) + - [🔌 Webservices \& API-Fluss](#-webservices--api-fluss) + - [🧠 Zustandverwaltung (Redux)](#-zustandverwaltung-redux) + - [🧪 Entwicklung \& Testdaten](#-entwicklung--testdaten) + - [❗ Fehlerbehandlung \& Glossar](#-fehlerbehandlung--glossar) + - [🔄 Hinweis zum Deployment](#-hinweis-zum-deployment) --- -## Technologie-Stack +## 🔍 Projektüberblick + +NodeMap wird von **TALAS.web** über einen iFrame geladen. Die Anwendung verwendet moderne +Technologien wie: | Technologie | Zweck | | ------------- | ------------------------------ | @@ -26,179 +37,86 @@ Gerätestatus in einer interaktiven Leaflet-Karte. | MySQL | Datenbank | | Node.js / IIS | Server und Auslieferung | -## 🧭 Zielumgebung - -- Windows-Produktionsserver (offline, kein Internet) -- Kommunikation nur im lokalen Netzwerk -- Nutzerzugriff per VPN + Remote Desktop (RDP) -- Integration per iFrame in TALAS.web +➡ Mehr zur Architektur: [architecture.md](/docs/architecture.md) --- -## 🔄 Wie funktioniert das System? +## 🧱 Projektstruktur & Setup -Die Anwendung wird von TALAS.web im iFrame geladen. Die URL enthält Parameter für Map- und -User-ID. - NodeMap lädt anschließend Daten über WebServices und MySQL. - ➡ Details zur Architektur: [docs/architecture.md](docs/architecture.md) +🔧 **Zielsystem:** + +- Offline-Umgebung +- Windows-Server mit IIS +- Datenzugriff über Webservice oder lokale API + +🚀 **Lokale Entwicklung starten:** +➡ [Entwicklungssetup](guide/setup-dev.md) + +📁 **Verzeichnisstruktur verstehen:** +➡ [Projektstruktur erklärt](guide/project-structure.md) + +🛠️ **Abhängigkeiten & Tools:** +➡ [dependencies.md](guide/dependencies.md) + +🌐 **Umgebungsvariablen (env-Dateien):** +➡ [env.md](guide/env.md) --- -## 🧰 Erstinstallation auf Server +## 🔌 Webservices & API-Fluss -### Voraussetzungen +NodeMap greift auf zwei Datenquellen zu: -- Windows Server mit IIS -- Sicherstellen, dass alle TALAS.web API-Endpunkte(WebService) erreichbar sind -- Node.js & npm installiert (z. B. v18–20) -- MySQL (lokal oder erreichbar) -- Port 3000 freigegeben (Firewall) -- IIS-Datei `mapTypC.aspx` vorhanden in C:\inetpub\wwwroot\talas5\MessagesMap\ - (Server-IP mit Port 3000) -- Browser: Chrome ab Version 125.0.6420.142 empfohlen -- Karten Material vorhanden in: `C:\inetpub\wwwroot\talas5\TileMap\mapTiles` - ![mapTiles](docs/screenshots/mapTiles.png) +1. **TALAS-WebServices** (Port 80) – Gerätedaten, POIs, Rechte etc. +2. **Lokale Next.js API** (Port 3000) – eigene Datenbankabfragen via MySQL + +➡ [Webservices-Dokumentation](guide/webservices.md) --- -## 🔗 Integration in TALAS.web +## 🧠 Zustandverwaltung (Redux) -![iFrame-Integration](docs/screenshots/iframe-in-talas2.png) +Alle Karten- und Gerätefunktionen (z. B. Marker, Linien, POIs) sind über Redux-Slices und Thunks +organisiert: -- Die App wird in einem **iFrame** geladen -- Startet über `?m=X&u=Y` für Map-/User-ID -- Rechte und Inhalte werden automatisch geladen - ``` - z.B. - `http://10.10.0.13/talas5/MessagesMap/mapTypC.aspx?m=12&u=484` - ``` +- Datenfluss: `Service` → `Thunk` → `Slice` → `Komponente` +- Beispiel: POI-Daten, Gerätemarker, Rechteprüfung, Sichtbarkeiten + +➡ [Zustandverwaltung mit Redux](guide/redux-zustand.md) --- -## 🪛 Schritt-für-Schritt: NodeMap auf dem Server installieren +## 🧪 Entwicklung & Testdaten + +Um auch **ohne echte Datenquelle** arbeiten zu können: + +- ✔ Mockdaten-Modus über `.env.local` +- ✔ API-Antworten werden lokal simuliert +- ✔ Redux prüft, ob `process.env.NEXT_PUBLIC_USE_MOCKS === true` + +➡ [Mockdaten & Entwicklung](guide/mock-data.md) --- -1. **Projekt lokal klonen und kompilieren:** +## ❗ Fehlerbehandlung & Glossar - ```bash - git clone http://10.10.0.12:3000/ISA/nodeMap - cd nodeMap # zu den Verzeichnis wechseln - npm install # Abhängigkeiten installieren (lädt alle Pakete aus package.json) - npm run build # Erstellt ein optimiertes Produktions-Build im Ordner .next/ - ``` +Typische Probleme bei Installation, Deployment oder Datenzugriff: -2. **ZIP-Paket vorbereiten (lokal):** +➡ [FAQ & häufige Fehler](guide/faq.md) -- Verzeichnis `.next/` -- Verzeichnisse `public/`, `node_modules/` falls auf dem Server nicht vorhanden sind oder etwas - hinzugefügt wurde (Bilder oder Bibliothek) -- Dateien `.env.production`, `package.json` falls auf dem Server nicht vorhanden sind oder etwas - hinzugefügt wurde (Umgebungsvariablen oder Bibliothek) -- `nssm.exe`, `StartNodeApp.bat`, `Start-Dev.ps1` um Windows Dienst zu erstellen falls noch nicht - vorhanden ist Download: - [nssm](https://littwinsystemtechnik.sharepoint.com/:f:/r/sites/LittwinSystemtechnik/Freigegebene%20Dokumente/Projekte/Masterkarte%20V2%20setup%20files?csf=1&web=1&e=Sm1wwt) +Begriffe wie `POI`, `IdMap`, `Station`, `Layer`, `Slice` erklärt: -3. **Auf Server kopieren nach:** Ein Ordner temp auf dem Desktop erstellen->ZIP-Paket - einfügen->entpacken->Inhalt in folgende Verzeichnis einfügen - - ``` - C:\inetpub\wwwroot\talas5\nodeMap\ - ``` - -4. **Kartenmaterial hinzufügen (falls nicht vorhanden):** - - Muss noch in Download-Server eingefügt werden, damit eine zentrale Stelle verfügbar ist - - ``` - C:\inetpub\wwwroot\talas5\TileMap\ - ``` - -5. **.env.production konfigurieren** - - Die Datei `.env.production` enthält alle benötigten Verbindungs- und Betriebsvariablen wie z. B. - Datenbank-Zugang, Pfade und Mock-Option. - - ➡ Vollständige Anleitung & Beispieldatei: [.env.production](docs/guide/env.md) - -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) - -1. **Starten:** Dienst starten , falls vorhanden einmal beenden und neustarten - -2. **Im Browser testen:** - ``` - http:///talas5/MessagesMap/mapTypC.aspx?m=IdMap&u=IdUser - z.B. - http:///talas5/MessagesMap/mapTypC.aspx?m=12&u=484 - ``` +➡ [Glossar](guide/glossar.md) --- -## 🔁 Update-Richtlinien +## 🔄 Hinweis zum Deployment -| Art | Ersetzte Dateien | Bemerkung | -| ------------------ | ---------------------------------- | ---------------------------- | -| **Kleines Update** | `.next/` | `node_modules` nicht nötig | -| **Großes Update** | alle Dateien (wie Neuinstallation) | Dienst ggf. neu registrieren | - -### Empfohlener Ablauf für kleines Update: - -1. `.next/` Verzeichnis nach Kompilieren kopieren und auf dem Server einfügen -2. Dienst neu starten -3. Im Browser testen: ` http:///talas5/MessagesMap/mapTypC.aspx?m=IdMap&u=IdUser` +Für die Anleitung zur Installation auf dem Server → siehe +📦 [Root-README.md im Projektverzeichnis](../README.md) --- -## ✅ Tests & Qualitätssicherung - -- **E2E-Tests:** Cypress (nur in der Entwicklungsumgebung) -- **Unit-Tests:** Aktuell keine Jest-Tests aufgrund Leaflet-Komplexität -- **Empfehlung:** Manuelle Tests nach jedem Deployment durchführen (Checkliste vorbereiten) - ---- - -## 🏷 Versionierung - -wird mit husky Bibliothek automatisch erhöht bei "git commit message" - -→ Wird in der Fußzeile angezeigt. Die Version wird automatisch erhöht über ein Script -(`scripts/bumpVersion.js`), das per Husky vor jedem Commit ausgeführt wird. -Die Version steht sowohl in `package.json` als auch in `config/appVersion.js`. - ---- - -## 💾 Setup: Installationen & Tools - -| Tool | Version | Link | -| -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Node.js | 20.12.1 | [nodejs](https://littwinsystemtechnik.sharepoint.com/:f:/r/sites/LittwinSystemtechnik/Freigegebene%20Dokumente/Projekte/Masterkarte%20V2%20setup%20files?csf=1&web=1&e=Sm1wwt) | -| Chrome | optional | [Chrome](https://littwinsystemtechnik.sharepoint.com/:f:/r/sites/LittwinSystemtechnik/Freigegebene%20Dokumente/Projekte/Masterkarte%20V2%20setup%20files?csf=1&web=1&e=Sm1wwt) | -| NSSM.exe | 2.24 | [nssm](https://littwinsystemtechnik.sharepoint.com/:f:/r/sites/LittwinSystemtechnik/Freigegebene%20Dokumente/Projekte/Masterkarte%20V2%20setup%20files?csf=1&web=1&e=Sm1wwt) | - -> Hinweis: Die Datei `MapTypC.aspx` in TALAS lädt NodeMap als iFrame über Port 3000. -> Wenn die Seite nicht angezeigt wird, bitte sicherstellen: -> -> - Port 3000 ist in der Firewall freigegeben -> - Die IP im Scriptteil von `MapTypC.aspx` ist aktuell (z. B. `10.10.0.13`) -> - Windows-Dienst `NodeMapService` ist aktiv oder `npm start` in Terminal ausgeführt - -## 📁 Dokumentation & technische Leitfäden - -| Thema | Link | -| ------------------------- | ------------------------------------------------------- | -| Benutzeranleitung | [docs/guide/user-guide.md](docs/guide/user-guide.md) | -| Architekturübersicht | [architecture.md](docs/architecture.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) | -| Lokale Entwicklung | [setup-dev.md](docs/guide/setup-dev.md) | -| FAQ & Fehlerbehandlung | [faq.md](docs/guide/faq.md) | -| Glossar | [faq.md](docs/guide/glossar.md) | +🧩 **Fragen oder neue Entwickler im Team?** +Diese README ist der beste Startpunkt und enthält alle Links zur vertieften technischen +Dokumentation. diff --git a/package-lock.json b/package-lock.json index 65a6e968f..fddd5288d 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "nodemap", - "version": "1.1.281", + "version": "1.1.282", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "nodemap", - "version": "1.1.281", + "version": "1.1.282", "dependencies": { "@emotion/react": "^11.13.3", "@emotion/styled": "^11.13.0", diff --git a/package.json b/package.json index 420e6abc3..f5d7b5b19 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "nodemap", - "version": "1.1.281", + "version": "1.1.282", "dependencies": { "@emotion/react": "^11.13.3", "@emotion/styled": "^11.13.0",