diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md index 9a81853..cdbafaa 100644 --- a/PROJECT_CONTEXT.md +++ b/PROJECT_CONTEXT.md @@ -258,3 +258,141 @@ UTC-Speicherregel (VERBINDLICH): Nexus ist modular, mit strikter Trennung zwischen globalem Layout und modulspezifischem Code. Staging/Live haben eigene /app//config-Strukturen; /config/ im Repo wird beim Deployment kopiert. Modul-Assets gehören ausschließlich in den Modul-Ordner und werden dort geladen. + +14) Nexus-Kerngerüst und Dashboard-Zielbild (VERBINDLICH) +- Der aktuelle Ausbauschritt betrifft das generelle Nexus-System, nicht die bestehenden Fachmodule. +- Bestehende Module sind funktional und strukturell zunächst ausgenommen und dürfen durch Arbeiten am Kerngerüst nicht beeinträchtigt werden. +- Neue Kernfunktionen müssen deshalb so eingeführt werden, dass sie parallel zum bestehenden Modulsystem laufen können. +- Zielbild ist ein Nexus-Grundsystem mit flexiblen Benutzer-Dashboards, Integrationen und datengetriebenen Seitenmodulen. + +Produktprinzip: +- Nexus ist nicht nur Modul-Launcher, sondern ein persönliches und gruppenfähiges Dashboard-System. +- Benutzer sollen eigene Dashboards anlegen, anordnen und konfigurieren können. +- Inhalte auf Dashboards sollen aus drei Quellen kommen können: + - interne Nexus-Funktionen + - externe Integrationen + - einfache Seitenmodule ohne eigene Modul-Implementierung + +Abgrenzung zu bestehenden Modulen: +- Das bestehende Verzeichnis `/modules//` bleibt das Zuhause klassischer Nexus-Module. +- Das neue Dashboard-System ist ein zusätzliches globales Kernsystem. +- Ein Dashboard-Widget darf Daten aus einem Modul anzeigen, aber das Dashboard-System darf keine Modulstruktur voraussetzen oder überschreiben. +- Neue Kernfunktionen müssen ohne Umbau bestehender Module lauffähig sein. + +15) Neue globale Kernbausteine (VERBINDLICH) +- `Dashboard` + - Eine benutzerspezifische oder freigegebene Übersichtsseite. + - Ein Benutzer kann mehrere Dashboards besitzen. + - Ein Dashboard kann als Standard-Dashboard markiert sein. +- `Dashboard-Element` + - Ein platzierbares Objekt innerhalb eines Dashboards. + - Eigenschaften sind mindestens Typ, Position, Größe, Sichtbarkeit und Konfiguration. +- `Widget-Typ` + - Beschreibt, welche Art Element gerendert wird. + - Beispiele: + - Kennzahl + - Link-/Bookmark-Gruppe + - iFrame/Webseite + - Integrationsstatus + - Modulansicht im Kleinformat +- `Integration` + - Zentrale Anbindung an ein externes System. + - Beispiele: + - Home Assistant + - Pi-hole + - Proxmox + - Docker + - Arr-Tools +- `Seitenmodul` + - Ein datengetriebenes, on-the-fly angelegtes Modul ohne eigenen Code-Ordner unter `/modules/`. + - Typische Verwendung: + - externer Link + - eingebettete Webseite + - einfache Startseite für ein Tool + +16) 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. + +17) 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. + +18) Integrationen als globales 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, z.B. mehrere Home-Assistant- oder Pi-hole-Instanzen. +- Integrationen müssen benennbar und für Benutzer oder Gruppen freigebbar sein. + +19) 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-/Widget-System aufsetzen. + +20) V1-Datenmodell für das Kerngerüst +- 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. + +21) Kollisionsschutz zu Modulen (VERBINDLICH) +- Ä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. + +22) Empfohlene Umsetzungsreihenfolge für das Kerngerüst +- 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, z.B. Home Assistant + - widgetfähige Abfrage von externen Daten +- Phase 4: + - Freigaben, Gruppenrechte, Dashboard-Duplikate + - spätere optionale Anbindung bestehender Module über definierte Widget-Provider diff --git a/README.md b/README.md index ce6fac4..7af036a 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,32 @@ Technisch: - bei Layout-Checks ist ausdrücklich zu prüfen, ob `Main-Header -> Submenü -> erste Section/Card` denselben Rhythmus hat wie auf Referenzseiten - die Optik von Submenü-Aktionen kommt ausschließlich aus dem globalen CSS; Module sollen dort keine eigenen Farbvarianten definieren +## Nexus-Kerngerüst + +Das generelle Nexus-System wird unabhängig von den bestehenden Fachmodulen weiterentwickelt. Aktuell gilt: + +- bestehende Module unter `modules//` bleiben zunächst unberührt +- neue Kernfunktionen müssen kollisionsfrei parallel zum Modulsystem aufgebaut werden +- Zielbild ist ein flexibles Dashboard-System im Stil moderner Startseitenlösungen mit: + - mehreren Dashboards pro Benutzer + - frei platzierbaren Dashboard-Elementen + - zentralen Integrationen zu Fremdsystemen + - datengetriebenen Seitenmodulen ohne eigenen Modulordner + +Die maßgeblichen Begriffe und Regeln dafür stehen in `PROJECT_CONTEXT.md`: + +- `Dashboard` +- `Dashboard-Element` +- `Widget-Typ` +- `Integration` +- `Seitenmodul` + +Wichtig: + +- Integrationen sind globale Systembausteine, keine Module +- Seitenmodule sind on the fly konfigurierbare Inhalte ohne Code unter `modules/` +- spätere Dashboard-Anbindungen bestehender Module sollen nur über definierte Adapter oder Provider erfolgen + ## Getting started