diff --git a/.planning/phases/18-desktop-client-fertigstellen/18-CONTEXT.md b/.planning/phases/18-desktop-client-fertigstellen/18-CONTEXT.md new file mode 100644 index 0000000..09d36c7 --- /dev/null +++ b/.planning/phases/18-desktop-client-fertigstellen/18-CONTEXT.md @@ -0,0 +1,77 @@ +# 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 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) + + + +## 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 +