@@ -1,21 +1,32 @@
# 🚀 NodeMap – instieg für Entwickler
# 📘 NodeMap – ntwicklerdokumentation
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 Kart e
Diese Anleitung führt dich **Schritt für Schritt** durch die wichtigsten Bereiche für lokal e
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 – ](#-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-Sta ck
## 🔍 Projektüberbli ck
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. –
- 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`
1. **TALAS-WebServices** (Port 80) –
2. **Lokale Next.js API** (Port 3000) –
➡ [Webservices-Dokumentation ](guide/webservices.md )
---
## 🔗 Integration in TALAS.web
## 🧠 Zustandverwaltung (Redux)
Alle Karten- und Gerätefunktionen (z.
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 installier en
🧪 Entwicklung & Testdat en
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.
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-Richtlini en
🔄 Hinweis zum Deploym ent
| 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. 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.
ISA