nexus/WIDGET_INTEGRATION.md

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