desktop/docs/WEITERENTWICKLUNG.md

# Weiterentwicklung

Zentrale Arbeits- und Regeldatei fuer die Weiterentwicklung von `desktop.kusche.berlin`.

Diese Datei enthaelt:

- Go's und NoGo's
- Dokumentationsregeln
- Architektur- und Pflegehinweise

## Dokumentationspflicht

Die Projektdokumentation wird zentral und dezentral gleichzeitig gepflegt.

Verbindlich ist:

- zentrale Inhalte und Begriffe muessen in [CONTENT.md](/home/lars/Schreibtisch/Projekte/desktop.kusche.berlin/docs/CONTENT.md) gepflegt werden
- Nutzungs- und Hilfetexte muessen in [ANLEITUNG.md](/home/lars/Schreibtisch/Projekte/desktop.kusche.berlin/docs/ANLEITUNG.md) gepflegt werden
- Entwicklungsregeln muessen in dieser Datei gepflegt werden
- vorhandene `README.md`-Dateien in Unterordnern muessen weiter gepflegt werden
- wichtige Informationen aus den einzelnen `README.md`-Dateien muessen auch zentral gehalten werden
- bei neuen wichtigen Unterordnern ist zu pruefen, ob eine eigene `README.md` noetig ist

## Go's

- Desktop-Mechaniken zentral halten, nicht pro App duplizieren
- Fensterverhalten konsistent halten
- gemeinsame Standards fuer Fensterinhalte nutzen, sofern eine App kein bewusst eigenes UI benoetigt
- globale Debug-Infrastruktur zentral halten und ueber alle Apps wiederverwenden
- Begriffe in UI und Doku konsistent nach `CONTENT.md` verwenden
- Apps als bereitgestellte Systemfunktionen denken, nicht nur als sichtbare Fenster
- Unterschiede zwischen `App`, `Infobereich` und `Widget-Bereich` sauber trennen
- lokale Persistenz und spaetere Backend-Synchronisierung getrennt vorbereiten
- Nutzerdaten und Desktop-Preferences bevorzugt datenbankbasiert speichern, nicht dateibasiert
- `README.md`-Dateien in Teilbereichen aktuell halten
- zentrale Doku bei jeder relevanten Struktur- oder Begriffsanpassung mitpflegen
- API-Pfade versioniert und host-konsistent unter `(staging.)desktop.kusche.berlin/api/v1/...` halten
- importierte Module mit eigener API ueber konsistente `public/api/<modul>/index.php`-Shims an die gemeinsame Desktop-Auth anbinden
- importierte Module mit eigener Fensterseite ueber konsistente `public/apps/<modul>/index.php`-Shims anbinden
- Widget-Logik einer App muss dieselben fachlichen Regeln wie die App-API verwenden, nicht eigene Sonderwege
- Systemtools duerfen nicht als installierbare Module modelliert werden
- neue Modul-Widgets und Modul-Cronjobs sollen ueber Manifest-Metadaten registriert werden statt ueber versteckte Sonderlisten

## NoGo's

- keine stillen Umbenennungen von Bereichen ohne Aktualisierung der zentralen Doku
- keine Rueckbauten bestehender Desktop-Mechaniken ohne ausdrueckliche Entscheidung
- keine Vermischung von Modul-Businesslogik mit globalem Desktop-Core
- keine Skin-Sonderlogik direkt in einzelnen Apps, wenn sie global loesbar ist
- keine neue globale Debug-Grundlogik pro App, wenn der Desktop-Debug-Bus und das zentrale Debug-Fenster genutzt werden koennen
- keine nur lokalen README-Informationen ohne zentrale Uebernahme der wichtigen Punkte
- keine Hilfeinhalte nur in Chatverlaeufen oder Ad-hoc-Notizen belassen
- keine produktive Architekturabhaengigkeit zu `Old-Nexus/` oder vergleichbaren Altbestaenden
- keine neue Standard-API-Domain wie `api.desktop.kusche.berlin`, solange keine ausdrueckliche Architekturentscheidung dafuer getroffen wurde
- keine stillen externen API-Abrufe beim blossen Oeffnen einer App, wenn die Fachregel explizite Refresh-Sperren vorsieht

## Architekturregeln

- `custom/apps/<app>/` bleibt Ort fuer installierbare Fach-Apps
- `system/apps/<app>/` bleibt Ort fuer System-Tools und nicht installierbare App-Quellen
- `system/shell/<tool>/` bleibt Ort fuer globale Shell-Werkzeuge und shell-nahe Desktop-Helfer
- globale Desktop-Mechaniken liegen im gemeinsamen Kern
- globale Modul-Helfer duerfen im gemeinsamen Kern liegen, Fachlogik aber nicht
- globale Debug-Steuerung fuer Admins liegt im Desktop-Core; Aktivierung erfolgt ueber das gemeinsame Debug-Widget neben der Uhr
- die Definition globaler Debug- und Shell-Werkzeuge soll in `system/shell/` liegen und nicht lose in `public/` oder verstreut im JS
- API und Desktop teilen sich im aktuellen Zielbild denselben Host; offizielle Basis ist `/api/v1/...`
- App, API und Widget einer Fachfunktion muessen dieselben Sperr- und Force-Regeln fuer externe Abrufe nutzen
- die Trennung `core` / `system_tool` / `module` ist in Metadaten, Startmenue und Benutzer-Setup konsistent zu halten
- Cron-Endpunkte muessen auf demselben Host laufen und duerfen keine separate Standard-API-Domain voraussetzen
- Skins definieren Darstellung und Interaktionsdetails, nicht die Fachlogik
- Hilfe- und Inhaltsdateien sollen spaeter maschinenlesbar oder zumindest klar strukturierbar in einen Hilfebereich ueberfuehrt werden koennen

## Pflegeprozess

Bei jeder groesseren Aenderung ist zu pruefen:

1. Wurden offizielle Begriffe geaendert oder erweitert
2. Wurde der Systemumfang sichtbar erweitert
3. Braucht ein Unterordner eine gepflegte `README.md`
4. Muessen zentrale Dateien angepasst werden
5. Ist der Inhalt spaeter fuer einen Hilfebereich relevant

## Aktuell wichtige Projektregeln

- `docs/UMSETZUNGSSTATUS.md` nur dann als erledigt markieren, wenn es ausdruecklich freigegeben wurde
- Fokus liegt aktuell auf Desktop-UI und Apps
- Login und Keycloak sind vorerst akzeptiert und nicht der aktuelle Hauptschwerpunkt
- API-Zielpfade sollen auf `(staging.)desktop.kusche.berlin/api/v1/...` vereinheitlicht werden
- Desktop-Icons sind frei verschiebbar und werden pro Benutzer und Skin lokal gespeichert
- die Schriftfarbe von Desktop-Icons passt sich automatisch an den Hintergrund an
- Benutzerdaten sollen spaeter sauber in LDAP oder Keycloak geschrieben werden
- Standard-Fensterinhalte sollen ein gemeinsames Design nutzen
- Desktop-Nutzereinstellungen liegen in einer eigenen Tabelle mit erkennbarem `_user_data`-Suffix
- das globale Admin-Debug-Fenster ist der Standardweg fuer Live-Debugging in Desktop und Native-Apps
- Debug-Tracking soll nur waehrend eines geoeffneten globalen Debug-Fensters laufen; der letzte Status soll einen Reload pro Benutzer ueberstehen