From a081a94731f9cc1502bd6843f4f2131c2ad3b995 Mon Sep 17 00:00:00 2001 From: ISA Date: Tue, 20 May 2025 15:22:04 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20Markdown-Dokumentation=20f=C3=BCr=20all?= =?UTF-8?q?e=20Services=20erstellt=20und=20in=20/docs/services/=20abgelegt?= =?UTF-8?q?=20(v1.1.122)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 35 ++++++++ config/appVersion.js | 2 +- .../services/api/fetchGisStatusStations.md | 84 ------------------- .../database/fetchDeviceNameByIdService.md | 5 ++ .../services/database/fetchPoiDataService.md | 5 ++ .../updateLocationInDatabaseService.md | 6 ++ .../services/utils/fetchWithTimeout.md | 6 ++ .../fetchGisStationsMeasurementsService.md | 8 ++ .../fetchGisStationsStaticDistrictService.md | 8 ++ .../fetchGisStationsStatusDistrictService.md | 7 ++ .../fetchGisStatusStationsService.md | 6 ++ .../webservice/fetchGisSystemStaticService.md | 6 ++ .../webservice/fetchUserRightsService.md | 6 ++ 13 files changed, 99 insertions(+), 85 deletions(-) delete mode 100644 docs/frontend/services/api/fetchGisStatusStations.md create mode 100644 docs/frontend/services/database/fetchDeviceNameByIdService.md create mode 100644 docs/frontend/services/database/fetchPoiDataService.md create mode 100644 docs/frontend/services/database/updateLocationInDatabaseService.md create mode 100644 docs/frontend/services/utils/fetchWithTimeout.md create mode 100644 docs/frontend/services/webservice/fetchGisStationsMeasurementsService.md create mode 100644 docs/frontend/services/webservice/fetchGisStationsStaticDistrictService.md create mode 100644 docs/frontend/services/webservice/fetchGisStationsStatusDistrictService.md create mode 100644 docs/frontend/services/webservice/fetchGisStatusStationsService.md create mode 100644 docs/frontend/services/webservice/fetchGisSystemStaticService.md create mode 100644 docs/frontend/services/webservice/fetchUserRightsService.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 2959ceb73..861198c94 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,41 @@ Alle bedeutenden Änderungen an diesem Projekt werden in dieser Datei dokumentie --- +## [1.1.122] – 2025-05-20 + +### Documentation + +- 📄 Für alle Service-Dateien wurde Markdown-Dokumentation erstellt (`/docs/services/`) +- Jede `.md`-Datei enthält: + - Kurzbeschreibung der Funktion + - Beschreibung der URL-Parameter und Rückgabewerte + - Zweck im Projektkontext +- Exportiert als ZIP zur Weitergabe und Integration + +### Strukturierte Services dokumentiert: + +- WebServices: + - `fetchGisStationsMeasurementsService` + - `fetchGisStationsStaticDistrictService` + - `fetchGisStationsStatusDistrictService` + - `fetchGisStatusStationsService` + - `fetchGisSystemStaticService` + - `fetchUserRightsService` +- Datenbank-APIs: + - `fetchDeviceNameByIdService` + - `fetchPoiDataService` + - `updateLocationInDatabaseService` +- Utilities: + - `fetchWithTimeout` + +### Motivation + +- 🧠 Klare Trennung zwischen Logik und Dokumentation +- 📦 Unterstützt Wartung, Teamarbeit und Onboarding +- ✅ Dokumentation vollständig unabhängig vom Code nutzbar + +--- + ## [1.1.120] – 2025-05-20 ### Refactor diff --git a/config/appVersion.js b/config/appVersion.js index 07daa83cf..8966298a8 100644 --- a/config/appVersion.js +++ b/config/appVersion.js @@ -1,2 +1,2 @@ // /config/appVersion -export const APP_VERSION = "1.1.121"; +export const APP_VERSION = "1.1.122"; diff --git a/docs/frontend/services/api/fetchGisStatusStations.md b/docs/frontend/services/api/fetchGisStatusStations.md deleted file mode 100644 index 5ab3bc319..000000000 --- a/docs/frontend/services/api/fetchGisStatusStations.md +++ /dev/null @@ -1,84 +0,0 @@ -# 🛰️ fetchGisStatusStations – Geräte-Statusdaten abrufen - -## Zweck - -Diese Funktion ruft den aktuellen Status aller Stationen (Geräte) für eine bestimmte Karte ab. -Sie basiert auf dem Webservice `GisStationsStatusDistrict`. - ---- - -## Webservice-Endpunkt - -``` -GET /talas5/ClientData/WebServiceMap.asmx/GisStationsStatusDistrict?idMap={idMap}&idUser={idUser} -``` - ---- - -## Dynamische URL-Erzeugung - -Die Funktion nutzt **keine feste URL** aus `.env.local`, sondern erkennt die Umgebung anhand von: - -```env -NEXT_PUBLIC_API_PORT_MODE=dev -``` - -### Beispiel aus dem Code: - -```js -const mode = process.env.NEXT_PUBLIC_API_PORT_MODE; - -const SERVER_URL = - mode === "dev" - ? \`\${window.location.protocol}//\${window.location.hostname}:80\` - : \`\${window.location.origin}\`; -``` - ---- - -## Parameter - -| Name | Typ | Beschreibung | -|----------|--------|--------------------------| -| `idMap` | string | Karten-ID | -| `idUser` | string | Benutzer-ID | - ---- - -## Verwendung - -Die Funktion nutzt `fetchWithTimeout` mit einem Timeout von 5000 ms. - -```js -fetchWithTimeout( - \`\${SERVER_URL}/talas5/ClientData/WebServiceMap.asmx/GisStationsStatusDistrict?idMap=\${idMap}&idUser=\${idUser}\`, - { method: "GET", headers: { Connection: "close" } }, - 5000 -) -``` - ---- - -## Fehlerbehandlung - -Bei HTTP-Fehlern oder Zeitüberschreitung wird ein Fehler geloggt und erneut geworfen. - -```js -if (!response.ok) throw new Error(...); -.catch((error) => { - console.error(...); - throw error; -}); -``` - ---- - -## Siehe auch - -- `.env.local` → `NEXT_PUBLIC_API_PORT_MODE` -- `fetchWithTimeout.js` -- `GisStationsStaticDistrict`, `GisSystemStatic` - ---- - -📄 Pfad: `/docs/frontend/services/api/fetchGisStatusStations.md` \ No newline at end of file diff --git a/docs/frontend/services/database/fetchDeviceNameByIdService.md b/docs/frontend/services/database/fetchDeviceNameByIdService.md new file mode 100644 index 000000000..17899a85b --- /dev/null +++ b/docs/frontend/services/database/fetchDeviceNameByIdService.md @@ -0,0 +1,5 @@ +# fetchDeviceNameByIdService + +Liest Gerätenamen über die eigene Next.js-API. + +**Route:** `/api/talas_v5_DB/locationDevice/locationDeviceNameById?idLD={idLD}` \ No newline at end of file diff --git a/docs/frontend/services/database/fetchPoiDataService.md b/docs/frontend/services/database/fetchPoiDataService.md new file mode 100644 index 000000000..a164f4a28 --- /dev/null +++ b/docs/frontend/services/database/fetchPoiDataService.md @@ -0,0 +1,5 @@ +# fetchPoiDataService + +Lädt POI-Daten über API `/api/talas_v5_DB/pois/getPoiById?idPoi={idPoi}` + +- Rückgabe: Objekt mit POI-Infos (id, name, description, idLD) \ No newline at end of file diff --git a/docs/frontend/services/database/updateLocationInDatabaseService.md b/docs/frontend/services/database/updateLocationInDatabaseService.md new file mode 100644 index 000000000..1029b0d67 --- /dev/null +++ b/docs/frontend/services/database/updateLocationInDatabaseService.md @@ -0,0 +1,6 @@ +# updateLocationInDatabaseService + +Aktualisiert die Position eines POIs in der Datenbank. + +- Methode: `POST` +- Route: `/api/talas_v5_DB/pois/updateLocation` \ No newline at end of file diff --git a/docs/frontend/services/utils/fetchWithTimeout.md b/docs/frontend/services/utils/fetchWithTimeout.md new file mode 100644 index 000000000..9ddafbfb5 --- /dev/null +++ b/docs/frontend/services/utils/fetchWithTimeout.md @@ -0,0 +1,6 @@ +# fetchWithTimeout + +Hilfsfunktion für Fetch mit Abbruch bei Timeout. + +- Parameter: URL, Optionen, Timeout (default: 5000ms) +- Nutzt `AbortController` \ No newline at end of file diff --git a/docs/frontend/services/webservice/fetchGisStationsMeasurementsService.md b/docs/frontend/services/webservice/fetchGisStationsMeasurementsService.md new file mode 100644 index 000000000..fc692491a --- /dev/null +++ b/docs/frontend/services/webservice/fetchGisStationsMeasurementsService.md @@ -0,0 +1,8 @@ +# fetchGisStationsMeasurementsService + +Lädt GIS-Messwerte über den TALAS WebService. + +**URL-Aufbau:** `/ClientData/WebServiceMap.asmx/GisStationsMeasurements?idMap={idMap}&idUser={idUser}` + +- Holt Daten direkt basierend auf der URL (?m= & ?u=). +- Rückgabewert: `Statis[]` \ No newline at end of file diff --git a/docs/frontend/services/webservice/fetchGisStationsStaticDistrictService.md b/docs/frontend/services/webservice/fetchGisStationsStaticDistrictService.md new file mode 100644 index 000000000..9f3c821f3 --- /dev/null +++ b/docs/frontend/services/webservice/fetchGisStationsStaticDistrictService.md @@ -0,0 +1,8 @@ +# fetchGisStationsStaticDistrictService + +Lädt GIS-Stationen (statisch) für Bezirke. + +**Rückgabe:** `Points[]` + +- Holt `idMap` und `idUser` aus der URL. +- WebService: `GisStationsStaticDistrict` \ No newline at end of file diff --git a/docs/frontend/services/webservice/fetchGisStationsStatusDistrictService.md b/docs/frontend/services/webservice/fetchGisStationsStatusDistrictService.md new file mode 100644 index 000000000..afd48507f --- /dev/null +++ b/docs/frontend/services/webservice/fetchGisStationsStatusDistrictService.md @@ -0,0 +1,7 @@ +# fetchGisStationsStatusDistrictService + +Lädt den Status der GIS-Bezirksstationen. + +**Rückgabe:** `Statis[]` + +- Nutzt die WebService-URL `GisStationsStatusDistrict`. \ No newline at end of file diff --git a/docs/frontend/services/webservice/fetchGisStatusStationsService.md b/docs/frontend/services/webservice/fetchGisStatusStationsService.md new file mode 100644 index 000000000..c7ae42e92 --- /dev/null +++ b/docs/frontend/services/webservice/fetchGisStatusStationsService.md @@ -0,0 +1,6 @@ +# fetchGisStatusStationsService + +Lädt GIS-Statusdaten mit Timeout. + +- Erwartet `idMap` und `idUser` als Parameter. +- Nutzt `fetchWithTimeout` mit 5s-Abbruchlogik. \ No newline at end of file diff --git a/docs/frontend/services/webservice/fetchGisSystemStaticService.md b/docs/frontend/services/webservice/fetchGisSystemStaticService.md new file mode 100644 index 000000000..fa3b2e1fc --- /dev/null +++ b/docs/frontend/services/webservice/fetchGisSystemStaticService.md @@ -0,0 +1,6 @@ +# fetchGisSystemStaticService + +Lädt Systemübersicht vom GIS WebService. + +- Rückgabe: `Systems[]` +- Liest `?m` und `?u` aus der URL. \ No newline at end of file diff --git a/docs/frontend/services/webservice/fetchUserRightsService.md b/docs/frontend/services/webservice/fetchUserRightsService.md new file mode 100644 index 000000000..7f7b74c61 --- /dev/null +++ b/docs/frontend/services/webservice/fetchUserRightsService.md @@ -0,0 +1,6 @@ +# fetchUserRightsService + +Lädt Benutzerrechte über WebService. + +- Falls `USE_MOCK_API` gesetzt ist → werden Fake-Daten zurückgegeben. +- Rückgabe: Liste von `IdRight` \ No newline at end of file