asdasd

MODULE_DEVELOPMENT.md

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