asdasd
This commit is contained in:
@@ -1,4 +1,5 @@
|
||||
Bitte PROJECT_CONTEXT.md lesen und strikt einhalten.
|
||||
Bitte `PROJECT_CONTEXT.md` lesen und strikt einhalten.
|
||||
Für Modul-Arbeiten zusätzlich immer `MODULE_DEVELOPMENT.md` lesen und beachten.
|
||||
Wichtig: Modul-spezifischer Code/Assets ausschließlich unter /modules/<modul>/,
|
||||
keine Änderungen an /public/assets/* für modul-spezifische Features.
|
||||
Staging/Live: /config/<env> im Repo wird nach /app/<env>/config kopiert.
|
||||
|
||||
154
MODULE_DEVELOPMENT.md
Normal file
154
MODULE_DEVELOPMENT.md
Normal file
@@ -0,0 +1,154 @@
|
||||
Projektkontext: Modul-Entwicklung
|
||||
|
||||
1) Modul-Konzept
|
||||
- Jedes klassische Modul lebt unter `/modules/<modulname>/`.
|
||||
- Pflicht-Dateien sind in der Regel:
|
||||
- `module.json`
|
||||
- `bootstrap.php`
|
||||
- `pages/*.php`
|
||||
- `assets/*`
|
||||
|
||||
2) Modulspezifische Assets
|
||||
- Modul-JS und Modul-CSS müssen im Modul-Ordner liegen.
|
||||
- Laden über Modul-Assets, zum Beispiel:
|
||||
- `$assets->addStyle('/module/pi_control/asset?file=pi_control.css');`
|
||||
- `$assets->addScript('/module/pi_control/asset?file=hosts.js', 'footer', true);`
|
||||
- Keine modulspezifischen Änderungen in `/public/assets/*`.
|
||||
|
||||
3) Scope-Regeln
|
||||
- Modul-Aufgaben: nur `/modules/<modul>/` und gegebenenfalls `/tools/<modul>` ändern
|
||||
- globale Layouts: `/partials/structure/` und `/public/assets/css/app.css`
|
||||
- Konfigurationslogik nur bei echtem Globalbedarf in `/config/` oder `/src/`
|
||||
|
||||
4) UI-Regeln für Module
|
||||
- Modulseiten sollen diesem Muster folgen:
|
||||
- Seitenheader-Box
|
||||
- Submenü-Box
|
||||
- danach Bereichs-Boxen und/oder Karten-Boxen
|
||||
- `Setup` gehört in Modulen grundsätzlich in die Submenü-Box
|
||||
- die Optik von Submenü-Aktionen kommt ausschließlich aus dem globalen CSS
|
||||
- Module dürfen dort keine eigenen Farb- oder Variantenlogiken einschleusen
|
||||
|
||||
5) Globales Setup-System
|
||||
- Modul-Setup wird zentral über `partials/landingpages/modules/setup.php` gerendert.
|
||||
- Die Bereiche
|
||||
- `Allgemein`
|
||||
- `Datenbank`
|
||||
- `Zugriffsrechte`
|
||||
- `Cron Einstellungen`
|
||||
müssen für alle Module aus dieser gemeinsamen Setup-Logik kommen.
|
||||
- Nur `Custom Settings` darf modulspezifischen Inhalt enthalten.
|
||||
- Modul-spezifische Sonderlayouts für die Bereiche `Allgemein`, `Datenbank`, `Zugriffsrechte` oder `Cron Einstellungen` sind nicht erlaubt.
|
||||
|
||||
Was global im Setup bereits verfügbar ist:
|
||||
- gemeinsame Setup-Navigation mit festen Unterseiten
|
||||
- rechte Aktionsseite mit
|
||||
- `Nexus Übersicht`
|
||||
- `Zurück zum Modul`
|
||||
- gemeinsames Speichern pro Bereich
|
||||
- gemeinsames Rendering von
|
||||
- Textfeldern
|
||||
- Zahlenfeldern
|
||||
- Checkboxen
|
||||
- Selects
|
||||
- Multiselects
|
||||
- Textareas
|
||||
- globale `Debug aktivieren`-Option pro Modul im Bereich `Allgemein`
|
||||
- gemeinsame Datenbank-Logik mit
|
||||
- `Eigene Modul-DB nutzen`
|
||||
- Anzeige oder Verbergen der Custom-DB-Felder
|
||||
- optional mehreren DB-Gruppen wie `db.*` und `metadata_db.*`
|
||||
- `Verbindung testen`
|
||||
- `Standardwerte laden`
|
||||
- gemeinsame Auth- und Zugriffslogik mit
|
||||
- `Login erforderlich`
|
||||
- erlaubten Benutzern
|
||||
- erlaubten Gruppen
|
||||
- bekannten Keycloak-Benutzern und -Gruppen
|
||||
- gemeinsame Cron- und Scheduler-Logik mit
|
||||
- Anzeige von Intervall-Tasks
|
||||
- Anzeige von Cron-Jobs
|
||||
- Bearbeiten von Cron-Einträgen im Modal
|
||||
- Cron-Test direkt aus dem Setup
|
||||
- Mehrfacheinträgen bei `mode = multi`
|
||||
- Modul-Zeitzonen-Override für Crons
|
||||
- Vererbung globaler Cron-Zeitzonen-Defaults
|
||||
- gemeinsame Darstellung von Setup-Aktionen und Statusblöcken
|
||||
- globale Zeitzonen-Datalist aus `nexus_timezones`
|
||||
|
||||
6) Was ein Modul für das Setup liefern darf
|
||||
- `module.json` mit `setup.fields`
|
||||
- optional `setup.sections.database`
|
||||
- optional `interval_tasks`
|
||||
- optional `scheduler_jobs`
|
||||
- optional `auth`
|
||||
- optional Bootstrap-Funktionen:
|
||||
- `setup_actions`
|
||||
- `run_setup_action`
|
||||
- `setup_status`
|
||||
- `runtime_settings`
|
||||
- `save_runtime_settings`
|
||||
|
||||
7) Was ein Modul nicht selbst bauen darf
|
||||
- eigene Setup-Seitenstruktur für `Allgemein`, `Datenbank`, `Zugriffsrechte`, `Cron Einstellungen`
|
||||
- eigene DB-Toggle-Logik für Standard und Custom
|
||||
- eigene Cron-Editor-Grundlogik
|
||||
- eigene Debug-UI-Grundlogik
|
||||
- eigene globale Zeitzonen-Defaults
|
||||
|
||||
8) Setup-Navigation
|
||||
- Setup-Routen laufen zentral über:
|
||||
- `/modules/setup/<modul>/general`
|
||||
- `/modules/setup/<modul>/database`
|
||||
- `/modules/setup/<modul>/access`
|
||||
- `/modules/setup/<modul>/cron`
|
||||
- `/modules/setup/<modul>/custom`
|
||||
- `Setup` gehört in der Modulansicht in die rechte Aktionsseite der Submenü-Box
|
||||
|
||||
9) Steuerung per `module.json`
|
||||
- Ein Modul kann über `setup.sections.database: true|false` steuern, ob der Menüpunkt `Datenbank` angezeigt wird.
|
||||
- Wenn `setup.sections.database` fehlt, kann die zentrale Setup-Logik den Punkt implizit aktivieren, sobald DB-Felder vorhanden sind.
|
||||
- Modulfelder für `Allgemein`, `Datenbank`, `Cron` und `Custom Settings` werden zentral nach Feldnamen aufgeteilt:
|
||||
- `debug_enabled` -> `Allgemein`
|
||||
- `use_separate_db` und `db.*` oder `metadata_db.*` -> `Datenbank`
|
||||
- `schedule_timezone` -> `Cron Einstellungen`
|
||||
- alle übrigen Setup-Felder -> `Custom Settings`
|
||||
|
||||
Weitere anerkannte Setup-Bausteine:
|
||||
- `interval_tasks`
|
||||
- `scheduler_jobs`
|
||||
- `auth`
|
||||
- `db_defaults`
|
||||
- `metadata_db_defaults`
|
||||
|
||||
10) Speicherregel
|
||||
- Beim Speichern eines Setup-Bereichs dürfen nur die in diesem Bereich sichtbaren Felder aktualisiert werden.
|
||||
- Felder aus anderen Bereichen dürfen nicht mit `null`, `0` oder leeren Strings überschrieben werden.
|
||||
|
||||
11) Datenbankbereich
|
||||
- `Eigene Modul-DB nutzen` ist der zentrale Standard-Schalter für Module mit optionaler eigener DB.
|
||||
- Wenn der Schalter deaktiviert ist, dürfen keine Custom-DB-Eingabefelder sichtbar sein.
|
||||
- Datenbankaktionen und Tabellenstatus gehören in den Menüpunkt `Datenbank`, nicht in `Custom Settings`.
|
||||
|
||||
12) Globale PHP-Helfer für Module
|
||||
- Neue Module sollen für zentrale Zeit- und Debug-Defaults nach Möglichkeit die globalen Funktionen aus `src/App/functions.php` nutzen:
|
||||
- `nexus_settings()`
|
||||
- `nexus_save_settings(array $settings)`
|
||||
- `nexus_system_timezone_name()`
|
||||
- `nexus_display_timezone_name()`
|
||||
- `nexus_cron_timezone_name()`
|
||||
- `module_debug_enabled(string $module)`
|
||||
- `module_debug_push(string $module, array $entry)`
|
||||
- `module_debug_clear(string $module)`
|
||||
|
||||
13) Regeln für neue Module
|
||||
- Keine Zeitzone wie `Europe/Berlin` hart im Modul als Standard erzwingen, wenn dafür ein globaler Nexus-Default existiert.
|
||||
- Für Anzeige- und Formatierungslogik nach Möglichkeit `nexus_display_timezone_name()` nutzen.
|
||||
- Für Cron-Fallbacks nach Möglichkeit `nexus_cron_timezone_name()` nutzen.
|
||||
- Neue Module dürfen keine lokalen Zeitzonen direkt in Datenbank-Zeitspalten persistieren.
|
||||
|
||||
14) Pi-Control-Besonderheiten
|
||||
- Worker und Jobs unter `/tools/pi_control/`
|
||||
- Check-Updates und Cron nutzen die gleichen SSH-Routinen
|
||||
- Host-Karten, Befehle und Konsole sind UI im Modul
|
||||
- Update- und Upgrade-Checks liefern Debug-Ausgaben, die als Tooltip oder Debugzeile angezeigt werden
|
||||
119
NEXUS_SYSTEM.md
Normal file
119
NEXUS_SYSTEM.md
Normal file
@@ -0,0 +1,119 @@
|
||||
Projektkontext: Nexus-System
|
||||
|
||||
1) Projekt-Zweck und Ziel
|
||||
- Nexus ist ein zentrales, webbasiertes Admin-Interface zur Steuerung einer dynamischen IT-Infrastruktur.
|
||||
- Module kapseln fachliche Funktionen, das Nexus-System stellt das globale Grundgerüst bereit.
|
||||
- Das generelle Nexus-System wird unabhängig von den bestehenden Fachmodulen weiterentwickelt.
|
||||
|
||||
2) Umgebungen und Domains
|
||||
- Live: `nexus.kusche.berlin`
|
||||
- Staging: `staging.nexus.kusche.berlin`
|
||||
|
||||
Container- und Deploy-Layout:
|
||||
- `/app/live/` -> Live-Code
|
||||
- `/app/staging/` -> Staging-Code
|
||||
- jeweils mit eigenem `config`-Unterordner:
|
||||
- `/app/live/config/`
|
||||
- `/app/staging/config/`
|
||||
|
||||
Repo-Layout zu Configs:
|
||||
- `/config/live/` und `/config/staging/` liegen im Repo
|
||||
- beim Deployment werden die Dateien daraus nach `/app/<env>/config` kopiert
|
||||
- wichtig: im laufenden Container existiert `/app/config/` nicht, sondern nur `/app/live/config` und `/app/staging/config`
|
||||
|
||||
3) Verzeichnisstruktur
|
||||
- `/public/` -> Web Root mit globalen Assets
|
||||
- `/api/` -> Backend- und API-Endpunkte
|
||||
- `/src/` -> PHP-Kernklassen und Utilities
|
||||
- `/tools/` -> CLI, Worker und Jobs
|
||||
- `/config/` -> Umgebungs-Configs
|
||||
- `/modules/<modul>/` -> klassische Nexus-Module
|
||||
- `/partials/structure/` -> Header, Footer, Menüs
|
||||
- `/partials/landingpages/` -> komplette Seitenlayouts
|
||||
- `/debug/` -> Custom Logs
|
||||
|
||||
4) Code-Änderungen nach Scope
|
||||
- globale Layouts: `/partials/structure/` und `/public/assets/css/app.css`
|
||||
- Konfigurationslogik: nur wenn nötig `/config/` und `/src/`
|
||||
- Modul-Aufgaben: nur `/modules/<modul>/` und gegebenenfalls `/tools/<modul>`
|
||||
|
||||
5) UI-Naming und Seitenaufbau
|
||||
- `Seitenheader-Box`: oberste globale Header-Box mit Seitentitel, Login und Farbschema
|
||||
- `Submenü-Box`: Box direkt unter der Seitenheader-Box für modul- oder seitenbezogene Aktionen
|
||||
- `Submenü-Aktionen`: rechtsbündige Zusatzbuttons innerhalb der Submenü-Box, z.B. `Setup` oder `Nexus Übersicht`
|
||||
- `Bereichs-Box`: größere Inhaltsbox für einen zusammenhängenden Seitenbereich
|
||||
- `Karten-Box`: kleinere Karte auf derselben Ebene wie Bereichs-Boxen, meist in Grids
|
||||
|
||||
Zentrale CSS-Klassen:
|
||||
- `main-header-box`
|
||||
- `submenu-box`
|
||||
- `module-submenu-actions`
|
||||
- `section-box`
|
||||
- `card-box`
|
||||
|
||||
Globale Struktur:
|
||||
- zuerst Seitenheader-Box
|
||||
- danach Submenü-Box
|
||||
- danach Bereichs-Boxen und/oder Karten-Boxen je nach Seite
|
||||
|
||||
Layout-Regeln:
|
||||
- vertikale Abstände zwischen `main-header-box`, `submenu-box` und den ersten Folge-Boxen müssen aus der globalen Shell kommen
|
||||
- maßgeblich sind `module-page-bg` und `module-page-stack` in `public/assets/css/app.css`
|
||||
- Top-Level-Wrapper wie Grids, Kartencontainer oder Modul-Listen dürfen keinen zusätzlichen `margin-top` oder Sonder-Gap erzeugen, der den Abstand nach dem Submenü verändert
|
||||
- bei Layout-Reviews ist explizit zu prüfen, ob `Main-Header -> Submenü -> erste Section/Card` optisch denselben Rhythmus hat wie auf Referenzseiten
|
||||
- die Optik der Submenü-Aktionsbuttons kommt ausschließlich aus dem globalen CSS
|
||||
|
||||
Beispielstruktur:
|
||||
- Börsenchecker: Seitenheader-Box, Submenü-Box, Bereichs-Box, Karten-Boxen, Bereichs-Box
|
||||
- FX-Rates: Seitenheader-Box, Submenü-Box, danach Bereichs-Boxen
|
||||
- Mining-Checker: Seitenheader-Box, Submenü-Box, Bereichs-Box, Karten-Boxen, Karten-Boxen, Bereichs-Box
|
||||
- Modulverwaltung: Seitenheader-Box, Submenü-Box, danach Karten-Boxen
|
||||
|
||||
6) Nexus-Kerngerüst
|
||||
- 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 parallel zum bestehenden Modulsystem eingeführt werden.
|
||||
- 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 Verzeichnis `/modules/<modul>/` bleibt das Zuhause klassischer Nexus-Module
|
||||
- das Dashboard-System ist ein zusätzliches globales Kernsystem
|
||||
- neue Kernfunktionen müssen ohne Umbau bestehender Module lauffähig sein
|
||||
|
||||
7) Globale Zeitzonen-Logik
|
||||
- globale Nexus-Einstellungen liegen unter `/settings`
|
||||
- dort werden zentral gepflegt:
|
||||
- `Anzeige-Zeitzone`
|
||||
- `Standard-Zeitzone für Crons`
|
||||
|
||||
Regeln:
|
||||
- ohne Custom bei der Anzeige-Zeitzone wird die System-Zeitzone verwendet
|
||||
- die aktive Anzeige-Zeitzone soll angezeigt werden
|
||||
- die Standard-Zeitzone für Crons ist der globale Default für Modul-Crons
|
||||
- Module dürfen diese Zeitzone im Setup übersteuern
|
||||
- einzelne Cron-Einträge dürfen sie ebenfalls übersteuern
|
||||
|
||||
UTC-Speicherregel:
|
||||
- Zeitwerte sollen projektweit intern immer in `UTC` gespeichert werden
|
||||
- Anzeige-Zeitzonen dienen nur der Darstellung für Benutzer
|
||||
- Cron-Zeitzonen dienen nur der lokalen Auswertung von Zeitplänen und Fälligkeiten
|
||||
- beim Einlesen lokaler Eingaben muss vor dem Speichern nach `UTC` normalisiert werden
|
||||
- beim Anzeigen gespeicherter Werte muss von `UTC` in die jeweils wirksame Anzeige-Zeitzone umgerechnet werden
|
||||
|
||||
8) Globales Debug-System
|
||||
- das Debug-Popup ist eine globale Infrastruktur aus dem zentralen Layout
|
||||
- die Aktivierung bleibt pro Modul über `debug_enabled` im Modul-Setup steuerbar
|
||||
- das Debug-Symbol darf nur sichtbar sein, wenn für das aktuelle Modul Debug aktiv ist
|
||||
- Module sollen keine eigene separate Debug-Oberfläche bauen, wenn der globale Debug-Stream genutzt werden kann
|
||||
|
||||
9) Sicherheits- und Netzwerk-Constraints
|
||||
- Zugriff im Heimnetz `192.168.178.0/24` per Nginx begrenzt
|
||||
- SSH-Hosts nur Heimnetz
|
||||
@@ -1,398 +1,41 @@
|
||||
Projekt-Zusammenfassung: Nexus Control Panel
|
||||
|
||||
1) Projekt-Zweck & Ziel
|
||||
Nexus ist ein zentrales, webbasiertes Admin-Interface zur Steuerung einer dynamischen IT-Infrastruktur.
|
||||
Module kapseln fachliche Funktionen (z.B. KEA DHCP, Pi Control).
|
||||
Diese Datei ist ab jetzt der zentrale Einstieg und verweist auf die drei maßgeblichen Dokumentationsbereiche.
|
||||
|
||||
2) Aktive Module (Kurzüberblick)
|
||||
- KEA DHCP: Verwaltung von Hosts/Leases, Statische Reservierungen, Metadaten.
|
||||
- Pi Control: Verwaltung von SSH-Hosts, Befehle/Preset, Konsole, Host-Status, Update/Upgrade-Checks.
|
||||
1) Nexus-System
|
||||
- Datei: [NEXUS_SYSTEM.md](NEXUS_SYSTEM.md)
|
||||
- Inhalt:
|
||||
- globales Grundgerüst von Nexus
|
||||
- Umgebungen, Verzeichnisstruktur und globale Scope-Regeln
|
||||
- UI-Naming mit Seitenheader-Box, Submenü-Box, Bereichs-Box und Karten-Box
|
||||
- globale Zeitzonen- und Debug-Regeln
|
||||
- Kerngerüst für das zukünftige Dashboard-System
|
||||
|
||||
3) Umgebungen & Domains
|
||||
- Live: nexus.kusche.berlin
|
||||
- Staging: staging.nexus.kusche.berlin
|
||||
2) Modul-Entwicklung
|
||||
- Datei: [MODULE_DEVELOPMENT.md](MODULE_DEVELOPMENT.md)
|
||||
- Inhalt:
|
||||
- Regeln für klassische Module unter `/modules/<modul>/`
|
||||
- Setup-System und zulässige Modulbausteine
|
||||
- globale Vorgaben für Modul-Layouts, Assets und Helper
|
||||
- Abgrenzung zwischen Modul-Code und globalem Nexus-System
|
||||
|
||||
Container/Deploy-Layout:
|
||||
- /app/live/ -> Live-Code
|
||||
- /app/staging/ -> Staging-Code
|
||||
- Jeweils mit eigenem /config-Unterordner:
|
||||
- /app/live/config/
|
||||
- /app/staging/config/
|
||||
3) Widget-Einbindung und Integrationen
|
||||
- Datei: [WIDGET_INTEGRATION.md](WIDGET_INTEGRATION.md)
|
||||
- Inhalt:
|
||||
- Benutzer-Dashboards
|
||||
- Dashboard-Elemente und Widget-Typen
|
||||
- Integrationen zu Fremdsystemen
|
||||
- on-the-fly Seitenmodule
|
||||
- Kollisionsschutz zu bestehenden Modulen
|
||||
- empfohlene Umsetzungsphasen
|
||||
|
||||
Repo-Layout zu Configs:
|
||||
- /config/live/ und /config/staging/ liegen im Repo.
|
||||
- Beim Deployment werden die Dateien daraus nach /app/<env>/config kopiert.
|
||||
- WICHTIG: Im laufenden Container existiert /app/config/ NICHT, sondern nur /app/live/config und /app/staging/config.
|
||||
4) Wichtige Leitplanken
|
||||
- Änderungen am generellen Nexus-System dürfen nicht in bestehende Module eingreifen, wenn das nicht ausdrücklich verlangt ist.
|
||||
- Klassische Fachmodule und das neue Dashboard- oder Widget-System sind getrennte Ebenen.
|
||||
- Modulspezifische Assets gehören weiterhin ausschließlich in den jeweiligen Modulordner.
|
||||
- Globale Layout- und Designregeln bleiben zentral in `public/assets/css/app.css` und den globalen Partials.
|
||||
|
||||
4) Verzeichnisstruktur (Repo)
|
||||
- /public/ -> Web Root (index.php, globale Assets)
|
||||
- /api/ -> Backend/API-Endpunkte
|
||||
- /src/ -> PHP-Kernklassen/Utilities
|
||||
- /tools/ -> CLI/Worker/Jobs (z.B. tools/pi_control)
|
||||
- /config/ -> Umgebungs-Configs (live/staging)
|
||||
- /modules/<modul>/ -> Module (Pages, Assets, Bootstrap)
|
||||
- /partials/structure/ -> Header/Footer/Menüs
|
||||
- /partials/landingpages/ -> Komplette Seitenlayouts
|
||||
- /debug/ -> Custom Logs
|
||||
|
||||
5) Modul-Konzept (WICHTIG)
|
||||
- Jedes Modul lebt unter /modules/<modulname>/.
|
||||
- Pflicht-Dateien i.d.R.:
|
||||
- module.json
|
||||
- bootstrap.php (Schema/Setup)
|
||||
- pages/*.php (UI/Endpoints)
|
||||
- assets/* (modulspezifisches CSS/JS)
|
||||
|
||||
Modulspezifische Assets:
|
||||
- Modul-JS/CSS MUSS im Modul-Ordner liegen.
|
||||
- Laden über Modul-Assets, z.B.:
|
||||
- $assets->addStyle('/module/pi_control/asset?file=pi_control.css');
|
||||
- $assets->addScript('/module/pi_control/asset?file=hosts.js', 'footer', true);
|
||||
- KEINE modulspezifischen Änderungen in /public/assets/*.
|
||||
|
||||
6) Code-Änderungen nach Scope
|
||||
- Modul-Aufgaben: nur /modules/<modul>/ + ggf. /tools/<modul> ändern.
|
||||
- Globale Layouts: /partials/structure und /public/assets/css/app.css.
|
||||
- Konfigurationslogik: nur wenn nötig /config/ und /src/.
|
||||
|
||||
7) UI-Naming und Seitenaufbau
|
||||
- `Seitenheader-Box`: oberste globale Header-Box mit Seitentitel, Login und Farbschema.
|
||||
- `Submenü-Box`: Box direkt unter der Seitenheader-Box für modul- oder seitenbezogene Aktionen.
|
||||
- `Submenü-Aktionen`: rechtsbündige Zusatzbuttons innerhalb der Submenü-Box, z.B. `Setup`, `Nexus Übersicht` oder `Zur Startseite`-Ersatz.
|
||||
- `Bereichs-Box`: größere Inhaltsbox für einen zusammenhängenden Seitenbereich.
|
||||
- `Karten-Box`: kleinere Karte auf derselben Ebene wie Bereichs-Boxen, meist in Grids.
|
||||
- Zentrale CSS-Klassen:
|
||||
- `main-header-box`
|
||||
- `submenu-box`
|
||||
- `module-submenu-actions`
|
||||
- `section-box`
|
||||
- `card-box`
|
||||
- Modulseiten sollen diesem Muster folgen:
|
||||
- zuerst Seitenheader-Box
|
||||
- danach Submenü-Box
|
||||
- danach Bereichs-Boxen und/oder Karten-Boxen je nach Modul
|
||||
- Vertikale Abstände zwischen `main-header-box`, `submenu-box` und den ersten Folge-Boxen muessen aus der globalen Shell kommen.
|
||||
- Maßgeblich sind `module-page-bg` und `module-page-stack` in `public/assets/css/app.css`.
|
||||
- Top-Level-Wrapper wie Grids, Kartencontainer oder Modul-Listen duerfen keinen eigenen zusaetzlichen `margin-top` oder Sonder-Gap erzeugen, der den Abstand nach dem Submenue veraendert.
|
||||
- Bei Layout-Reviews ist explizit zu pruefen, ob `Main-Header -> Submenue -> erste Section/Card` optisch denselben Rhythmus hat wie auf Referenzseiten wie dem Boersenchecker.
|
||||
- `Setup` gehört in Modulen grundsätzlich in die Submenü-Box.
|
||||
- In Verwaltungsseiten soll `Nexus Übersicht` als fester Button in den Submenü-Aktionen vorhanden sein.
|
||||
- Die Optik der Submenü-Aktionsbuttons kommt ausschließlich aus dem globalen CSS. Module sollen dort keine eigenen Farb- oder Variantenlogiken einschleusen.
|
||||
- Beispielstruktur:
|
||||
- Börsenchecker: Seitenheader-Box, Submenü-Box, Bereichs-Box, Karten-Boxen, Bereichs-Box
|
||||
- FX-Rates: Seitenheader-Box, Submenü-Box, danach Bereichs-Boxen
|
||||
- Mining-Checker: Seitenheader-Box, Submenü-Box, Bereichs-Box, Karten-Boxen, Karten-Boxen, Bereichs-Box
|
||||
- Modulverwaltung: Seitenheader-Box, Submenü-Box, danach Karten-Boxen
|
||||
|
||||
8) Globales Setup-System (VERBINDLICH)
|
||||
- Modul-Setup wird zentral über `partials/landingpages/modules/setup.php` gerendert.
|
||||
- Die Bereiche
|
||||
- `Allgemein`
|
||||
- `Datenbank`
|
||||
- `Zugriffsrechte`
|
||||
- `Cron Einstellungen`
|
||||
muessen fuer alle Module aus dieser gemeinsamen Setup-Logik kommen.
|
||||
- Nur `Custom Settings` darf modulspezifischen Inhalt enthalten.
|
||||
- Modul-spezifische Sonderlayouts fuer die Bereiche `Allgemein`, `Datenbank`, `Zugriffsrechte` oder `Cron Einstellungen` sind nicht erlaubt.
|
||||
- Wenn sich das Verhalten eines dieser Bereiche ändert, muss die Änderung zentral erfolgen, so dass sie automatisch fuer alle Module gilt.
|
||||
|
||||
Was global im Setup bereits verfügbar ist:
|
||||
- gemeinsame Setup-Navigation mit festen Unterseiten
|
||||
- rechte Aktionsseite mit
|
||||
- `Nexus Übersicht`
|
||||
- `Zurück zum Modul`
|
||||
- gemeinsames Speichern pro Bereich
|
||||
- gemeinsames Rendering von
|
||||
- Textfeldern
|
||||
- Zahlenfeldern
|
||||
- Checkboxen
|
||||
- Selects
|
||||
- Multiselects
|
||||
- Textareas
|
||||
- globale `Debug aktivieren`-Option pro Modul im Bereich `Allgemein`
|
||||
- gemeinsame Datenbank-Logik mit
|
||||
- `Eigene Modul-DB nutzen`
|
||||
- Anzeige/Verbergen der Custom-DB-Felder
|
||||
- optional mehreren DB-Gruppen wie `db.*` und `metadata_db.*`
|
||||
- `Verbindung testen`
|
||||
- `Standardwerte laden`
|
||||
- gemeinsame Auth-/Zugriffslogik mit
|
||||
- `Login erforderlich`
|
||||
- erlaubten Benutzern
|
||||
- erlaubten Gruppen
|
||||
- bekannten Keycloak-Benutzern und -Gruppen
|
||||
- gemeinsame Cron-/Scheduler-Logik mit
|
||||
- Anzeige von Intervall-Tasks
|
||||
- Anzeige von Cron-Jobs
|
||||
- Bearbeiten von Cron-Einträgen im Modal
|
||||
- Cron-Test direkt aus dem Setup
|
||||
- Mehrfacheinträgen bei `mode = multi`
|
||||
- Modul-Zeitzonen-Override fuer Crons
|
||||
- Vererbung globaler Cron-Zeitzonen-Defaults
|
||||
- gemeinsame Darstellung von Setup-Aktionen und Statusblöcken
|
||||
- globale Zeitzonen-Datalist aus `nexus_timezones`
|
||||
|
||||
Was ein Modul für das Setup nur noch liefern muss:
|
||||
- `module.json` mit `setup.fields`
|
||||
- optional `setup.sections.database`
|
||||
- optional `interval_tasks`
|
||||
- optional `scheduler_jobs`
|
||||
- optional `auth`
|
||||
- optional Bootstrap-Funktionen:
|
||||
- `setup_actions`
|
||||
- `run_setup_action`
|
||||
- `setup_status`
|
||||
- `runtime_settings`
|
||||
- `save_runtime_settings`
|
||||
|
||||
Was nicht mehr jedes Modul selbst bauen darf:
|
||||
- eigene Setup-Seitenstruktur fuer `Allgemein`, `Datenbank`, `Zugriffsrechte`, `Cron Einstellungen`
|
||||
- eigene DB-Toggle-Logik fuer Standard/Custom
|
||||
- eigene Cron-Editor-Grundlogik
|
||||
- eigene Debug-UI-Grundlogik
|
||||
- eigene globale Zeitzonen-Defaults
|
||||
|
||||
Setup-Navigation:
|
||||
- Setup-Routen laufen zentral ueber:
|
||||
- `/modules/setup/<modul>/general`
|
||||
- `/modules/setup/<modul>/database`
|
||||
- `/modules/setup/<modul>/access`
|
||||
- `/modules/setup/<modul>/cron`
|
||||
- `/modules/setup/<modul>/custom`
|
||||
- `Setup` gehoert in der Modulansicht in die rechte Aktionsseite der Submenü-Box.
|
||||
|
||||
Steuerung per `module.json`:
|
||||
- Ein Modul kann ueber `setup.sections.database: true|false` steuern, ob der Menüpunkt `Datenbank` angezeigt wird.
|
||||
- Wenn `setup.sections.database` fehlt, kann die zentrale Setup-Logik den Punkt implizit aktivieren, sobald DB-Felder vorhanden sind.
|
||||
- Modulfelder fuer `Allgemein`, `Datenbank`, `Cron` und `Custom Settings` werden zentral nach Feldnamen aufgeteilt:
|
||||
- `debug_enabled` -> `Allgemein`
|
||||
- `use_separate_db` und `db.*` / `metadata_db.*` -> `Datenbank`
|
||||
- `schedule_timezone` -> `Cron Einstellungen`
|
||||
- alle übrigen Setup-Felder -> `Custom Settings`
|
||||
|
||||
Weitere anerkannte Setup-Bausteine:
|
||||
- `interval_tasks`
|
||||
- fuer automatische Aufgaben beim Modulaufruf
|
||||
- `scheduler_jobs`
|
||||
- fuer zentrale Cron-Jobs ueber den Nexus-Scheduler
|
||||
- `auth`
|
||||
- fuer den initialen Modulschutz
|
||||
- `db_defaults`
|
||||
- fuer vorbefuellte Standard-DB-Werte im Datenbankbereich
|
||||
- `metadata_db_defaults`
|
||||
- fuer weitere globale DB-Gruppen im Datenbankbereich
|
||||
|
||||
Speicherregel:
|
||||
- Beim Speichern eines Setup-Bereichs duerfen nur die in diesem Bereich sichtbaren Felder aktualisiert werden.
|
||||
- Felder aus anderen Bereichen duerfen nicht mit `null`, `0` oder leeren Strings ueberschrieben werden.
|
||||
|
||||
Datenbankbereich:
|
||||
- `Eigene Modul-DB nutzen` ist der zentrale Standard-Schalter fuer Module mit optionaler eigener DB.
|
||||
- Wenn der Schalter deaktiviert ist, duerfen keine Custom-DB-Eingabefelder sichtbar sein.
|
||||
- Datenbankaktionen und Tabellenstatus gehoeren in den Menüpunkt `Datenbank`, nicht in `Custom Settings`.
|
||||
|
||||
9) Globale Zeitzonen-Logik (VERBINDLICH)
|
||||
- Globale Nexus-Einstellungen liegen unter `/settings`.
|
||||
- Dort werden zentral gepflegt:
|
||||
- `Anzeige-Zeitzone`
|
||||
- `Standard-Zeitzone für Crons`
|
||||
- `Anzeige-Zeitzone`:
|
||||
- hat eine `Custom`-Checkbox
|
||||
- ohne Custom wird die System-Zeitzone verwendet
|
||||
- die aktive Zeitzone soll angezeigt werden
|
||||
- `Standard-Zeitzone für Crons`:
|
||||
- ist der globale Default fuer Modul-Crons
|
||||
- Module duerfen diese Zeitzone im Setup uebersteuern
|
||||
- einzelne Cron-Einträge duerfen sie ebenfalls uebersteuern
|
||||
|
||||
Modul-Cron-Verhalten:
|
||||
- Im Modul-Setup gibt es keinen nackten Pflicht-Default mehr, der immer direkt eingegeben werden muss.
|
||||
- Stattdessen:
|
||||
- Anzeige des aktuell wirksamen Modul-Cron-Defaults
|
||||
- `Custom-Zeitzone verwenden` fuer Modul-Override
|
||||
- einzelne Cron-Einträge koennen ebenfalls `Custom-Zeitzone verwenden`
|
||||
- Ohne Override erbt ein Cron-Eintrag die Modul-Zeitzone, und die Modul-Zeitzone erbt den globalen Nexus-Cron-Default.
|
||||
|
||||
Globale PHP-Helfer:
|
||||
- Neue Module sollen fuer zentrale Zeit-/Debug-Defaults nach Moeglichkeit die globalen Funktionen aus `src/App/functions.php` nutzen:
|
||||
- `nexus_settings()`
|
||||
- `nexus_save_settings(array $settings)`
|
||||
- `nexus_system_timezone_name()`
|
||||
- `nexus_display_timezone_name()`
|
||||
- `nexus_cron_timezone_name()`
|
||||
- `module_debug_enabled(string $module)`
|
||||
- `module_debug_push(string $module, array $entry)`
|
||||
- `module_debug_clear(string $module)`
|
||||
|
||||
Regel fuer neue Module:
|
||||
- Keine Zeitzone wie `Europe/Berlin` hart im Modul als Standard erzwingen, wenn dafuer ein globaler Nexus-Default existiert.
|
||||
- Fuer Anzeige-/Formatierungslogik nach Moeglichkeit `nexus_display_timezone_name()` nutzen.
|
||||
- Fuer Cron-Fallbacks nach Moeglichkeit `nexus_cron_timezone_name()` nutzen.
|
||||
|
||||
UTC-Speicherregel (VERBINDLICH):
|
||||
- Zeitzonen-Einstellungen haben keinen Einfluss auf das Speicherformat von Zeitwerten in der Datenbank.
|
||||
- Zeitwerte sollen projektweit intern immer in `UTC` gespeichert werden.
|
||||
- Anzeige-Zeitzonen dienen nur der Darstellung fuer Benutzer.
|
||||
- Cron-Zeitzonen dienen nur der lokalen Auswertung von Zeitplaenen und Faelligkeiten.
|
||||
- Beim Einlesen lokaler Eingaben muss vor dem Speichern nach `UTC` normalisiert werden.
|
||||
- Beim Anzeigen gespeicherter Werte muss von `UTC` in die jeweils wirksame Anzeige-Zeitzone umgerechnet werden.
|
||||
- Neue Module duerfen keine lokalen Zeitzonen direkt in Datenbank-Zeitspalten persistieren.
|
||||
|
||||
10) Globales Debug-System
|
||||
- Das Debug-Popup ist eine globale Infrastruktur aus dem zentralen Layout.
|
||||
- Aktivierung bleibt jedoch pro Modul ueber `debug_enabled` im Modul-Setup.
|
||||
- Das Debug-Symbol darf nur sichtbar sein, wenn fuer das aktuelle Modul Debug aktiv ist.
|
||||
- Module sollen keine eigene separate Debug-Oberflaeche bauen, wenn der globale Debug-Stream genutzt werden kann.
|
||||
|
||||
11) Sicherheits-/Netzwerk-Constraints
|
||||
- Zugriff im Heimnetz (192.168.178.0/24) per Nginx begrenzt.
|
||||
- SSH-Hosts nur Heimnetz.
|
||||
|
||||
12) Pi Control Besonderheiten (konkret)
|
||||
- Worker/Jobs unter /tools/pi_control/
|
||||
- Check-Updates & Cron nutzen die gleichen SSH-Routinen.
|
||||
- Host-Karten, Befehle und Konsole sind UI im Modul.
|
||||
- Update/Upgrade-Checks liefern Debug-Ausgaben, die als Tooltip oder Debugzeile angezeigt werden.
|
||||
|
||||
13) Zusammenfassung (kurz)
|
||||
Nexus ist modular, mit strikter Trennung zwischen globalem Layout und modulspezifischem Code.
|
||||
Staging/Live haben eigene /app/<env>/config-Strukturen; /config/<env> 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/<modul>/` 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
|
||||
5) Für neue Chats und Arbeitsaufträge
|
||||
- Für globale Nexus-Themen zuerst `NEXUS_SYSTEM.md` lesen.
|
||||
- Für Arbeiten an klassischen Modulen zuerst `MODULE_DEVELOPMENT.md` lesen.
|
||||
- Für Dashboard-, Widget- oder Integrationsarbeiten zuerst `WIDGET_INTEGRATION.md` lesen.
|
||||
|
||||
11
README.md
11
README.md
@@ -46,13 +46,12 @@ Das generelle Nexus-System wird unabhängig von den bestehenden Fachmodulen weit
|
||||
- zentralen Integrationen zu Fremdsystemen
|
||||
- datengetriebenen Seitenmodulen ohne eigenen Modulordner
|
||||
|
||||
Die maßgeblichen Begriffe und Regeln dafür stehen in `PROJECT_CONTEXT.md`:
|
||||
Die maßgeblichen Begriffe und Regeln dafür stehen in:
|
||||
|
||||
- `Dashboard`
|
||||
- `Dashboard-Element`
|
||||
- `Widget-Typ`
|
||||
- `Integration`
|
||||
- `Seitenmodul`
|
||||
- `PROJECT_CONTEXT.md` als Einstieg
|
||||
- `NEXUS_SYSTEM.md`
|
||||
- `MODULE_DEVELOPMENT.md`
|
||||
- `WIDGET_INTEGRATION.md`
|
||||
|
||||
Wichtig:
|
||||
|
||||
|
||||
126
WIDGET_INTEGRATION.md
Normal file
126
WIDGET_INTEGRATION.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user