From 52158ef041fccdd483c2207c63282b0271cb458f Mon Sep 17 00:00:00 2001 From: Lars Gebhardt-Kusche Date: Fri, 15 May 2026 00:38:56 +0200 Subject: [PATCH] asdasd --- MODULCREATION_ANWEISUNG.md | 3 +- MODULE_DEVELOPMENT.md | 154 ++++++++++++++ NEXUS_SYSTEM.md | 119 +++++++++++ PROJECT_CONTEXT.md | 425 +++---------------------------------- README.md | 11 +- WIDGET_INTEGRATION.md | 126 +++++++++++ 6 files changed, 440 insertions(+), 398 deletions(-) create mode 100644 MODULE_DEVELOPMENT.md create mode 100644 NEXUS_SYSTEM.md create mode 100644 WIDGET_INTEGRATION.md diff --git a/MODULCREATION_ANWEISUNG.md b/MODULCREATION_ANWEISUNG.md index d638263..c1a204c 100644 --- a/MODULCREATION_ANWEISUNG.md +++ b/MODULCREATION_ANWEISUNG.md @@ -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//, keine Änderungen an /public/assets/* für modul-spezifische Features. Staging/Live: /config/ im Repo wird nach /app//config kopiert. diff --git a/MODULE_DEVELOPMENT.md b/MODULE_DEVELOPMENT.md new file mode 100644 index 0000000..708e8cb --- /dev/null +++ b/MODULE_DEVELOPMENT.md @@ -0,0 +1,154 @@ +Projektkontext: Modul-Entwicklung + +1) Modul-Konzept +- Jedes klassische Modul lebt unter `/modules//`. +- 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//` und gegebenenfalls `/tools/` ä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//general` + - `/modules/setup//database` + - `/modules/setup//access` + - `/modules/setup//cron` + - `/modules/setup//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 diff --git a/NEXUS_SYSTEM.md b/NEXUS_SYSTEM.md new file mode 100644 index 0000000..ceda073 --- /dev/null +++ b/NEXUS_SYSTEM.md @@ -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//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//` -> 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//` und gegebenenfalls `/tools/` + +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//` 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 diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md index cdbafaa..f822005 100644 --- a/PROJECT_CONTEXT.md +++ b/PROJECT_CONTEXT.md @@ -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//` + - 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//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// -> 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//. -- 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// + ggf. /tools/ ä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//general` - - `/modules/setup//database` - - `/modules/setup//access` - - `/modules/setup//cron` - - `/modules/setup//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//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 +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. diff --git a/README.md b/README.md index 7af036a..a0cfb97 100644 --- a/README.md +++ b/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: diff --git a/WIDGET_INTEGRATION.md b/WIDGET_INTEGRATION.md new file mode 100644 index 0000000..8478c89 --- /dev/null +++ b/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