tessera-ctl/.planning/phases/18-desktop-client-fertigstellen/18-CONTEXT.md

Phase 18: Desktop-Client fertigstellen - Context

Gathered: 2026-09-16 (Entscheidungen des Users im Gespraech; technische Festlegungen durch Claude) Status: Ready for planning

## Phase Boundary

Der Tauri-Desktop-Client aus Phase 6 (apps/desktop, Grundgeruest: WebView auf die Tessera-Web-App, Erststart-Seite fuer die Server-Adresse, Tray, Schliessen-ins-Tray, Autostart, Fensterzustand, Benachrichtigung, Versionspruefung, AppImage+NSIS-Ziele) wird zu einem fertigen, verteilbaren Produkt: Pakete aus der Pipeline, Download in Tessera und am Gitea-Release, Versionierung, Update-Hinweis, Handbuecher. KEINE neuen App-Funktionen im Client (keine nativen Kalender-Erinnerungen, kein Auto-Update, keine Code-Signierung).

## Implementation Decisions

Produkt (User)

• D-01: Der Installer ist in Tessera herunterladbar (Anwender ohne Gitea-Zugang) und liegt als Datei am Gitea-Release des Freigabe-Tags.
• D-02: Server-Adresse wird weiterhin beim ersten Start abgefragt (ein Paket fuer alle Umgebungen/Kunden). Kein fest eingebauter Server.
• D-03: Updates: Hinweis + Download-Link, kein automatisches Aktualisieren.

Plattformen & Bau (Claude)

• D-04: Windows-Installer (NSIS, Tessera-Setup-X.Y.Z.exe) ist das Hauptziel; Linux-AppImage (Tessera-X.Y.Z.AppImage) wird mitgebaut, weil der Runner ohnehin Linux ist.
• D-05: Der Gitea-Runner ist Linux (gitea/runner-images:ubuntu-latest, Docker, 8 Kerne/15 GB). Der Windows-Bau laeuft als Cross-Bau auf Linux (Tauri: cargo tauri build --runner cargo-xwin --target x86_64-pc-windows-msvc, NSIS via makensis aus dem Ubuntu-Paket nsis, llvm/lld/clang). Kein Windows-Rechner in der Pipeline.
• D-06: Neuer CI-Job desktop nach test, laeuft bei Push auf main und bei Tags v* (Beta bekommt die Pakete auch, sonst ist nichts testbar). Cargo-Registry, target/ und das xwin-SDK werden per actions/cache zwischengespeichert; Forschung klaert, ob der lokale act_runner den Cache-Server anbietet — wenn nicht, laeuft der Bau ohne Cache (langsamer, aber korrekt).
• D-07: Versionsquelle ist der Freigabe-Tag: Ein Skript (.gitea/scripts/desktop-version.sh) schreibt vor dem Bau die Version (X.Y.Z aus dem letzten Tag) in apps/desktop/src-tauri/tauri.conf.json und Cargo.toml. Beta-Builds tragen dieselbe X.Y.Z wie der letzte Tag plus den Commit-Stempel in einem separaten Feld/Dateinamen-Suffix (Forschung: welche Versionsformen NSIS/Tauri auf Windows akzeptieren; Regel: keine Form waehlen, die den Windows-Installer scheitern laesst).
• D-08: Verteilung ohne Netzabhaengigkeit: Die gebauten Pakete werden im publish-Job in das API-Abbild kopiert (/app/desktop-dist/ mit manifest.json: Version, Dateinamen, Groessen, SHA-256). Die API liefert sie selbst aus — Live-Server brauchen keinen Zugang zu Gitea. Zusaetzlich haengt publish-release.sh (nur bei Tags) beide Dateien als Release-Assets an das Gitea-Release (D-01).
• D-09: Keine Code-Signierung (intern; SmartScreen-Hinweis wird im Anwenderhandbuch erklaert).

API (Claude)

• D-10: Neues Modul apps/api/src/desktop/: GET /desktop/latest (oeffentlich, ohne Anmeldung — die Anmeldeseite zeigt den Link) liefert { version, files: { windows: { name, size, sha256, url }, linux: {...} } } aus manifest.json; GET /desktop/download/:platform (windows | linux, oeffentlich) streamt die Datei mit Content-Disposition: attachment. Fehlt das Verzeichnis/Manifest: 404 mit klarer Meldung; die Web-Oberflaeche blendet den Link dann aus. Nur Dateinamen aus dem Manifest werden geoeffnet (kein Pfad aus der Anfrage), Plattform per Whitelist.
• D-11: /health/version bleibt unveraendert; der Client vergleicht seine Version kuenftig mit /desktop/latest.

Web (Claude)

• D-12: Anmeldeseite: unauffaelliger Link unterhalb des Formulars "Desktop-App herunterladen (Windows)" + kleiner Linux-Link, nur wenn /desktop/latest antwortet. Einstellungen: neuer Eintrag Einstellungen → Allgemein → Desktop-App mit Version, beiden Download-Knoepfen, Dateigroesse und 3-4 Saetzen (Was ist das, Erststart, Tray). Texte de/en, Sie-Form.

