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). 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. 3) Umgebungen & Domains - Live: nexus.kusche.berlin - Staging: staging.nexus.kusche.berlin Container/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. 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.