nexus/MODULE_DEVELOPMENT.md

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