desktop/docs/ANLEITUNG.md

# Anleitung

Nutzungs- und Hilfedatei fuer `desktop.kusche.berlin`.

Diese Datei ist fuer spaetere Endnutzerhilfe, interne Einfuehrung und als Basis fuer einen Hilfebereich gedacht.

## Einstieg

Der Desktop besteht aus mehreren Hauptbereichen:

- `Desktop`
  Arbeitsflaeche mit Icons, Fenstern und Infobereich.

- `Startmenue`
  Zugang zu Benutzerfunktionen und installierten Programmen.

- `Infobereich`
  Rechter Seitenbereich fuer eingeblendete Informationskarten.

- `Tray-Bereich`
  Bereich bei Uhr und Systemleiste fuer kleine Tray-Apps und Mini-Funktionen.

## Startmenue verwenden

Das Startmenue ist in drei Bereiche gegliedert:

1. `User Setting Bereich`
   Hier befinden sich Benutzername, User-Icon, Einstellungen sowie Anmelden oder Abmelden.
2. `Funktion-Bereich`
   Hier werden die Funktionsgruppen ausgewaehlt. Aktuell ist `Programme` die erste Gruppe.
3. `Auswahlbereich`
   Hier erscheinen die Inhalte der aktuell gewaehlten Funktionsgruppe, gruppiert nach `Desktop`, `Systemtools` und `Modulen`.

## Programme oeffnen

- Desktop-Icons koennen direkt geoeffnet werden.
- Im Startmenue lassen sich Programme ueber den `Auswahlbereich` starten.
- `Systemtools` erscheinen dort getrennt von installierbaren `Modulen`.
- Fenster koennen verschoben, minimiert, maximiert und geschlossen werden.
- Programme koennen sowohl globale System-Apps als auch klassische Module sein.

## API

Die API der Anwendung liegt aktuell bewusst auf demselben Host wie der Desktop.

Das Zielbild ist:

- `desktop.kusche.berlin/api/v1/...`
- `staging.desktop.kusche.berlin/api/v1/...`

Eine getrennte API-Domain wie `api.desktop.kusche.berlin` ist derzeit nicht der Standard.

## Einstellungen oeffnen

Die Einstellungen werden aktuell ueber die App `User Self Management` bereitgestellt.

Dort koennen derzeit insbesondere verwaltet werden:

- `Desktop Type` beziehungsweise Skin-Auswahl
- persoenliche Benutzerdaten
- aktivierte `Apps` im Menue
- optionale `Desktop-Icons` fuer geeignete Apps
- aktivierte `Tray-Apps`
- aktivierte `Widgets`

Administratoren nutzen zusaetzlich `Admin Apps` fuer den globalen App-Bestand, Installationswege, LDAP-Gruppenberechtigungen und erste Integrations-Einstellungen wie den Gitea-Deploy-Status.

Vor dem Login erscheint nun zusaetzlich ein offener `Logoff-Desktop`. Dort gibt es unten nur die Login-Lasche. Sichtbar sind dort ausschliesslich Desktop-Apps, die ein Admin explizit fuer die Nutzung ohne Login freigegeben hat.

Neue Fach-Apps koennen im Bereich `Admin Apps > Installation` direkt als ZIP hochgeladen werden. Das ZIP muss genau ein Modulverzeichnis enthalten und wird nach einer Basispruefung nach `custom/apps/` entpackt.

## Module

Installierbare Fach-Apps liegen unter `custom/apps/<app>/` und koennen als normale `App` im Desktop erscheinen.

Aktuell gilt:

- der `Mining-Checker` ist das erste echte Modul in dieser Form
- der `Waehrungs-Checker` ist das zweite echte Modul in dieser Form
- Modul-Businesslogik bleibt im Modul und wird nicht in den Desktop-Core verschoben
- gemeinsame Desktop-Mechaniken wie Fenster, Asset-Einbindung und Zugriffsschutz werden global bereitgestellt

## Tray-Apps, Widgets und Cronjobs

- `Tray-Apps` liegen im Bereich neben der Uhr und sind fuer Schnellaktionen oder kleine Visualisierungen gedacht.
- `Widgets` koennen von Modulen bereitgestellt werden, wenn das Modul diese Funktion im Manifest hinterlegt.
- Widgets sind fachlich kleine Desktop-Elemente ohne Fensterfunktionen; aktuell erscheinen sie technisch noch uebergangsweise im rechten `Infobereich`.
- Widget- und Tray-Funktionen stehen nur dann zur Auswahl, wenn der Benutzer auf die zugrundeliegende App Zugriff hat.
- Der Abschnitt `Widgets` in `Admin Apps` ist eine technische Registry-Uebersicht und zeigt Herkunft, Launch-App und APIs vorhandener Widgets.
- Das `Cron Tool` ist ein globales `Systemtool` fuer Administratoren.
- Dort erscheinen Modul-Cronjobs automatisch, sobald ein Modul sie in `module.json` hinterlegt.
- Cron-Aufrufe laufen auf demselben Host und verwenden dieselbe Projektbasis wie der Desktop.

## Waehrungs-Checker

Der `Waehrungs-Checker` verwaltet gespeicherte Wechselkurse, Kurs-Historie, Umrechnungen und manuelle Aktualisierung.

- das Oeffnen der App loest keinen externen Abruf aus
- ein manueller Abruf ist nur erlaubt, wenn die letzten gespeicherten Kurse aelter als die konfigurierte Sperrzeit sind
- mit `force` kann ein Abruf bewusst erzwungen werden
- das zugehoerige Widget nutzt dieselbe Regel wie App und API

## Benutzerdaten

Aktuell gelten folgende Regeln:

- Standardfelder wie Name, E-Mail, Telefon, Titel und Ort koennen fuer LDAP vorbereitet oder synchronisiert werden.
- `Geburtsdatum` bleibt derzeit lokal gespeichert.
- nicht jedes Profilfeld wird automatisch in LDAP geschrieben.
- Desktop-bezogene Nutzereinstellungen werden in einer eigenen Datenbanktabelle gespeichert.

## Desktop Type und Skins

Das System unterstuetzt derzeit:

- `Apple`
- `Windows`
- `Linux`

Der ausgewaehlte Desktop Type beeinflusst Darstellung und Interaktionsdetails, waehrend die gemeinsame Shell-Logik erhalten bleibt.

## Infobereich

Der `Infobereich` ist der rechte Desktopbereich.

- Inhalte koennen benutzerbezogen ein- oder ausgeblendet werden.
- Aenderungen sollen gespeichert bleiben.
- Der `Infobereich` ist nicht identisch mit dem `Tray-Bereich`.
- Widgets werden aktuell noch dort eingeblendet, sollen spaeter aber frei auf dem Desktop positionierbar sein.

## Begriffsregel

Fuer sprachliche Konsistenz gilt:

- rechte Desktopseite: `Infobereich`
- Mini-Apps an Uhr/Systemleiste: `Tray-Bereich`
- linke Startmenuespalte: `User Setting Bereich`
- mittlere Startmenuespalte: `Funktion-Bereich`
- rechte Startmenuespalte: `Auswahlbereich`

Die verbindliche zentrale Fassung der Begriffe steht in [CONTENT.md](/home/lars/Schreibtisch/Projekte/desktop.kusche.berlin/docs/CONTENT.md).