asdasd

WIDGET_INTEGRATION.md

@@ -0,0 +1,126 @@
+Projektkontext: Widget-Einbindung und Integrationen
+
+1) Zielbild
+- Nexus soll ein flexibles Dashboard-System im Stil moderner Startseitenlösungen werden.
+- Benutzer sollen eigene Dashboards anlegen, anordnen und konfigurieren können.
+- Inhalte auf Dashboards sollen aus internen Nexus-Funktionen, externen Integrationen und Seitenmodulen kommen können.
+
+2) Begriffe
+- `Dashboard`
+  - eine benutzerspezifische oder freigegebene Übersichtsseite
+- `Dashboard-Element`
+  - ein platzierbares Objekt innerhalb eines Dashboards
+- `Widget-Typ`
+  - beschreibt, welche Art Element gerendert wird
+- `Integration`
+  - zentrale Anbindung an ein externes System
+- `Seitenmodul`
+  - datengetriebenes, on-the-fly angelegtes Modul ohne eigenen Code-Ordner unter `/modules/`
+
+3) Anforderungen an Benutzer-Dashboards
+- jeder Benutzer soll mehrere eigene Dashboards anlegen können
+- jedes Dashboard braucht mindestens:
+  - Name
+  - Slug oder technische ID
+  - Eigentümer
+  - Sichtbarkeit
+  - Sortierung
+  - optional Standardstatus
+- Dashboards sollen perspektivisch auch teilbar sein:
+  - privat
+  - gruppenbasiert
+  - optional global sichtbar
+- ein Benutzer soll seine Dashboards selbst umsortieren, umbenennen, duplizieren und löschen können
+- Dashboard-Konfigurationen müssen datenbankbasiert gespeichert werden, nicht in Moduldateien
+
+4) Anforderungen an Dashboard-Layout und Editor
+- Dashboards müssen vom Benutzer flexibel bearbeitet werden können.
+- Jedes Dashboard-Element braucht mindestens:
+  - Spaltenbreite
+  - Höhe oder Zeilenspanne
+  - Position im Grid
+  - gerätespezifische Layoutdaten, sobald Mobile/Desktop getrennt unterstützt werden
+- der Editor soll ein frei konfigurierbares Grid unterstützen
+- Größen und Positionen müssen pro Element speicherbar sein
+- ein Wechsel zwischen Anzeige-Modus und Bearbeiten-Modus ist vorzusehen
+- das Layout-System dieses Editors ist globales Nexus-Kerngerüst und darf nicht in einzelnen Modulen dupliziert werden
+
+5) Widget-Typen V1
+- `link`
+  - einzelner Verweis zu einer internen oder externen Seite
+- `iframe`
+  - eingebettete Webseite oder Tool-Oberfläche
+- `bookmark_group`
+  - Sammlung mehrerer Links oder Schnellzugriffe
+- `external_status`
+  - kompakte Zustandsanzeige aus einer Integration
+- perspektivisch zusätzlich:
+  - Kennzahl
+  - Integrationsstatus
+  - Modulansicht im Kleinformat
+
+6) Integrationen als Kernsystem
+- Integrationen sind keine Module und keine Widgets, sondern eine eigene Systemschicht.
+- Eine Integration stellt Verbindung, Zugangsdaten, Basis-URL und technische Einstellungen für ein Fremdsystem bereit.
+- Widgets oder Seitenmodule greifen nicht direkt auf Rohkonfigurationen zu, sondern auf eine definierte Integration.
+- Zugangsdaten müssen zentral und getrennt von Widget-Konfigurationen gespeichert werden.
+- Eine Integration soll mehrfach anlegbar sein, zum Beispiel mehrere Home-Assistant- oder Pi-hole-Instanzen.
+- Integrationen müssen benennbar und für Benutzer oder Gruppen freigebbar sein.
+
+Beispiele für Integrationen:
+- Home Assistant
+- Pi-hole
+- Proxmox
+- Docker
+- Arr-Tools
+
+7) Seitenmodule on the fly
+- Ein Seitenmodul ist ein vom Benutzer oder Administrator angelegtes Objekt ohne eigenen Programmcode.
+- Seitenmodule sind Teil des Nexus-Kerngerüsts und nicht Teil des klassischen Modulordners.
+- Ein Seitenmodul kann mindestens folgende Typen haben:
+  - `link`
+  - `iframe`
+  - `bookmark_group`
+  - `external_status`
+- Seitenmodule sollen in Dashboards eingebunden werden können.
+- Seitenmodule sollen optional auch in der allgemeinen Nexus-Übersicht auftauchen können.
+- Seitenmodule dürfen keine globale CSS- oder Layoutlogik mitbringen; sie müssen auf dem zentralen Dashboard- und Widget-System aufsetzen.
+
+8) V1-Datenmodell
+- Für das generelle Nexus-System sollen neue zentrale Tabellen vorgesehen werden.
+- Empfohlene V1-Struktur:
+  - `nexus_dashboards`
+    - Dashboard-Metadaten
+  - `nexus_dashboard_items`
+    - platzierte Elemente pro Dashboard
+  - `nexus_integrations`
+    - technische Integrationen und Verbindungsdaten
+  - `nexus_page_modules`
+    - on-the-fly angelegte Seitenmodule
+  - `nexus_dashboard_shares`
+    - optionale Freigaben für Benutzer oder Gruppen
+- JSON-Konfigurationen sind für flexible Widget- oder Layoutoptionen erlaubt, aber Kerneigenschaften wie Eigentümer, Typ, Position und Sichtbarkeit sollen eigene Spalten behalten.
+
+9) Kollisionsschutz zu Modulen
+- Änderungen am Nexus-Kerngerüst dürfen nicht voraussetzen, dass bestehende Module sofort migriert werden.
+- Neue Tabellen, Services und Seiten müssen unter globalen Namen aufgebaut werden, nicht unter einem Modulpräfix.
+- Bestehende Modulrouten, Modul-Assets und Modul-Setups dürfen durch neue Dashboard-Funktionen nicht ersetzt werden.
+- Integrationen sind global zu denken und dürfen nicht als versteckte Modul-Features in einzelne Module eingestreut werden.
+- Wenn ein bestehendes Modul später Widgets für Dashboards anbietet, muss das über definierte Adapter oder Provider geschehen, nicht über direkte Eingriffe in das Modul-Layout.
+
+10) Empfohlene Umsetzungsreihenfolge
+- Phase 1:
+  - zentrale Begriffe und Datenmodelle festlegen
+  - globale Tabellen für Dashboards, Dashboard-Elemente, Integrationen und Seitenmodule einführen
+  - globale Seiten für Dashboard-Verwaltung anlegen
+- Phase 2:
+  - erstes Dashboard pro Benutzer
+  - einfacher Grid-Editor
+  - erste Widget-Typen `link`, `iframe`, `bookmark_group`
+- Phase 3:
+  - Integrationsverwaltung
+  - erste Integrationsadapter, zum Beispiel Home Assistant
+  - widgetfähige Abfrage von externen Daten
+- Phase 4:
+  - Freigaben, Gruppenrechte, Dashboard-Duplikate
+  - spätere optionale Anbindung bestehender Module über definierte Widget-Provider