Client (Claude)

• D-13: lib.rs: Versionspruefung gegen {server}/desktop/latest; bei abweichender Version Benachrichtigung "Neue Version X.Y.Z verfuegbar" und Tray-Menuepunkt "Update herunterladen", der {server}/settings/general/desktop im Systembrowser oeffnet (tauri-plugin-opener oder open-Crate — Forschung waehlt). Erststart-Seite (setup.html): Adresse pruefen ueber /health/version (bleibt), Texte in Sie-Form, Tessera-Farben; Tray-Texte mit Umlauten ("Öffnen", "Beenden").
• D-14: Bestehende Phase-6-Funktionen (Tray, Schliessen-ins-Tray, Autostart, Fensterzustand) bleiben unveraendert; Autostart-Schalter kommt ins Tray-Menue ("Mit Windows starten", Haken), weil es keine Client-Einstellungsseite gibt.

Doku & Tests (Claude)

• D-15: docs/anleitung-anwender.md: Kapitel "Desktop-App" (Download in Tessera, Installation, SmartScreen-Hinweis, Erststart mit Server-Adresse, Tray/Schliessen/Beenden, Autostart, Update-Hinweis). docs/anleitung-betrieb.md: Pipeline-Job, Cross-Bau, wo die Pakete im Abbild liegen, Release-Dateien, Fehlerbilder. docs/anleitung-entwicklung.md: apps/desktop ist kein Grundgeruest mehr; lokaler Bau (pnpm --filter @tessera/desktop build), Voraussetzungen.
• D-16: Tests: API-Modul (Manifest lesen, 404 ohne Manifest, Plattform-Whitelist, Pfad-Traversal abgewiesen), Web (Link erscheint/verschwindet je nach API-Antwort, Einstellungsseite), Rust: cargo check/cargo clippy im CI-Job; ein lokaler Linux-Bau (tauri build AppImage) als Beweis vor dem Push. Der Windows-Cross-Bau wird erst in der Pipeline bewiesen — der Plan sieht eine Iterationsschleife vor (Fehler lesen, Job anpassen, erneut pushen), bis ein gruener Lauf mit beiden Dateien vorliegt.
• D-17: CHANGELOG Unveröffentlicht → ### Neu: "Desktop-App für Windows und Linux: Download auf der Anmeldeseite und unter Einstellungen → Desktop-App" (Stichpunkt-Stil).

Claude's Discretion

• Aufteilung in Plaene (Vorschlag: 18-01 CI/Cross-Bau + Versionsskript + Release-Assets; 18-02 API-Modul + Abbild-Einbau; 18-03 Web-Oberflaeche + Client-Anpassungen + Handbuecher)
• Tray-Menue-Reihenfolge, Icon-Pruefung, Dateinamen-Details

<canonical_refs>

Canonical References

• .planning/phases/06-desktop-client-ci-cd/06-CONTEXT.md, 06-01-SUMMARY.md, 06-02-SUMMARY.md — was Phase 6 gebaut hat (Tray, Setup-Seite, Plugins, Bundles)
• apps/desktop/src-tauri/src/lib.rs, apps/desktop/src/setup.html, apps/desktop/src-tauri/tauri.conf.json, Cargo.toml — heutiger Stand des Clients
• .gitea/workflows/ci.yml, .gitea/scripts/publish-images.sh, .gitea/scripts/publish-release.sh — Pipeline, Kanalmodell (main=beta, Tag=live), Release-Anlage
• apps/api/Dockerfile, apps/api/src/health/ — Abbild-Aufbau, /health/version
• apps/web/src/app/(auth)/login/ (Anmeldeseite), apps/web/src/app/(portal)/settings/ (Einstellungen, Navigation "Allgemein → Konto")
• docs/anleitung-anwender.md, docs/anleitung-betrieb.md (Kap. 9 Freigabe), docs/anleitung-entwicklung.md
• Tauri 2 Doku: Cross-Platform Compilation (Windows on Linux via cargo-xwin), NSIS bundler, tauri-plugin-opener; act_runner Cache ([cache] enabled in runner config) </canonical_refs>

## Specific Ideas

• Der Download-Knopf soll wie die uebrigen Tessera-Knoepfe aussehen (Primaerfarbe), mit Windows/Linux-Symbol und Dateigroesse ("Tessera-Setup-1.2.0.exe · 6 MB").
• Der Erststart-Dialog soll sich anfuehlen wie Tessera (Logo, Farben), nicht wie eine Rohseite.
• Runner-Ressourcen sind begrenzt (8 Kerne, 15 GB): Rust-Bau mit -j 4 falls noetig, kein paralleler Windows+Linux-Bau in zwei Jobs, sondern nacheinander im selben Job (ein Cache).

## Deferred Ideas

• Auto-Update (Tauri Updater, Signaturschluessel) — spaeter, wenn extern verkauft wird
• Code-Signierung — spaeter
• Native Kalender-Erinnerungen ueber den Client — nicht Teil dieser Phase
• macOS-Paket — kein Bedarf