245 lines
9.8 KiB
Markdown
245 lines
9.8 KiB
Markdown
# 🌍 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.
|
||
|
||
## 🌍 Live-Vorschau der Karte
|
||
|
||
|
||
|
||
---
|
||
|
||
> 🖥 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
|
||
|
||
---
|
||
|
||
## Technologie-Stack
|
||
|
||
| Technologie | Zweck |
|
||
| ------------- | ------------------------------ |
|
||
| Next.js | React-Framework (Frontend/SSR) |
|
||
| Leaflet | Kartendarstellung |
|
||
| Redux Toolkit | Zustandverwaltung |
|
||
| Tailwind CSS | Styling |
|
||
| 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
|
||
|
||
---
|
||
|
||
## 🔄 Wie funktioniert das System?
|
||
|
||
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)
|
||
|
||
---
|
||
|
||
## 🧰 Erstinstallation auf Server
|
||
|
||
### Voraussetzungen
|
||
|
||
- 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`
|
||
|
||
|
||
---
|
||
|
||
## 🔗 Integration in TALAS.web
|
||
|
||
|
||
|
||
- 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`
|
||
```
|
||
|
||
---
|
||
|
||
## 🪛 Schritt-für-Schritt: NodeMap auf dem Server installieren
|
||
|
||
---
|
||
|
||
## 📦 Schnelles Deployment über ZIP-Paket
|
||
|
||
Ein fertiges Deployment-Bundle für jede Version (z. B. `NodeMap V1.1.260.zip`) ist auf dem internen
|
||
SharePoint verfügbar:
|
||
|
||
📁
|
||
[Masterkarte V2 setup files](https://littwinsystemtechnik.sharepoint.com/sites/LittwinSystemtechnik/Freigegebene%20Dokumente/Forms/AllItems.aspx?id=%2Fsites%2FLittwinSystemtechnik%2FFreigegebene%20Dokumente%2FProjekte%2FMasterkarte%20V2%20setup%20files&csf=1&web=1&e=Sm1wwt&CID=9291bb06%2Dc869%2D4e30%2D8efa%2D8cda40df3cd6&FolderCTID=0x0120009C4F8227D6A11D4E89F1CCB9E517F488)
|
||
|
||
**ZIP-Inhalt:**
|
||
NodeMap
|
||
|
||
- `.next/`, `public/` → Build- und statische Dateien
|
||
- `.env.production` → Umgebungsvariablen
|
||
|
||
---
|
||
|
||
- `nssm.exe` → Windows-Diensttool, `Start-Dev.ps1`
|
||
- `StartNodeApp.bat` → Startet sowohl die NodeMap-Anwendung (Next.js, Port 3000) als auch den
|
||
integrierten WebSocket-Server (Socket.IO, ebenfalls über Port 3000)
|
||
- Anleitung `nssm.exe Installation.md`
|
||
[Anleitung zur Dienstinstallation mit NSSM](docs/nssm-exe-installation.md)
|
||
|
||
---
|
||
|
||
- `package.json`, `package-lock.json`
|
||
- `server.js` → Startet den integrierten WebSocket-Server auch (Port 3000) zur Datenübertragung von
|
||
TALAS.web WebServices
|
||
|
||
**Optional:**
|
||
|
||
Falls `node_modules/` auf dem Server nicht vorhanden ist:
|
||
|
||
- `node_modules-v1.1.260.zip` herunterladen und entpacken
|
||
|
||
➡ Danach nur noch entpacken nach `C:\inetpub\wwwroot\talas5\nodeMap` und Dienst starten.
|
||
|
||
---
|
||
|
||
## 📦 Über Git
|
||
|
||
1. **Projekt lokal klonen und kompilieren:**
|
||
|
||
```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/
|
||
```
|
||
|
||
2. **ZIP-Paket vorbereiten (lokal):**
|
||
|
||
- 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)
|
||
|
||
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
|
||
```
|
||
|
||
---
|
||
|
||
## 🔁 Update-Richtlinien
|
||
|
||
| 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`
|
||
|
||
---
|
||
|
||
## ✅ 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) |
|