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>

docs/ci-cd-setup.md

@@ -109,21 +109,71 @@ hardcoden.
 
 Die CI/CD-Pipeline (`.gitea/workflows/ci.yml`) laeuft bei jedem Push auf die
 Zweige `main` und `live` sowie bei jedem Tag `v*` (z. B. `v1.0.0`) und besteht
-aus drei aufeinander aufbauenden Jobs:
+aus vier aufeinander aufbauenden Jobs:
 
 1. **quality** -- Lint und TypeScript Type-Check (Lint ist derzeit ein Leerlauf,
    siehe WINDOWS #35; der Type-Check ist echt)
 2. **test** -- Vitest Unit- und Integrationstests
-3. **publish** -- Docker Images mit Versionsstempel bauen und in die Gitea-Registry
+3. **desktop** -- Desktop-Pakete fuer Windows und Linux bauen (nur auf `main`
+   und bei Tags `v*`, siehe unten)
+4. **publish** -- Docker Images mit Versionsstempel bauen und in die Gitea-Registry
    veroeffentlichen
 
-Ablauf: `quality` -> `test` -> `publish` (jeder Job nur bei Erfolg des
-vorherigen). Der Job `publish` besteht aus vier Schritten: `actions/checkout@v4`
-mit `fetch-depth: 0` (volle Historie samt Tags, sonst liefert `git describe`
-nichts), Login in die Registry (siehe Abschnitt 3), der Aufruf von
-`.gitea/scripts/publish-images.sh` und der Aufruf von
-`.gitea/scripts/publish-release.sh` (legt bei Tags `v*` den Gitea-Release aus dem
-CHANGELOG-Abschnitt an; auf `main` endet er mit "nichts zu tun").
+Ablauf: `quality` -> `test` -> `desktop` -> `publish` (jeder Job nur bei Erfolg
+des vorherigen; `desktop` selbst laeuft nur, wenn die `if`-Bedingung zutrifft
+-- auf einem Push nach `live` ohne Tag entfaellt der Job, `publish` startet in
+diesem Fall trotzdem, weil `needs: desktop` bei einem uebersprungenen Job nicht
+blockiert). Der Job `publish` besteht aus sechs Schritten:
+`actions/checkout@v4` mit `fetch-depth: 0` (volle Historie samt Tags, sonst
+liefert `git describe` nichts), der Wiederherstellung der Desktop-Pakete aus
+dem Zwischenspeicher, einer harten Pruefung des Manifests, Login in die
+Registry (siehe Abschnitt 3), der Aufruf von `.gitea/scripts/publish-images.sh`
+und der Aufruf von `.gitea/scripts/publish-release.sh` (legt bei Tags `v*` den
+Gitea-Release aus dem CHANGELOG-Abschnitt an und haengt die Desktop-Pakete als
+Dateien an; auf `main` endet er mit "nichts zu tun").
+
+### Job `desktop`: Windows- und Linux-Pakete auf dem Linux-Runner
+
+Der Job `desktop` baut auf demselben `ubuntu-latest`-Runner nacheinander (ein
+Cache, ein Runner, siehe `18-CONTEXT.md` Specific Ideas) sowohl das
+Linux-AppImage als auch -- per Cross-Bau -- den Windows-Installer:
+
+1. **Systemabhaengigkeiten** (`apt-get install`): WebKit/Tauri-Pakete
+   (`libwebkit2gtk-4.1-dev` usw.) fuer den Linux-Bau, dazu `lld llvm clang
+   nsis` fuer den Windows-Cross-Bau (der NSIS-Bundler ruft `makensis` aus
+   genau diesem Paket auf).
+2. **Rust-Toolchain** per `rustup` (kein Rust im Runner-Abbild), inklusive
+   `rustup component add clippy` -- `--profile minimal` installiert `clippy`
+   sonst nicht mit (siehe Fehlerbehebung unten).
+3. **Cargo-Zwischenspeicher** (`actions/cache@v4`, Schluessel ueber den Hash
+   von `Cargo.lock`): `~/.cargo/registry`, `~/.cargo/git`,
+   `~/.cargo/bin/cargo-xwin`, `~/.cache/cargo-xwin` (die von `cargo-xwin`
+   heruntergeladene Windows-SDK-Ablage -- soll nur einmal geladen werden),
+   `~/.local/share/tauri` (NSIS-Plugins) und `apps/desktop/src-tauri/target`.
+4. **Windows-Werkzeuge** -- bewusst NACH dem Cache-Wiederherstellungsschritt:
+   `rustup target add x86_64-pc-windows-msvc` und
+   `command -v cargo-xwin || cargo install --locked cargo-xwin`. Stuende
+   dieser Schritt vor der Cache-Wiederherstellung, wuerde `cargo-xwin` bei
+   jedem Lauf neu gebaut, selbst wenn der Cache es bereits enthaelt.
+5. **Version setzen** (`desktop-version.sh`), **Rust pruefen**
+   (`cargo check`/`cargo clippy`, D-16), Bau des Linux-AppImage
+   (`tauri build --bundles appimage`), dann des Windows-Installers per
+   Cross-Bau (`tauri build --runner cargo-xwin --target
+   x86_64-pc-windows-msvc --bundles nsis`).
+6. **Pakete einsammeln** (`desktop-collect.sh --require linux,windows`) --
+   schreibt `manifest.json` und schlaegt fehl, wenn eine der beiden Dateien
+   fehlt.
+7. **Uebergabe an `publish`** per `actions/cache/save@v4` mit dem Schluessel
+   `desktop-dist-${{ gitea.sha }}` (ein neuer Schluessel je Commit, damit
+   `publish` garantiert die Pakete des gerade gebauten Standes bekommt, nicht
+   einen aelteren Cache-Treffer).
+
+**Warum `actions/cache` und nicht `upload-artifact`:** Auf dieser
+Gitea-Instanz ist `actions/upload-artifact`/`download-artifact` unzuverlaessig
+(Erfahrungswert aus 18-02) -- die Uebergabe zwischen `desktop` und `publish`
+laeuft deshalb bewusst ueber `actions/cache/save` und
+`actions/cache/restore` mit `fail-on-cache-miss: true`, nicht ueber
+Artefakt-Uploads.
 
 Das Release-Skript spricht die Gitea-API ueber `GITHUB_API_URL` bzw.
 `GITHUB_SERVER_URL/api/v1` an -- im Job-Container ist das
@@ -237,3 +287,59 @@ und einen Branch-Schutz fuer `live` anlegen (T-KU1-04).
 2. Pruefen, ob der Tag wirklich gepusht wurde: `git ls-remote --tags origin`
 3. `dev` bedeutet: das Image wurde ohne Build-Args gebaut (lokal statt ueber
    das Skript) -- das ist fuer lokale Builds normal
+
+### Job `desktop` schlaegt fehl
+
+1. **`cargo clippy` meldet `'cargo-clippy' is not installed for the toolchain`**
+   -- der Schritt "Rust-Toolchain" installiert mit `--profile minimal`, das
+   `clippy` nicht mitbringt. Behoben durch `rustup component add clippy`
+   direkt nach der Toolchain-Installation (siehe oben); bei einem aehnlichen
+   Fehlerbild in Zukunft pruefen, ob diese Zeile noch vorhanden ist.
+2. **apt-Paketname unbekannt / `pkg-config` findet eine Bibliothek nicht** --
+   Paketnamen aendern sich gelegentlich zwischen Ubuntu-Versionen des
+   Runner-Abbilds; den fehlenden `.pc`/`.so`-Namen aus der Fehlermeldung in
+   `apt-cache search` nachschlagen und die Paketliste im Schritt
+   "Systemabhaengigkeiten" ergaenzen.
+3. **`openssl-sys` scheitert beim Windows-Cross-Ziel** -- OpenSSL laesst sich
+   fuer `x86_64-pc-windows-msvc` von Linux aus nicht ohne Weiteres
+   cross-kompilieren; falls eine neue Abhaengigkeit das ueber `openssl-sys`
+   statt `rustls-tls` einzieht, das Feature/die Abhaengigkeit auf
+   `rustls-tls` umstellen (in diesem Job bislang nicht aufgetreten, `reqwest`
+   ist bereits auf `rustls-tls` konfiguriert).
+4. **NSIS-Plugin-Download schlaegt fehl** -- Tauris NSIS-Bundler laedt beim
+   ersten Bau zusaetzliche Plugins nach `~/.local/share/tauri`; ein
+   Netzwerkfehler dort bricht den Bauschritt "Windows-Installer bauen
+   (Cross-Bau)" ab. Lauf erneut anstossen; bleibt der Cache warm, entfaellt
+   der Download beim naechsten Mal.
+5. **Runner-Speicher/-Zeit reicht nicht** -- der Rust-Bau laeuft auf einem
+   begrenzten Runner (8 Kerne/15 GB, siehe `18-CONTEXT.md`); bei
+   Speicherdruck `CARGO_BUILD_JOBS` (z. B. auf `4`) als Umgebungsvariable im
+   Job setzen, um die parallele Uebersetzung zu drosseln.
+
+### `publish`: cache miss
+
+`actions/cache/restore@v4` mit `fail-on-cache-miss: true` bricht den Job
+`publish` hart ab, wenn kein Eintrag unter dem Schluessel
+`desktop-dist-${{ gitea.sha }}` existiert. Wahrscheinlichste Ursachen:
+
+1. Der Job `desktop` ist fehlgeschlagen oder uebersprungen worden (siehe
+   `if`-Bedingung oben) -- im Gitea-Actions-Lauf pruefen, ob `desktop`
+   tatsaechlich gruen war.
+2. Der Zwischenspeicher-Server des `act_runner` ist nicht erreichbar oder
+   nicht aktiviert -- Runner-Konfiguration pruefen (Abschnitt 2,
+   `[cache] enabled` muss gesetzt sein).
+3. Der Commit-SHA im Schluessel weicht zwischen den Jobs ab (sollte bei
+   `gitea.sha` innerhalb desselben Laufs nicht vorkommen) -- bei Verdacht die
+   Job-Logs beider Schritte (`Uebergabe an publish` in `desktop`,
+   `Desktop-Pakete aus dem Zwischenspeicher holen` in `publish`) auf den
+   verwendeten Schluessel vergleichen.
+
+### Release-Upload 413
+
+Schlaegt der Datei-Upload in `publish-release.sh` mit HTTP 413 (Datei zu
+gross) fehl, blockt vermutlich der vorgeschaltete Proxy vor `git.vicolab.de`
+den grossen Installer-Upload -- dasselbe bekannte Verhalten wie beim
+Image-Push (Abschnitt 3). Abhilfe: `GITEA_API` auf die Host-Adresse
+`http://172.18.0.1:3002/api/v1` setzen, damit der Release-Upload denselben
+Weg wie der Registry-Push nimmt und den Proxy umgeht -- nur noetig, wenn der
+Proxy die Groesse tatsaechlich abweist.