docs(18-06): Betriebshandbuch Kapitel 10, CI/CD-Runbook Job desktop, Entwicklungshandbuch

- Betriebshandbuch: neues Kapitel 10 (Pipeline-Herkunft, Ablageort im Abbild,
  Release-Anhaenge, DESKTOP_DIST_DIR, Fehlerbilder-Tabelle); Kapitel 9 um
  Satz zu Desktop-Paketen im Freigabe-Tag ergaenzt
- CI/CD-Runbook: aus drei werden vier Jobs, Job desktop ausfuehrlich
  beschrieben (Cross-Bau, Cache-Reihenfolge, Cache-vs-upload-artifact-
  Begruendung), Fehlerbehebung um drei Unterabschnitte ergaenzt
  (Job desktop, cache miss, Release-Upload 413)
- Entwicklungshandbuch: apps/desktop ist kein Grundgeruest mehr, neuer
  Abschnitt "Desktop-App lokal bauen", Testabschnitt um vitest src/desktop
  und cargo check/clippy ergaenzt

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-09-16 17:22:49 +02:00
parent 43c7061cb3
commit 8f2069b845
3 changed files with 263 additions and 16 deletions
+74 -5
View File
@@ -30,15 +30,23 @@ fest verankert.
apps/
api/ @tessera/api — NestJS-Backend
web/ @tessera/web — Next.js-Frontend
desktop/ — — Tauri-Wrapper, früher Stand (nur Cargo-Projekt + eine setup.html)
desktop/ @tessera/desktop — Tauri-Desktop-Client (Windows/Linux), fertiges Produkt
packages/
shared/ @tessera/shared — geteilte Konstanten/Typen, derzeit sehr klein (APP_NAME, HealthResponse)
shared/ @tessera/shared — geteilte Konstanten/Typen, inzwischen auch die Manifest-Typen der Desktop-Pakete
module-sdk/ — — TypeScript-Interfaces für den Modul-Vertrag (TesseraModule, ModuleManifest)
```
`apps/desktop` besteht bislang nur aus dem Tauri-Grundgerüst (`src-tauri/`) und einer einzelnen
`setup.html` — dort ist noch keine eigentliche Anwendung zu finden. `packages/shared` ist ebenfalls
minimal; es enthält aktuell nur eine Konstante und ein Health-Interface, keine DTOs.
`apps/desktop` ist der fertige Desktop-Client (Tauri 2), kein Grundgerüst mehr:
`src-tauri/src/lib.rs` bündelt Tray-Menü, die beiden Erststart-Kommandos
(`check_server`/`save_server_url`) und die Versionsprüfung gegen den Server;
`src/setup.html` ist die eigenständige Erststart-Seite (kein Bundler, spricht
nur über `window.__TAURI__.core.invoke`). Die fertigen Installationspakete
(Windows-`.exe`, Linux-`.AppImage`) entstehen nicht lokal, sondern im CI-Job
`desktop` (siehe [Desktop-App lokal bauen](#desktop-app-lokal-bauen) für den
lokalen Linux-Bau). `packages/shared` bleibt schlank, trägt inzwischen aber
zusätzlich zu Konstante und Health-Interface auch die Typen für das
Desktop-Paket-Manifest (`DesktopPlatform`, `DesktopManifest`,
`DesktopLatestResponse`).
**Root-Skripte** (`package.json`, laufen über Turborepo durch alle Workspaces):
@@ -117,6 +125,46 @@ postgresql://tessera:tessera_dev@<container-ip>:5432/tessera
Das ist relevant, sobald Sie `prisma migrate dev`, `prisma studio` oder ein manuelles `psql` **vom
Host aus** statt aus dem `api`-Container heraus ausführen wollen.
### Desktop-App lokal bauen
Voraussetzungen zusätzlich zu oben:
- Rust (stable) über [rustup](https://rustup.rs/)
- Auf Ubuntu/Debian folgende Systempakete:
```bash
sudo apt-get install -y libwebkit2gtk-4.1-dev libjavascriptcoregtk-4.1-dev \
libayatana-appindicator3-dev librsvg2-dev libgtk-3-dev libssl-dev patchelf
```
Version setzen und Linux-Paket bauen:
```bash
sh .gitea/scripts/desktop-version.sh
pnpm --filter @tessera/desktop exec tauri build --bundles appimage
```
`desktop-version.sh` schreibt die Version des letzten Freigabe-Tags in
`tauri.conf.json`/`Cargo.toml` — die im Repository eingecheckten Versionsdateien
sind nur eine Basislinie, nicht die tatsächliche Freigabeversion. Das fertige
Paket liegt danach unter
`apps/desktop/src-tauri/target/release/bundle/appimage/`. Um es wie die
API es ausliefern würde einzusammeln:
```bash
sh .gitea/scripts/desktop-collect.sh --require linux
```
Das schreibt `desktop-dist/` (per `.gitignore` vom Git ausgeschlossen, bis auf
einen Platzhalter) samt `manifest.json`. Starten Sie danach den lokalen
Docker-Stack (`docker compose build api` genügt für die API allein), liefert
`GET /desktop/latest` die dort abgelegten Pakete aus.
**Der Windows-Installer wird nur im CI gebaut** (`cargo-xwin`-Cross-Bau, NSIS
aus dem Ubuntu-Paket `nsis` — siehe `docs/ci-cd-setup.md`, Abschnitt 4). Lokal
genügt für Rust-Änderungen `cargo check`/`cargo clippy` in
`apps/desktop/src-tauri`; einen Windows-Installer lokal zu bauen ist nicht
vorgesehen.
## Architektur im Überblick
**Frontend** (`apps/web/src/app`, Next.js App Router):
@@ -422,6 +470,27 @@ gegen Services, Controller-Logik und React-Komponenten. Guard-artige Spezifikati
gegen bereits einmal aufgetretene Fehler — wiederkehrende Fallstricke werden in diesem Projekt
durch einen Test abgesichert, nicht nur durch einen Kommentar.
**Desktop-Modul (`apps/api/src/desktop`):**
```bash
pnpm --filter @tessera/api exec vitest run src/desktop
```
Die Tests laufen als echter HTTP-Durchstich über `NestFactory.create()` +
`app.listen(0)` gegen ein echtes temporäres Verzeichnis (kein `fs`-Mock) —
Manifest lesen, 404 ohne Manifest, Plattform-Whitelist, Pfad-Traversal
abgewiesen.
**Rust (`apps/desktop/src-tauri`):**
```bash
cargo check
cargo clippy
```
Beide laufen auch im CI-Job `desktop` (D-16); ein grüner `cargo clippy` ohne
Warnungen ist Voraussetzung für den Bauschritt.
## Konventionen und Fallstricke
**NestJS-Routenreihenfolge:** NestJS matcht Routen in Deklarationsreihenfolge. Eine statische Route