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

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.