nexus/PROJECT_CONTEXT.md

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/<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.

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.