From 7d1e7ef88ae92f18a0c6172976cf6b4b68370cd3 Mon Sep 17 00:00:00 2001 From: Ismail Ali Date: Sat, 21 Jun 2025 23:54:02 +0200 Subject: [PATCH] docs: add full architecture diagram and data flow for json, jsmock and production modes --- .env.development | 2 +- .env.production | 2 +- CHANGELOG.md | 5 ++ docs/diagrams/analog-inputs-flow.md | 88 ++++++++++++++--------------- package-lock.json | 4 +- package.json | 2 +- 6 files changed, 52 insertions(+), 51 deletions(-) diff --git a/.env.development b/.env.development index dd39b43..4d14996 100644 --- a/.env.development +++ b/.env.development @@ -6,5 +6,5 @@ NEXT_PUBLIC_USE_MOCK_BACKEND_LOOP_START=false NEXT_PUBLIC_EXPORT_STATIC=false NEXT_PUBLIC_USE_CGI=false # App-Versionsnummer -NEXT_PUBLIC_APP_VERSION=1.6.440 +NEXT_PUBLIC_APP_VERSION=1.6.441 NEXT_PUBLIC_CPL_MODE=jsmock # json (Entwicklungsumgebung) oder jsmock (CPL ->CGI-Interface-Simulator) oder production (CPL-> CGI-Interface Platzhalter) \ No newline at end of file diff --git a/.env.production b/.env.production index 013b74a..ce88a1f 100644 --- a/.env.production +++ b/.env.production @@ -5,5 +5,5 @@ NEXT_PUBLIC_CPL_API_PATH=/CPL NEXT_PUBLIC_EXPORT_STATIC=true NEXT_PUBLIC_USE_CGI=true # App-Versionsnummer -NEXT_PUBLIC_APP_VERSION=1.6.440 +NEXT_PUBLIC_APP_VERSION=1.6.441 NEXT_PUBLIC_CPL_MODE=production \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 1f4b13c..fc03c30 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,8 @@ +## [1.6.441] – 2025-06-21 + +- docs: add analog inputs architecture diagram and flow description + +--- ## [1.6.440] – 2025-06-21 - docs: move user documentation to docs/user-guide as single source of truth diff --git a/docs/diagrams/analog-inputs-flow.md b/docs/diagrams/analog-inputs-flow.md index 225e36e..d8169fc 100644 --- a/docs/diagrams/analog-inputs-flow.md +++ b/docs/diagrams/analog-inputs-flow.md @@ -1,71 +1,67 @@ -# 📊 Architektur: Analoge Eingänge – Datenfluss & Struktur +# 🧩 Datenfluss & Architekturstrategie – Analoge Eingänge (Alle Modi) -Diese Datei beschreibt den Datenfluss und die Trennung der Verantwortlichkeiten beim Laden der analogen Eingänge aus JavaScript-Mockdateien im Entwicklungsmodus (`NEXT_PUBLIC_NODE_ENV=development`). +Diese Dokumentation beschreibt die Architekturstrategie für die Verarbeitung von analogen Eingangsdaten in den drei unterstützten Modi: `jsmock`, `json` und `production`. --- ## 🎯 Ziel -- Mockdaten in `.js`-Format (wie vom echten Gerät geliefert) -- Konvertierung in valide JSON-Objekte -- Einheitlicher Zugriff über `fetch` im Service -- Redux/Komponenten bleiben unabhängig von der Datenquelle +- Trennung von Verantwortung (API, Service, UI) +- Mock-fähige Entwicklung ohne echte Hardware +- Einheitliches JSON-Format für alle Modi +- Zukunftssicherheit für moderne Systeme mit nativen JSON-APIs --- -## 📌 Verzeichnisstruktur (Beispiel) - -```txt -/mocks/device-cgi-simulator/SERVICE/analogInputsMockData.js -/pages/api/cpl/getAnalogInputsHandler.ts -/services/fetchAnalogInputsService.ts -/redux/thunks/getAnalogInputsThunk.ts -/components/AnalogInputsDisplay.tsx -``` - ---- - -## 📐 UML-Diagramm (Mermaid) +## 🔁 Datenfluss (alle Modi) ```mermaid flowchart TD -subgraph Quelle - A1[analogInputsMockData.js – JS-Format mit window-Variablen] -end + subgraph JSMOCK-Modus + A1["analogInputsMockData.js - Mockdaten mit window-Variablen"] + B1["/api/cpl/getAnalogInputsHandler.ts - API gibt Rohdaten zurück"] + C1["fetchAnalogInputsService.ts - wandelt in JSON"] + A1 --> B1 --> C1 + end -subgraph API - B1[getAnalogInputsHandler.ts] - A1 --> B1 -end - -subgraph Client - C1[fetchAnalogInputsService.ts] - D1[getAnalogInputsThunk.ts] - E1[React-Komponente: AnalogInputsDisplay] -end - -B1 --> C1 -C1 --> D1 -D1 --> E1 + subgraph JSON-Modus + A2["analogInputs.json - Mockdaten im JSON-Format"] + B2["/api/cpl/getAnalogInputsHandler.ts - gibt JSON direkt weiter"] + C2["fetchAnalogInputsService.ts - verarbeitet JSON"] + A2 --> B2 --> C2 + end + subgraph Production-Modus + A3["CPL Gerät via CGI - JS mit Platzhaltern (im public-Verzeichnis)"] + C3["fetchAnalogInputsService.ts - wandelt direkt JS in JSON"] + A3 --> C3 + end + C1 --> D["getAnalogInputsThunk.ts"] + C2 --> D + C3 --> D + D --> E["Redux Store und UI"] ``` --- -## 🧠 Beschreibung +## ✅ Vorteile dieser Struktur -- **JS-Datei** enthält `var win_analogInputsValues = [...]` usw. -- **API-Handler (`getAnalogInputsHandler.ts`)** importiert die Variablen und wandelt sie in eine JSON-Struktur um -- **Service (`fetchAnalogInputsService.ts`)** nutzt `fetch("/api/cpl/getAnalogInputsHandler")` und gibt JSON zurück -- **Thunk (`getAnalogInputsThunk.ts`)** ruft den Service auf und übergibt die Daten an Redux -- **Komponente (`AnalogInputsDisplay.tsx`)** nutzt `useSelector` zum Anzeigen +- 🔄 Austauschbare Datenquellen ohne Frontend-Codeänderung +- 🧼 Trennung von Datenformaten (JS, JSON, CGI) und deren Umwandlung +- 🧪 Mock-fähig für Entwickler und CI ohne Backend +- 🔮 Zukunftssicher für moderne embedded APIs mit echtem JSON --- -## ✅ Vorteile +## 📁 Verzeichnisstruktur (Auszug) -- 🔄 Austauschbare Datenquelle (`js`, `json`, `CGI`, `DB`) -- 🧼 Saubere Trennung von Technik (API) und Fachlogik (Service/Redux) -- 🔍 Leicht testbar, lokal entwickelbar +```txt +/mocks/device-cgi-simulator/SERVICE/*.js # jsmock-Modus +/mocks/api/SERVICE/*.json # json-Modus +/public/CPL/SERVICE/*.js # production-Modus (CGI-Daten im JS-Format) +/services/fetchAnalogInputsService.ts # verarbeitet Rückgabe zu JSON +/redux/thunks/getAnalogInputsThunk.ts # Redux-Thunk zur Übergabe +/components/AnalogInputsDisplay.tsx # Anzeige in der UI +``` diff --git a/package-lock.json b/package-lock.json index 517a30d..56dbc0d 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "cpl-v4", - "version": "1.6.440", + "version": "1.6.441", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "cpl-v4", - "version": "1.6.440", + "version": "1.6.441", "dependencies": { "@fontsource/roboto": "^5.1.0", "@iconify-icons/ri": "^1.2.10", diff --git a/package.json b/package.json index aedb44b..9513422 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "cpl-v4", - "version": "1.6.440", + "version": "1.6.441", "private": true, "scripts": { "dev": "next dev",