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>/,
|
Wichtig: Modul-spezifischer Code/Assets ausschließlich unter /modules/<modul>/,
|
||||||
keine Änderungen an /public/assets/* für modul-spezifische Features.
|
keine Änderungen an /public/assets/* für modul-spezifische Features.
|
||||||
Staging/Live: /config/<env> im Repo wird nach /app/<env>/config kopiert.
|
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
|
Projekt-Zusammenfassung: Nexus Control Panel
|
||||||
|
|
||||||
1) Projekt-Zweck & Ziel
|
Diese Datei ist ab jetzt der zentrale Einstieg und verweist auf die drei maßgeblichen Dokumentationsbereiche.
|
||||||
Nexus ist ein zentrales, webbasiertes Admin-Interface zur Steuerung einer dynamischen IT-Infrastruktur.
|
|
||||||
Module kapseln fachliche Funktionen (z.B. KEA DHCP, Pi Control).
|
|
||||||
|
|
||||||
2) Aktive Module (Kurzüberblick)
|
1) Nexus-System
|
||||||
- KEA DHCP: Verwaltung von Hosts/Leases, Statische Reservierungen, Metadaten.
|
- Datei: [NEXUS_SYSTEM.md](NEXUS_SYSTEM.md)
|
||||||
- Pi Control: Verwaltung von SSH-Hosts, Befehle/Preset, Konsole, Host-Status, Update/Upgrade-Checks.
|
- 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
|
2) Modul-Entwicklung
|
||||||
- Live: nexus.kusche.berlin
|
- Datei: [MODULE_DEVELOPMENT.md](MODULE_DEVELOPMENT.md)
|
||||||
- Staging: staging.nexus.kusche.berlin
|
- 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:
|
3) Widget-Einbindung und Integrationen
|
||||||
- /app/live/ -> Live-Code
|
- Datei: [WIDGET_INTEGRATION.md](WIDGET_INTEGRATION.md)
|
||||||
- /app/staging/ -> Staging-Code
|
- Inhalt:
|
||||||
- Jeweils mit eigenem /config-Unterordner:
|
- Benutzer-Dashboards
|
||||||
- /app/live/config/
|
- Dashboard-Elemente und Widget-Typen
|
||||||
- /app/staging/config/
|
- Integrationen zu Fremdsystemen
|
||||||
|
- on-the-fly Seitenmodule
|
||||||
|
- Kollisionsschutz zu bestehenden Modulen
|
||||||
|
- empfohlene Umsetzungsphasen
|
||||||
|
|
||||||
Repo-Layout zu Configs:
|
4) Wichtige Leitplanken
|
||||||
- /config/live/ und /config/staging/ liegen im Repo.
|
- Änderungen am generellen Nexus-System dürfen nicht in bestehende Module eingreifen, wenn das nicht ausdrücklich verlangt ist.
|
||||||
- Beim Deployment werden die Dateien daraus nach /app/<env>/config kopiert.
|
- Klassische Fachmodule und das neue Dashboard- oder Widget-System sind getrennte Ebenen.
|
||||||
- WICHTIG: Im laufenden Container existiert /app/config/ NICHT, sondern nur /app/live/config und /app/staging/config.
|
- 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)
|
5) Für neue Chats und Arbeitsaufträge
|
||||||
- /public/ -> Web Root (index.php, globale Assets)
|
- Für globale Nexus-Themen zuerst `NEXUS_SYSTEM.md` lesen.
|
||||||
- /api/ -> Backend/API-Endpunkte
|
- Für Arbeiten an klassischen Modulen zuerst `MODULE_DEVELOPMENT.md` lesen.
|
||||||
- /src/ -> PHP-Kernklassen/Utilities
|
- Für Dashboard-, Widget- oder Integrationsarbeiten zuerst `WIDGET_INTEGRATION.md` lesen.
|
||||||
- /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
|
|
||||||
|
|||||||
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
|
- zentralen Integrationen zu Fremdsystemen
|
||||||
- datengetriebenen Seitenmodulen ohne eigenen Modulordner
|
- 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`
|
- `PROJECT_CONTEXT.md` als Einstieg
|
||||||
- `Dashboard-Element`
|
- `NEXUS_SYSTEM.md`
|
||||||
- `Widget-Typ`
|
- `MODULE_DEVELOPMENT.md`
|
||||||
- `Integration`
|
- `WIDGET_INTEGRATION.md`
|
||||||
- `Seitenmodul`
|
|
||||||
|
|
||||||
Wichtig:
|
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