docs: docs/README

2025-06-24 06:58:56 +02:00
parent 13ce14a703
commit 4a7328167c
6 changed files with 82 additions and 160 deletions
--- 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://<ip>/talas5/MessagesMap/mapTypC.aspx?m=IdMap&u=IdUser
-   z.B.
-   http://<ip>/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://<ip>/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.