tessera-ctl/.planning/quick/260922-frg-desktop-client-update-eintrag-im-tray-ni/260922-frg-PLAN.md

phase, plan, type, autonomous, subsystem, requirements

phase	plan	type	autonomous	subsystem	requirements
quick-260922-frg	01	tdd	true	apps/desktop/src-tauri

Quick-Aufgabe 260922-frg: Update-Eintrag im Tray nie mehr stumm ausgegraut

Befund (Orchestrator, 22.09.2026)

Der Nutzer sieht im Tray-Menü nur den grauen Eintrag „Update installieren“, obwohl alpha das Paket 1.2.0-beta.gc001a08 anbietet und der Client auf Stand a6d1a64 steht (Neustart der App ändert nichts). Nachgemessen:

• Die Update-Anfrage genau in der Form des Clients (/api-proxy/desktop/update?target=windows&arch=x86_64&current=1.2.0&base=https://alpha.tessera.ctl.de) liefert auf dem alpha-Server selbst (Port 3000 am Proxy vorbei) 200 mit gültigem Manifest. Tessera-seitig ist alles in Ordnung.
• Vor Tessera steht der Nginx Proxy Manager und antwortet auf jede Anfrage an alpha.tessera.ctl.de mit 401 Authorization Required (WWW-Authenticate: Basic), gemessen vom Dev-Host (192.168.13.11) und vom Testserver selbst (192.168.200.240 über die öffentliche Adresse 217.7.63.32). Die Webansicht der App kann so ein Passwortfenster beantworten und sich das merken; der Updater (tauri-plugin-updater, eigener reqwest-Client) nicht.
• Im Plugin führt ein Nicht-2xx-Status NICHT zu einem Fehler mit Statuscode: updater.rs Z. 529-559 loggt nur „did not respond with a successful status code“, lässt last_error leer und endet in Err(Error::ReleaseNotFound). Unser spawn_version_check fängt das mit Err(_) => {} — stumm. Der Eintrag bleibt für immer „Update installieren“ (gesperrt), die App prüft außerdem nur beim Start (und beim Serverwechsel).

Das ist der eigentliche Produktfehler dieser Aufgabe: ein fehlgeschlagener Update-Check ist vom Zustand „kein Update“ nicht unterscheidbar, und es gibt keinen Weg, die Prüfung ohne Neustart zu wiederholen. Den Passwortschutz am Proxy selbst kann der Client nicht lösen (und soll es nicht: Zugangsdaten gehören nicht in ausgelieferte Clients) — er wird dem Nutzer als Grund angezeigt.

Gebundene Entscheidungen (Orchestrator)

1. Der Update-Eintrag hat drei Endzustände, alle anklickbar außer während Prüfung/Installation und bei http-Server:
   • Update gefunden → Auf Beta-Stand <sha7> aktualisieren / Auf Version X.Y.Z aktualisieren (wie bisher), Klick installiert.
   • Kein Update → Kein Update verfügbar – erneut prüfen, Klick startet die Prüfung erneut.
   • Prüfung fehlgeschlagen → Update-Prüfung fehlgeschlagen (HTTP 401) – erneut prüfen bzw. ohne Status Update-Prüfung fehlgeschlagen (keine Verbindung) – erneut prüfen, Klick startet die Prüfung erneut.
   • Während der Prüfung: Suche nach Updates… (gesperrt). Während Download/Installation wie bisher (gesperrt, Fortschritt im Text).
   • http-Server: Update nur über https möglich (gesperrt, unverändert).
   • Beim Bau des Menüs steht Suche nach Updates… (gesperrt), weil setup die Prüfung sofort startet; ohne gespeicherte Server-Adresse Kein Update verfügbar – erneut prüfen (Klick ohne Adresse: nichts tun).
2. Statuscode nachliefern. Bei Err(ReleaseNotFound) (= Server hat geantwortet, aber nicht 2xx/204) stellt der Client dieselbe Anfrage einmal mit seinem eigenen reqwest-Client (Timeout 8 s, Muster check_server) an die konkret gebaute Adresse (Platzhalter ersetzt: target = std::env::consts::OS, arch = std::env::consts::ARCH, current = CARGO_PKG_VERSION, base wie bisher) und liest NUR den Statuscode. Rumpf wird nicht ausgewertet. Bei Err(Reqwest(..))/Err(Network(..))/Err(Io(..)) des Plugins (keine Verbindung, TLS, Timeout) keine zweite Anfrage: Status None.
3. Benachrichtigung mit Erklärung, einmal je unterschiedlichem Fehlertext (Mutex mit dem zuletzt gemeldeten Text; gleicher Text wird bei der periodischen Prüfung nicht erneut gemeldet). Texte über eine reine Funktion check_failure_labels(status: Option<u16>) -> (String, String):
   • Some(401) / Some(403): Menü Update-Prüfung fehlgeschlagen (HTTP 401) – erneut prüfen; Body Der Server hat die Update-Anfrage mit HTTP 401 abgewiesen. Meist steht ein Passwortschutz oder eine Zugriffsliste am vorgeschalteten Proxy davor, die die App für Updates nicht durchlaufen kann. Anmeldung und Arbeiten in der App sind davon nicht betroffen.
   • Some(n) sonst: Menü Update-Prüfung fehlgeschlagen (HTTP n) – erneut prüfen; Body Der Server hat auf die Update-Anfrage mit HTTP n geantwortet statt mit Paketdaten.
   • None: Menü Update-Prüfung fehlgeschlagen (keine Verbindung) – erneut prüfen; Body Der Server war für die Update-Prüfung nicht erreichbar. Die App prüft in vier Stunden erneut – oder über den Menüeintrag.
4. Periodische Prüfung alle 4 Stunden (std::thread::spawn mit std::thread::sleep(Duration::from_secs(4 * 3600)) in Schleife; kein neues Crate). Je Durchlauf: gespeicherte Adresse frisch über stored_server_url(app) lesen (Serverwechsel berücksichtigt); wenn PendingUpdate bereits ein Update hält → überspringen (keine wiederholte Benachrichtigung „Neuer Beta-Stand“); sonst spawn_version_check. Der Thread wird in setup einmal gestartet.
5. Klick auf „update“: PendingUpdate.take() → vorhanden: spawn_update_install (wie bisher); sonst: wenn eine Server-Adresse gespeichert ist → spawn_version_check (manuelles „erneut prüfen“); ohne Adresse → nichts. Der bisherige Browser-Rückfall (open_download_page) bleibt NUR im Fehlerpfad der Installation.
6. Ein Mutex-Zustand für die Benachrichtigungs-Entprellung als eigener app.manage-Typ (LastCheckNotice(Mutex<String>)), damit spawn_version_check keine Signatur-Änderung nach außen braucht.
7. Alle Menütexte Deutsch (wie bisher, „Sie“ in Benachrichtigungen), Kommentare Deutsch im Stil der Datei, Verweise auf updater.rs-Zeilen wie im Bestand.

Aufgabe (eine Datei Code, plus Changelog)

Aufgabe 1: lib.rs — Zustände des Update-Eintrags, Statuscode-Diagnose, Entprellung, 4-Stunden-Prüfung, Klick = erneut prüfen; Tests; Changelog apps/desktop/src-tauri/src/lib.rs, CHANGELOG.md - `check_failure_labels(Some(401))` → Menü enthält `HTTP 401` und endet auf `– erneut prüfen`; Body enthält `Passwortschutz` und `Zugriffsliste`. `Some(403)` gleiche Body-Erklärung mit `HTTP 403`. `Some(502)` → Menü `HTTP 502`, Body ohne `Passwortschutz`, enthält `statt mit Paketdaten`. `None` → Menü enthält `keine Verbindung`, Body enthält `vier Stunden`. - `diagnostic_update_url("https://alpha.example", "windows", "x86_64", "1.2.0")` → `https://alpha.example/api-proxy/desktop/update?target=windows&arch=x86_64¤t=1.2.0&base=https%3A%2F%2Falpha.example` (Schlussstrich getrimmt; `base` kodiert wie in `update_endpoint`). - Konstanten: `UPDATE_ITEM_CHECKING == "Suche nach Updates…"`, `UPDATE_ITEM_NONE == "Kein Update verfügbar – erneut prüfen"`, `UPDATE_ITEM_INSECURE` unverändert. - `is_update_newer`, `update_labels`, `release_labels`, `update_endpoint` unverändert (bestehende Tests bleiben grün). 1. Konstanten: `UPDATE_ITEM_DEFAULT` entfernen (durch `UPDATE_ITEM_CHECKING` und `UPDATE_ITEM_NONE` ersetzt), Kommentare anpassen. Neue Konstante `UPDATE_CHECK_INTERVAL: Duration = 4 h` mit Begründung (Tray-App läuft tagelang; nur Start-Prüfung → Update nie gesehen, Befund 22.09.2026). 2. Reine Funktionen `check_failure_labels(status: Option) -> (String, String)` und `diagnostic_update_url(server: &str, target: &str, arch: &str, current: &str) -> String` (nutzt `api_url` + `url::Url::query_pairs_mut` wie `update_endpoint`, damit die Kodierung identisch ist). Tests zuerst (rot: Funktionen fehlen), mindestens 6 `#[test]` gemäß ``. 3. `async fn probe_update_status(url: String) -> Option`: `reqwest::Client::builder().timeout(8 s)`, `GET`, `Some(resp.status().as_u16())`, bei Fehler `None`. Keine Auswertung des Rumpfs, kein Folgen von Redirects nötig (Standard). 4. `spawn_version_check`: zu Beginn `UPDATE_ITEM_CHECKING` + gesperrt (statt DEFAULT). Ergebnisse: - `Ok(Some(update))` wie bisher. - `Ok(None)` → Text `UPDATE_ITEM_NONE`, `set_enabled(true)`. - `Err(InsecureTransportProtocol)` → wie bisher (gesperrt). - `Err(ReleaseNotFound)` → `probe_update_status(diagnostic_update_url(&server_url, std::env::consts::OS, std::env::consts::ARCH, env!("CARGO_PKG_VERSION"))).await` → `check_failure_labels(status)` → Menütext setzen, `set_enabled(true)`, Benachrichtigung nur, wenn der Body vom zuletzt gemeldeten (`LastCheckNotice`) abweicht; danach dort ablegen. - `Err(_)` sonst → `check_failure_labels(None)`, gleiche Behandlung. Bei `Ok(Some)` und `Ok(None)` `LastCheckNotice` leeren, damit ein späterer Fehler wieder gemeldet wird. 5. `setup`: Menüeintrag mit `UPDATE_ITEM_CHECKING` bauen, wenn eine Adresse gespeichert ist, sonst `UPDATE_ITEM_NONE`; `.enabled(server_url.is_none())` entsprechend. `app.manage(LastCheckNotice(Mutex::new(String::new())))`. Nach dem Start der Erstprüfung den Wiederhol-Thread starten: `let handle = app.handle().clone(); std::thread::spawn(move || loop { std::thread::sleep(UPDATE_CHECK_INTERVAL); let pending = handle.state::().0.lock().map(|g| g.is_some()).unwrap_or(false); if pending { continue; } if let Some(url) = stored_server_url(&handle) { spawn_version_check(handle.clone(), url); } })`. Kommentar: warum kein `tokio::time` (kein neues Feature/Crate) und warum `PendingUpdate` den Durchlauf überspringt. 6. Klick „update“: `take()` wie bisher; `None` → `if let Some(url) = stored_server_url(app) { spawn_version_check(app.clone(), url) }`. Kommentar aktualisieren (der Browser-Weg ist nicht mehr der Rückfall des Klicks). 7. `cargo fmt`, `cargo clippy` (0 Warnungen, wie CI), `cargo test` in `apps/desktop/src-tauri` — alle bestehenden Tests plus die neuen grün. `cargo build` (Debug reicht lokal; Release/Windows baut die CI). 8. `CHANGELOG.md` unter „Unveröffentlicht → Behoben“ als erster Stichpunkt: „Desktop-App: der Update-Eintrag im Menü des Infobereich-Symbols bleibt nicht mehr stumm ausgegraut – schlägt die Update-Prüfung fehl, steht der Grund im Eintrag (z. B. „HTTP 401“, wenn ein Passwortschutz am Proxy die Anfrage abweist) und ein Klick prüft erneut; die App prüft außerdem alle vier Stunden, nicht mehr nur beim Start“ (kein Fließtext, Tonlage der Nachbarzeilen). Commit: `fix(desktop): Update-Eintrag nennt den Grund einer fehlgeschlagenen Pruefung, Klick prueft erneut, Pruefung alle 4 h` (Wortlaut frei, Stil `git log --oneline -15`). cd /home/vicolab/projects/tessera-ctl/apps/desktop/src-tauri && cargo fmt --check && cargo clippy 2>&1 | tail -3 && cargo test 2>&1 | tail -5 && grep -q 'HTTP 401' /home/vicolab/projects/tessera-ctl/CHANGELOG.md Tests in `lib.rs` ≥ 6 neue, alle grün, die Label-/URL-Tests nachweislich zuerst rot (Kompilierfehler „cannot find function“ zählt als rot — im SUMMARY nennen). `cargo clippy` ohne Warnung, `cargo fmt --check` sauber, `cargo build` erfolgreich. Menüzustände wie in Entscheidung 1; Klick ohne abgelegtes Update startet die Prüfung; Wiederhol-Thread alle 4 h; Benachrichtigung entprellt. CHANGELOG-Zeile steht. Genau ein Commit mit Scope `desktop`.

Hinweise für den Executor

• Nur apps/desktop/src-tauri/src/lib.rs und CHANGELOG.md anfassen. Keine neuen Crates, keine Cargo.toml-Änderung (reqwest ist da, url kommt über tauri::Url).
• MenuItem::set_text/set_enabled liefern Result, wie im Bestand mit let _ = ignorieren.
• stored_server_url(app) existiert (siehe open_download_page). AppHandle ist Clone + Send; std::thread::spawn mit dem Klon ist zulässig (die Setup-Funktion nutzt bereits app.handle().clone() für den Async-Task).
• Die Prüfung im CI: cargo check + cargo clippy; lokal zusätzlich cargo test. Der Cross-Bau für Windows läuft in der CI (Stempel ändert sich, weil apps/desktop berührt wird).
• Nicht anfassen: is_update_newer, update_labels, release_labels, update_endpoint, spawn_update_install.

Verifikation durch den Orchestrator (nach CI)

• CI-Lauf grün, Job desktop hat neu gebaut (kein Cache-Treffer), Manifest im API-Abbild trägt den neuen Stempel.
• Optional auf der Windows-Test-VM gegen alpha: neuer Client zeigt Update-Prüfung fehlgeschlagen (HTTP 401) – erneut prüfen und eine Benachrichtigung mit der Proxy-Erklärung.

<threat_model> ASVS 1, block on high.

ID	Bedrohung	Schwere	Disposition
T-FRG-01	Diagnose-Anfrage folgt Redirects zu fremden Hosts	low	Nur Statuscode wird gelesen, kein Rumpf; Ziel ist die vom Nutzer gespeicherte Server-Adresse; kein Geheimnis in der Anfrage. Akzeptiert.
T-FRG-02	Benachrichtigungs-Spam durch periodische Prüfung gegen kaputten Proxy	low	Entprellung über LastCheckNotice (gleicher Text wird nicht erneut gemeldet). Mitigiert.
T-FRG-03	Proxy-Zugangsdaten in den Client einbauen, um 401 zu umgehen	high	Ausdrücklich NICHT umgesetzt (Entscheidung Befund); der Grund wird angezeigt, die Behebung liegt am Proxy. Mitigiert durch Nicht-Bau.
T-FRG-04	Wiederhol-Thread startet Prüfung während Installation	low	Während der Installation ist PendingUpdate durch take() leer, ein Durchlauf würde nur eine Prüfung anstoßen; spawn_version_check setzt den Menütext — Restrisiko: Fortschrittstext wird überschrieben, wenn genau im Download-Fenster die 4-h-Marke fällt. Akzeptiert (Download dauert Minuten, Intervall Stunden).
</threat_model>