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 gepflegt werden
Nutzungs- und Hilfetexte muessen in 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, Tray-App, Widget, Infobereich und Tray-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
App-Berechtigungen fuer LDAP-Gruppen muessen zentral und pro App nachvollziehbar pflegbar bleiben
die Freigabe fuer den offenen Logoff-Desktop muss pro App zentral pflegbar bleiben
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
system/addons/<addon>/ bleibt Ort fuer optionale System-Erweiterungen und Integrationen
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
Nutzersteuerung fuer Menue-App, Tray-App, Desktop-Icon und Widget muss getrennt speicherbar bleiben
Widgets sollen fachlich als Desktop-Elemente gedacht werden; die aktuelle Einblendung im rechten Infobereich ist nur ein Uebergang und darf spaeter sauber ersetzt werden
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:

Wurden offizielle Begriffe geaendert oder erweitert
Wurde der Systemumfang sichtbar erweitert
Braucht ein Unterordner eine gepflegte README.md
Muessen zentrale Dateien angepasst werden
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

6.5 KiB Raw Blame History