Projektkontext: Modul-Entwicklung 1) Modul-Konzept - Jedes klassische Modul lebt unter `/modules//`. - 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//` und gegebenenfalls `/tools/` ä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//general` - `/modules/setup//database` - `/modules/setup//access` - `/modules/setup//cron` - `/modules/setup//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