docs: überarbeitete /docs/README.md

2025-06-24 07:17:36 +02:00
parent 7b68534f7e
commit 82a1e11797
5 changed files with 51 additions and 53 deletions
--- a/docs/README.md
+++ b/docs/README.md
@@ -4,7 +4,7 @@ Willkommen in der Entwicklerdokumentation für **NodeMap** – einer modularen K
 Visualisierung und Bearbeitung von GIS-Daten, POIs und Gerätestatus in einer interaktiven
 Leaflet-Karte.

-Diese Anleitung führt dich **Schritt für Schritt** durch die wichtigsten Bereiche für lokale
+Diese Anleitung führt dich **Schritt für Schritt** durch die wichtigsten Themen für lokale
 Entwicklung, Architekturverständnis und Erweiterung.

 ---
@@ -13,7 +13,7 @@ Entwicklung, Architekturverständnis und Erweiterung.

 ### 🔹 Einstieg & Übersicht

- [Projektüberblick](architecture.md)
+- [Projektüberblick](#projektüberblick)
 - [Build & Deployment](build-and-deploy.md)
 - [Checkliste für Deployment](checklist.md)
 - [Dynamische Marker erklärt](DynamischeMarkerErklaerung.md)
@@ -60,18 +60,16 @@ Entwicklung, Architekturverständnis und Erweiterung.
 - [EditModeToggle](components/uiWidgets/mapLayersControlPanel/EditModeToggle.md)
 - [MapLayersControlPanel](components/uiWidgets/mapLayersControlPanel/MapLayersControlPanel.md)

-### 🔍 Weitere Tools
+### 🧪 Weitere Tools

 - [TestScript (Debug)](components/TestScript.md)

 ---

---
+## Projektüberblick

-## 🔍 Projektüberblick
-
-NodeMap wird von **TALAS.web** über einen iFrame geladen. Die Anwendung verwendet moderne
-Technologien wie:
+NodeMap wird von **TALAS.web** über einen iFrame geladen. Die Anwendung basiert auf folgenden
+Technologien:

 | Technologie   | Zweck                          |
 | ------------- | ------------------------------ |
@@ -82,86 +80,86 @@ Technologien wie:
 | MySQL         | Datenbank                      |
 | Node.js / IIS | Server und Auslieferung        |

-➡ Mehr zur Architektur: [architecture.md](/docs/architecture.md)
+👉 Mehr zur Systemarchitektur: [architecture.md](architecture.md)

 ---

-## 🧱 Projektstruktur & Setup
+## Projektstruktur & Setup

-🔧 **Zielsystem:**
+### Zielsystem

 - Offline-Umgebung
 - Windows-Server mit IIS
- Datenzugriff über Webservice oder lokale API
+- Datenzugriff über TALAS-Webservice oder lokale API

-🚀 **Lokale Entwicklung starten:**  
-➡ [Entwicklungssetup](guide/setup-dev.md)
+### Lokale Entwicklung

-📁 **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)
+➡ [Entwicklungs-Setup](guide/setup-dev.md)  
+➡ [Projektstruktur erklärt](guide/project-structure.md)  
+➡ [Abhängigkeiten & Tools](guide/dependencies.md)  
+➡ [Umgebungsvariablen (env-Dateien)](guide/env.md)

 ---

-## 🔌 Webservices & API-Fluss
+## Webservices & API-Fluss

-NodeMap greift auf zwei Datenquellen zu:
+NodeMap verwendet zwei Quellen für Daten:

-1. **TALAS-WebServices** (Port 80) – Gerätedaten, POIs, Rechte etc.
-2. **Lokale Next.js API** (Port 3000) – eigene Datenbankabfragen via MySQL
+1. **TALAS-WebServices** (Port 80) – POIs, Geräte, Rechte, Linien usw.
+2. **Lokale Next.js API** (Port 3000) – direkte Datenbankzugriffe via MySQL

 ➡ [Webservices-Dokumentation](guide/webservices.md)

 ---

-## 🧠 Zustandverwaltung (Redux)
+## Zustandverwaltung Redux

-Alle Karten- und Gerätefunktionen (z. B. Marker, Linien, POIs) sind über Redux-Slices und Thunks
-organisiert:
+Die komplette Anwendung verwendet Redux zur globalen Zustandverwaltung.

- Datenfluss: `Service` → `Thunk` → `Slice` → `Komponente`
- Beispiel: POI-Daten, Gerätemarker, Rechteprüfung, Sichtbarkeiten
+- Architektur: `Service → Thunk → Slice → Komponente`
+- Beispiel: POIs, Marker, Linien, Rechte, Layer-Status
+- Redux DevTools werden unterstützt

 ➡ [Zustandverwaltung mit Redux](guide/redux-zustand.md)

 ---

-## 🧪 Entwicklung & Testdaten
+## Entwicklung & Testdaten

-Um auch **ohne echte Datenquelle** arbeiten zu können:
+Zur Entwicklung ohne echte API stehen lokale Mockdaten zur Verfügung:

- ✔ Mockdaten-Modus über `.env.local`
- ✔ API-Antworten werden lokal simuliert
- ✔ Redux prüft, ob `process.env.NEXT_PUBLIC_USE_MOCKS === true`
+- Aktivierung über `.env.local → NEXT_PUBLIC_USE_MOCKS=true`
+- Nutzung z. B. in `pages/api/mocks/...`
+- Hinweise im UI zeigen aktivierten Mockmodus

 ➡ [Mockdaten & Entwicklung](guide/mock-data.md)

 ---

-## ❗ Fehlerbehandlung & Glossar
+## Fehlerbehandlung & Glossar

-Typische Probleme bei Installation, Deployment oder Datenzugriff:
-
-➡ [FAQ & häufige Fehler](guide/faq.md)
-
-Begriffe wie `POI`, `IdMap`, `Station`, `Layer`, `Slice` erklärt:
+Typische Probleme (z. B. Webservice nicht erreichbar, Layer nicht sichtbar) werden in der FAQ
+gesammelt.  
+Zudem gibt es eine Begriffsliste zur Orientierung:

+➡ [FAQ & häufige Fehler](guide/faq.md)  
 ➡ [Glossar](guide/glossar.md)

 ---

-## 🔄 Hinweis zum Deployment
+## Hinweis zum Deployment

-Für die Anleitung zur Installation auf dem Server → siehe  
-📦 [Root-README.md im Projektverzeichnis](../README.md)
+📦 Die Anleitung für Server-Installation und ZIP-Deployment findest du in:  
+➡ [Root-README.md](../README.md)

 ---

-🧩 **Fragen oder neue Entwickler im Team?**  
-Diese README ist der beste Startpunkt und enthält alle Links zur vertieften technischen
-Dokumentation.
+## Tipp
+
+Wenn du neu im Projekt bist, beginne mit dem Kapitel **Projektstruktur & Setup** und folge dann über
+die Webservices bis zu den Komponenten.
+
+---
+
+Möchtest du eine `.md`-Datei exportiert zum Einfügen in dein Projektverzeichnis? Ich kann dir sofort
+eine Download-Version erstellen. Sag einfach: „Ja, bitte als Datei“.