sadsad

PROJECT_CONTEXT.md

@@ -84,17 +84,168 @@ Modulspezifische Assets:
   - Mining-Checker: Seitenheader-Box, Submenü-Box, Bereichs-Box, Karten-Boxen, Karten-Boxen, Bereichs-Box
   - Modulverwaltung: Seitenheader-Box, Submenü-Box, danach Karten-Boxen
 
-8) Sicherheits-/Netzwerk-Constraints
+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.
 
-9) Pi Control Besonderheiten (konkret)
+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.
 
-10) Zusammenfassung (kurz)
+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.