# Module

Installierbare und fachliche Apps liegen in diesem Projekt unter `custom/apps/<app>/`.

Die neue Desktop-Shell ist nur die UI-Schicht. Modul-Businesslogik wird nicht in den Desktop-Core verschoben.

## Aktuelle Modulstruktur

Ein Desktop-Modul kann zusaetzlich diese Projektdateien besitzen:

- `desktop.php` fuer die Desktop-App-Metadaten und Asset-Definitionen
- `pages/` fuer Standalone-Seiten oder iframe/native Einstiegspunkte
- `api/` fuer modulinterne HTTP-Endpunkte
- `assets/` fuer modulnahe CSS- und JS-Dateien
- `docs/README.md` fuer modulspezifische Hinweise, API und Sonderregeln
- `module.json` fuer Setup, Desktop-Freigabe, Widget-Funktionen und Cron-Endpunkte

Custom-App-Assets werden nicht direkt aus `public/` geladen, sondern ueber den generischen Endpoint `/module-assets/index.php` aus dem jeweiligen App-Ordner ausgeliefert.

## Trennung zwischen Systemtools und Modulen

- `Systemtools` sind globale Verwaltungs- und Setup-Apps und nicht installierbar
- aktuelle Beispiele: `Admin Apps`, `User Management`, `User Self Management`, `Cron Tool`
- `Custom Apps` sind installierbare Fachanwendungen
- aktuelle Beispiele: `Mining-Checker`, `Waehrungs-Checker`, `Boersenchecker`, `Pi-hole`
- eine `App` ist die allgemeine Anwendung; ein Benutzer aktiviert sie mindestens fuer das Menue und kann fuer geeignete Apps zusaetzlich ein Desktop-Icon einblenden
- `Tray-Apps` sind kleine Schnellzugriffe oder Statusanzeigen neben der Uhr und koennen eigenstaendig oder zusammen mit der Haupt-App genutzt werden
- `Widgets` sind kleine Desktop-Elemente ohne klassische Fensterfunktionen und koennen eigenstaendig oder Teil einer App sein
- aktuell werden Widgets noch uebergangsweise im rechten Infobereich gerendert; das Zielbild ist spaeter eine freier positionierbare Darstellung auf dem Desktop

Diese Trennung wird ueber App-Metadaten gesteuert:

- `app_scope`
  - `core`
  - `system_tool`
  - `module`
- `installable`
  - `false` fuer Core- und Systemtools
  - `true` fuer installierbare Module

## Modul-Metadaten in `module.json`

Module sollen ihre Desktop-Faehigkeiten zentral in `module.json` beschreiben.

Wichtige Bausteine:

- `desktop`
  - `available`
  - `show_on_desktop`
  - `show_in_start_menu`
- `widgets`
  - beschreibt Widget-Funktionen, die fuer Benutzer mit App-Zugriff separat aktiviert werden koennen
- `cron_jobs`
  - beschreibt Cron-Endpunkte fuer die zentrale Cron-Verwaltung

Die Desktop-Shell liest diese Angaben automatisch ein. Neue Modul-Crons und Widgets muessen deshalb nicht zusaetzlich in einer separaten globalen Liste nachgetragen werden, solange sie sauber im Manifest beschrieben sind.

## Globale Desktop-Standards fuer Module

- gemeinsame Desktop-Mechaniken wie Fenster, Tray, globale Persistenz und Debug-Infrastruktur liegen im Desktop-Core
- Module und andere Apps sollen keine eigene Grund-Debug-Oberflaeche im Stil eines separaten globalen Debuggers bauen
- fuer Debugging im Desktop gilt das zentrale Admin-Debug-Widget neben der Uhr mit eigenem Debug-Fenster als Standard
- Debug-Events aus Modulen sollen in den gemeinsamen Desktop-Debug-Bus geschrieben werden, damit sie im globalen Debug-Fenster sichtbar sind
- wenn das globale Debug-Fenster geschlossen ist, sollen Module kein dauerhaft aktives Live-Debugging erzwingen
- app-spezifische Debug-Darstellungen sind nur zulaessig, wenn sie fachliche Zusatzinformationen zeigen, die ueber den globalen Stream hinausgehen

## Pflegehinweis

Diese Datei muss gepflegt bleiben, wenn sich Modulstruktur oder Modulregeln aendern.

Wichtige Inhalte aus dieser Datei muessen ebenfalls zentral gepflegt werden in:

- [CONTENT.md](/home/lars/Schreibtisch/Projekte/desktop.kusche.berlin/docs/CONTENT.md)
- [WEITERENTWICKLUNG.md](/home/lars/Schreibtisch/Projekte/desktop.kusche.berlin/docs/WEITERENTWICKLUNG.md)