docs: Projektstruktur der Dokumentation an Quellcode angepasst

- Verzeichnisstruktur unter /docs spiegelt nun die tatsächliche Projektstruktur wider - frontend/server-Trennung entfernt zugunsten von /docs/pages, /docs/redux, /docs/utils etc. - Erhöht Wiederauffindbarkeit, Übersichtlichkeit und Entwicklerfreundlichkeit
2025-05-27 09:30:40 +02:00
parent 4c6386edea
commit b847b5d2c8
55 changed files with 29 additions and 3 deletions
--- a/docs/redux/api/fromDB/fetchLocationDevices.md
+++ b/docs/redux/api/fromDB/fetchLocationDevices.md
@@ -0,0 +1,70 @@
+# 🌐 fetchLocationDevices
+
+Diese Funktion lädt alle Geräte für einen bestimmten Standort aus der Datenbank via API-Endpunkt.
+
+---
+
+## 📍 Pfad
+
+```
+/redux/api/fromDB/fetchLocationDevices.js
+```
+
+---
+
+## 📥 Funktion
+
+```ts
+export const fetchLocationDevices = async () => {
+  const response = await fetch("/api/talas_v5_DB/locationDevice/locationDevices");
+  if (!response.ok) {
+    throw new Error("Geräteliste konnte nicht geladen werden");
+  }
+  return await response.json();
+};
+```
+
+---
+
+## 📡 API-Endpunkt
+
+```http
+GET /api/talas_v5_DB/locationDevice/locationDevices
+```
+
+Dieser Endpunkt liefert eine JSON-Liste aller Geräte eines Standorts (z. B. für Map-Rendering, POI-Anzeige, Standortübersicht etc.).
+
+---
+
+## 🧪 Fehlerbehandlung
+
+Falls der Request fehlschlägt (z. B. Statuscode ≠ 2xx), wird folgender Fehler ausgelöst:
+
+```
+"Geräteliste konnte nicht geladen werden"
+```
+
+Dies kann im Redux-Slice über den `.rejected`-Case ausgewertet werden.
+
+---
+
+## 🧩 Verwendung
+
+```ts
+import { fetchLocationDevices } from "@/redux/api/fromDB/fetchLocationDevices";
+
+const result = await fetchLocationDevices();
+console.log(result); // Erwartet: Array von Geräteobjekten
+```
+
+Diese Funktion wird typischerweise im Redux-Thunk `fetchLocationDevicesFromDB` verwendet:
+```ts
+const data = await fetchLocationDevices();
+```
+
+---
+
+## 🔄 Zusammenhang
+
+- Eingebunden in: [`locationDevicesFromDBSlice.js`](./locationDevicesFromDBSlice.md)
+- Redux Thunk: `fetchLocationDevicesFromDB`
--- a/docs/redux/api/fromWebService.md
+++ b/docs/redux/api/fromWebService.md
@@ -0,0 +1,90 @@
+# 📡 Webservices – Redux Integration (/redux/api/fromWebService)
+
+In diesem Verzeichnis befinden sich alle Webservice-Fetch-Funktionen für die Kommunikation mit TALAS.web über SOAP-Endpunkte.
+
+---
+
+## Übergabe der Parameter über URL (`m`, `u`)
+
+TALAS.web ruft die Kartenansicht in der Regel so auf:
+
+```
+http://[SERVER]:3000/?m=10&u=484
+```
+
+Daraus ergeben sich folgende Zuweisungen:
+
+| URL-Parameter | Bedeutung | Variable im Code                 |
+| ------------- | --------- | -------------------------------- |
+| `m`           | `idMap`   | `const idMap = params.get("m")`  |
+| `u`           | `idUser`  | `const idUser = params.get("u")` |
+
+### Beispiel:
+
+```ts
+const params = new URLSearchParams(window.location.search);
+const idMap = params.get("m");
+const idUser = params.get("u");
+```
+
+---
+
+## Änderung am 2025-05-15
+
+Vorher wurden Default-Werte über `.env.local` als Fallback genutzt:
+
+```ts
+const idMap = params.get("idMap") || process.env.NEXT_PUBLIC_DEFAULT_ID_MAP || "12";
+```
+
+Das wurde entfernt, um folgende Ziele zu erreichen:
+
+- ❌ Keine fest eingetragenen Defaults im Browser sichtbar
+- ✅ Verbindlichkeit: TALAS.web übergibt die Werte immer korrekt via URL
+- 🔐 Sicherheit: Kein versehentliches Verwenden eines falschen Users
+- 🔍 Fehler leichter erkennbar (Parameter nicht gefunden = echter Fehler)
+
+---
+
+## Hinweis zur Webservice-Konfiguration
+
+Die Webservice-Basisadresse wird **nicht mehr über `.env.local` gesteuert**.
+
+Stattdessen wird sie dynamisch im Client anhand des aktuellen Hostnamens bestimmt:
+
+```js
+const baseUrl = `${window.location.origin}/talas5/ClientData/WebServiceMap.asmx`;
+```
+
+➡ Dadurch ist kein Rebuild mehr nötig bei IP-Wechseln oder Serverumzügen.  
+Die Build-Version kann auf jedem Server wiederverwendet werden.
+
+---
+
+## Optional: Validierung einbauen
+
+Falls gewünscht, kann ein expliziter Fehler ausgelöst werden:
+
+```ts
+if (!idMap || !idUser) {
+  throw new Error("Fehlende URL-Parameter: idMap oder idUser");
+}
+```
+
+---
+
+## Betroffene Dateien
+
+Diese Änderung betrifft alle Funktionen in:
+
+```
+/redux/api/fromWebService/fetchGisStationsStatic.js
+/redux/api/fromWebService/fetchGisStationsStaticDistrict.js
+/redux/api/fromWebService/fetchGisStationsStatusDistrict.js
+/redux/api/fromWebService/fetchGisStationsMeasurements.js
+/redux/api/fromWebService/fetchGisSystemStatic.js
+```
+
+---
+
+Diese Konvention stellt sicher, dass Webservices unabhängig von IP und Serverkonfiguration aufgerufen werden können.
--- a/docs/redux/api/fromWebService/README.md
+++ b/docs/redux/api/fromWebService/README.md
@@ -0,0 +1,61 @@
+# 📁 Webservice-Dokumentation – fromWebService
+
+Dieses Verzeichnis dokumentiert alle Webservice-Aufrufe,  
+die über `/redux/api/fromWebService/` im Projekt ausgeführt werden.
+
+---
+
+## 🌐 Hintergrund
+
+Die TALAS.web-Anwendung übergibt `idMap` und `idUser` über die URL-Parameter:
+
+```
+http://<server>/talas5/MessagesMap/mapTypeC.aspx?m=12&u=484
+```
+
+Daraus entstehen Webservice-Aufrufe wie:
+
+```
+/talas5/ClientData/WebServiceMap.asmx/GisSystemStatic?idMap=12&idUser=484
+```
+
+Alle Webservices nutzen den Port 80 – auch in der Entwicklungsumgebung.  
+Daher wird zentral über `.env.local` gesteuert:
+
+```env
+NEXT_PUBLIC_API_PORT_MODE=dev
+```
+
+---
+
+## 📄 Enthaltene Dokumentationen
+
+| Dateiname                              | Zweck                                |
+|----------------------------------------|--------------------------------------|
+| [`fetchGisSystemStatic.md`](./fetchGisSystemStatic.md)                     | Systemübersicht aller Geräte         |
+| [`fetchGisStationsMeasurements.md`](./fetchGisStationsMeasurements.md)     | Messwerte der Geräte                 |
+| [`fetchGisStationsStatic.md`](./fetchGisStationsStatic.md)                 | Statische Standortinformationen      |
+| [`fetchGisStationsStaticDistrict.md`](./fetchGisStationsStaticDistrict.md) | Gerätestruktur je Bezirk             |
+| [`fetchGisStationsStatusDistrict.md`](./fetchGisStationsStatusDistrict.md) | Aktueller Gerätestatus nach Bezirk   |
+
+---
+
+## 🔁 Verzeichnisstruktur
+
+```bash
+/docs
+└── frontend
+    └── redux
+        └── api
+            └── fromWebService
+                ├── fetchGisSystemStatic.md
+                ├── fetchGisStationsMeasurements.md
+                ├── fetchGisStationsStatic.md
+                ├── fetchGisStationsStaticDistrict.md
+                ├── fetchGisStationsStatusDistrict.md
+                └── README.md  ← (diese Datei)
+```
+
+---
+
+Diese Übersicht hilft Entwicklern beim Einstieg und zeigt, wie zentrale Webservice-Kommunikation im Projekt funktioniert.
--- a/docs/redux/api/fromWebService/fetchGisStationsMeasurements.md
+++ b/docs/redux/api/fromWebService/fetchGisStationsMeasurements.md
@@ -0,0 +1,81 @@
+# 🌐 fetchGisStationsMeasurements – Geräte-Messwerte abrufen
+
+## Zweck
+
+Diese Funktion ruft Messwerte aller Geräte einer Karte ab.  
+Die Daten werden vom Webservice `GisStationsMeasurements` bereitgestellt.
+
+---
+
+## Webservice-Endpunkt
+
+```
+GisStationsMeasurements?idMap={idMap}&idUser={idUser}
+```
+
+---
+
+## Besonderheit: Port-Steuerung per Umgebungsvariable
+
+Die Webservices (z. B. `WebServiceMap.asmx`) laufen **immer auf Port 80** –  
+auch in der Entwicklungsumgebung.
+
+Um das zu berücksichtigen, wird der Port über `.env.local` gesteuert:
+
+```env
+NEXT_PUBLIC_API_PORT_MODE=dev
+```
+
+### Beispiel (aus dem Code):
+
+```js
+const mode = process.env.NEXT_PUBLIC_API_PORT_MODE;
+
+const apiBaseUrl =
+  mode === "dev"
+    ? `${window.location.protocol}//${window.location.hostname}:80/talas5/ClientData/WebServiceMap.asmx`
+    : `${window.location.origin}/talas5/ClientData/WebServiceMap.asmx`;
+```
+
+---
+
+## Parameter
+
+| URL-Parameter | Beschreibung | Übergabe durch TALAS.web |
+|---------------|--------------|---------------------------|
+| `m`           | Map-ID       | Ja                        |
+| `u`           | User-ID      | Ja                        |
+
+Diese Parameter werden clientseitig aus der URL gelesen:
+
+```js
+const params = new URLSearchParams(window.location.search);
+const idMap = params.get("m");
+const idUser = params.get("u");
+```
+
+---
+
+## Beispiel-Aufruf
+
+```
+http://10.10.0.13/talas5/MessagesMap/mapTypeC.aspx?m=12&u=484
+```
+
+→ ergibt folgenden Webservice-Aufruf:
+
+```
+http://10.10.0.13/talas5/ClientData/WebServiceMap.asmx/GisStationsMeasurements?idMap=12&idUser=484
+```
+
+---
+
+## Siehe auch
+
+- `.env.local` → `NEXT_PUBLIC_API_PORT_MODE`
+- `docs/frontend/redux/api/fromWebService/fetchGisSystemStatic.md`
+- API-Datei: `/redux/api/fromWebService/fetchGisStationsMeasurements.js`
+
+---
+
+📄 Pfad: `/docs/frontend/redux/api/fromWebService/fetchGisStationsMeasurements.md`
--- a/docs/redux/api/fromWebService/fetchGisStationsStatic.md
+++ b/docs/redux/api/fromWebService/fetchGisStationsStatic.md
@@ -0,0 +1,78 @@
+# 🌐 fetchGisStationsStatic – Standortdaten der Karte abrufen
+
+## Zweck
+
+Diese Funktion ruft die statischen Standortinformationen aller Geräte für eine bestimmte Karte ab.  
+Sie nutzt den Webservice-Endpunkt `GisStationsStatic`.
+
+---
+
+## Webservice-Endpunkt
+
+```
+GisStationsStatic?idMap={idMap}
+```
+
+---
+
+## Besonderheit: Port-Steuerung über Umgebungsvariable
+
+Die Webservices laufen immer auf Port 80 – auch in der Entwicklungsumgebung.
+
+Die Funktion erkennt dies anhand der Umgebungsvariable in `.env.local`:
+
+```env
+NEXT_PUBLIC_API_PORT_MODE=dev
+```
+
+### Codeauszug:
+
+```js
+const mode = process.env.NEXT_PUBLIC_API_PORT_MODE;
+
+const apiBaseUrl =
+  mode === "dev"
+    ? `${window.location.protocol}//${window.location.hostname}:80/talas5/ClientData/WebServiceMap.asmx`
+    : `${window.location.origin}/talas5/ClientData/WebServiceMap.asmx`;
+```
+
+---
+
+## Parameter
+
+| URL-Parameter | Beschreibung | Übergabe durch TALAS.web |
+|---------------|--------------|---------------------------|
+| `m`           | Map-ID       | Ja                        |
+
+Die Map-ID wird aus der URL gelesen:
+
+```js
+const params = new URLSearchParams(window.location.search);
+const idMap = params.get("m");
+```
+
+---
+
+## Beispiel
+
+```
+http://10.10.0.13/talas5/MessagesMap/mapTypeC.aspx?m=12&u=484
+```
+
+→ wird zu:
+
+```
+http://10.10.0.13/talas5/ClientData/WebServiceMap.asmx/GisStationsStatic?idMap=12
+```
+
+---
+
+## Siehe auch
+
+- `.env.local` → `NEXT_PUBLIC_API_PORT_MODE`
+- `fetchGisSystemStatic.md`
+- `fetchGisStationsMeasurements.md`
+
+---
+
+📄 Pfad: `/docs/frontend/redux/api/fromWebService/fetchGisStationsStatic.md`
--- a/docs/redux/api/fromWebService/fetchGisStationsStaticDistrict.md
+++ b/docs/redux/api/fromWebService/fetchGisStationsStaticDistrict.md
@@ -0,0 +1,77 @@
+# 🌐 fetchGisStationsStaticDistrict – Statische Gerätebezirksdaten abrufen
+
+## Zweck
+
+Diese Funktion ruft alle statischen Geräte- und Sektordaten eines bestimmten Kartenbereichs ab.  
+Sie basiert auf dem Webservice-Endpunkt `GisStationsStaticDistrict`.
+
+---
+
+## Webservice-Endpunkt
+
+```
+GisStationsStaticDistrict?idMap={idMap}&idUser={idUser}
+```
+
+---
+
+## Portsteuerung über Umgebungsvariable
+
+Da die Webservices in allen Umgebungen auf Port 80 laufen, wird der Zugriff über eine Umgebungsvariable gesteuert:
+
+```env
+NEXT_PUBLIC_API_PORT_MODE=dev
+```
+
+### Codebeispiel:
+
+```js
+const mode = process.env.NEXT_PUBLIC_API_PORT_MODE;
+
+const apiBaseUrl =
+  mode === "dev"
+    ? `${window.location.protocol}//${window.location.hostname}:80/talas5/ClientData/WebServiceMap.asmx`
+    : `${window.location.origin}/talas5/ClientData/WebServiceMap.asmx`;
+```
+
+---
+
+## URL-Parameter
+
+| Parameter | Beschreibung | Wird übergeben durch |
+|-----------|--------------|------------------------|
+| `m`       | Map-ID       | TALAS.web (in URL)     |
+| `u`       | User-ID      | TALAS.web (in URL)     |
+
+```js
+const params = new URLSearchParams(window.location.search);
+const idMap = params.get("m");
+const idUser = params.get("u");
+```
+
+---
+
+## Beispiel
+
+```
+http://10.10.0.13/talas5/MessagesMap/mapTypeC.aspx?m=12&u=484
+```
+
+→ wird übersetzt zu:
+
+```
+http://10.10.0.13/talas5/ClientData/WebServiceMap.asmx/GisStationsStaticDistrict?idMap=12&idUser=484
+```
+
+---
+
+## Siehe auch
+
+- `.env.local` → `NEXT_PUBLIC_API_PORT_MODE`
+- `fetchGisStationsStatic.js`
+- `fetchGisStationsMeasurements.js`
+- `fetchGisSystemStatic.js`
+
+---
+
+📄 Pfad: `/docs/frontend/redux/api/fromWebService/fetchGisStationsStaticDistrict.md`
--- a/docs/redux/api/fromWebService/fetchGisStationsStatusDistrict.md
+++ b/docs/redux/api/fromWebService/fetchGisStationsStatusDistrict.md
@@ -0,0 +1,78 @@
+# 🌐 fetchGisStationsStatusDistrict – Gerätestatus nach Bezirken abrufen
+
+## Zweck
+
+Diese Funktion ruft die aktuellen Statusdaten aller Geräte eines bestimmten Kartenbezirks ab.  
+Sie basiert auf dem Webservice-Endpunkt `GisStationsStatusDistrict`.
+
+---
+
+## Webservice-Endpunkt
+
+```
+GisStationsStatusDistrict?idMap={idMap}&idUser={idUser}
+```
+
+---
+
+## Portsteuerung über Umgebungsvariable
+
+Da die Webservices in allen Umgebungen über Port 80 laufen,  
+wird der Zugriff über eine Umgebungsvariable in `.env.local` konfiguriert:
+
+```env
+NEXT_PUBLIC_API_PORT_MODE=dev
+```
+
+### Codebeispiel:
+
+```js
+const mode = process.env.NEXT_PUBLIC_API_PORT_MODE;
+
+const apiBaseUrl =
+  mode === "dev"
+    ? `${window.location.protocol}//${window.location.hostname}:80/talas5/ClientData/WebServiceMap.asmx`
+    : `${window.location.origin}/talas5/ClientData/WebServiceMap.asmx`;
+```
+
+---
+
+## URL-Parameter
+
+| Parameter | Beschreibung | Übergabe durch TALAS.web |
+|-----------|--------------|---------------------------|
+| `m`       | Map-ID       | Ja                        |
+| `u`       | User-ID      | Ja                        |
+
+```js
+const params = new URLSearchParams(window.location.search);
+const idMap = params.get("m");
+const idUser = params.get("u");
+```
+
+---
+
+## Beispiel
+
+```
+http://10.10.0.13/talas5/MessagesMap/mapTypeC.aspx?m=12&u=484
+```
+
+→ wird übersetzt zu:
+
+```
+http://10.10.0.13/talas5/ClientData/WebServiceMap.asmx/GisStationsStatusDistrict?idMap=12&idUser=484
+```
+
+---
+
+## Siehe auch
+
+- `.env.local` → `NEXT_PUBLIC_API_PORT_MODE`
+- `fetchGisStationsStaticDistrict.js`
+- `fetchGisStationsMeasurements.js`
+- `fetchGisSystemStatic.js`
+
+---
+
+📄 Pfad: `/docs/frontend/redux/api/fromWebService/fetchGisStationsStatusDistrict.md`
--- a/docs/redux/api/fromWebService/fetchGisSystemStatic.md
+++ b/docs/redux/api/fromWebService/fetchGisSystemStatic.md
@@ -0,0 +1,76 @@
+# 🌐 fetchGisSystemStatic – Geräte-Systemdaten abrufen
+
+## Zweck
+
+Diese Funktion ruft die Gerätestatus-Übersicht für eine bestimmte Karte ab:
+
+WebService-Endpunkt:
+
+```
+GisSystemStatic?idMap={idMap}&idUser={idUser}
+```
+
+---
+
+## Besonderheit bei der URL
+
+Die Webservices (z. B. `WebServiceMap.asmx`) laufen **immer auf Port 80**,  
+egal ob im Entwicklungsmodus (`localhost`, `:3000`) oder auf dem Testserver (`10.10.0.13`).
+
+Daher wird im Code explizit `:80` gesetzt – gesteuert über die Umgebungsvariable:
+
+```env
+NEXT_PUBLIC_API_PORT_MODE=dev
+```
+
+### Beispiel (aus dem Code):
+
+```js
+const mode = process.env.NEXT_PUBLIC_API_PORT_MODE;
+
+const apiBaseUrl = mode === "dev" ? `${window.location.protocol}//${window.location.hostname}:80/talas5/ClientData/WebServiceMap.asmx` : `${window.location.origin}/talas5/ClientData/WebServiceMap.asmx`;
+```
+
+---
+
+## Parameter
+
+Die Funktion liest folgende URL-Parameter ein:
+
+| URL-Parameter | Beschreibung | Übergabe durch TALAS.web |
+| ------------- | ------------ | ------------------------ |
+| `m`           | Map-ID       | Ja                       |
+| `u`           | User-ID      | Ja                       |
+
+Diese werden aus der URL wie folgt gelesen:
+
+```js
+const params = new URLSearchParams(window.location.search);
+const idMap = params.get("m");
+const idUser = params.get("u");
+```
+
+---
+
+## Beispiel-Aufruf
+
+TALAS-Aufruf:
+
+```
+http://10.10.0.13/talas5/MessagesMap/mapTypeC.aspx?m=12&u=484
+```
+
+wird im Webservice-Request zu:
+
+```
+http://10.10.0.13/talas5/ClientData/WebServiceMap.asmx/GisSystemStatic?idMap=12&idUser=484
+```
+
+---
+
+## Siehe auch
+
+- `.env.local` → `NEXT_PUBLIC_API_PORT_MODE`
+- `docs/fromWebService.md`
+- API-Datei: `/redux/api/fromWebService/fetchGisSystemStatic.js`
+- 📄 Pfad: `/docs/frontend/redux/api/fromWebService/fetchGisSystemStatic.md`