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