28 KiB
phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, user_setup, estimate, must_haves
| phase | plan | type | wave | depends_on | files_modified | autonomous | requirements | user_setup | estimate | must_haves | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 18-desktop-client-fertigstellen | 06 | execute | 4 |
|
|
true |
|
|
|
Purpose: D-15 und D-17 aus 18-CONTEXT.md; Nachverfolgung DESK-03/04/05. Output: Vier Dokumente, CHANGELOG-Stichpunkt, REQUIREMENTS-Abschnitt, gruene Gesamtlaeufe, Bedienprobe des Nutzers.
Alle Handbuchtexte in Sie-Form, mit echten Umlauten, ohne firmenspezifische
Adressen (Platzhalter https://tessera.example.com; die Testserver-Adresse
steht nur in der Bedienprobe fuer den Nutzer, nicht im Handbuch).
Artifacts this phase produces
Dieser Plan: docs/anleitung-anwender.md (Kapitel "Desktop-App"),
docs/anleitung-betrieb.md (Kapitel 10), docs/anleitung-entwicklung.md
(Abschnitt "Desktop-App lokal bauen", Aktualisierung Monorepo-Aufbau und
Tests), docs/ci-cd-setup.md (Job desktop, Fehlerbehebung),
CHANGELOG.md (Stichpunkt), .planning/REQUIREMENTS.md (Kategorie DESK).
Gesamtliste der Phase: siehe 18-01-PLAN.md.
<execution_context> @$HOME/.claude/gsd-core/workflows/execute-plan.md @$HOME/.claude/gsd-core/templates/summary.md </execution_context>
@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md @.planning/phases/18-desktop-client-fertigstellen/18-CONTEXT.md @.planning/phases/18-desktop-client-fertigstellen/18-01-SUMMARY.md @.planning/phases/18-desktop-client-fertigstellen/18-02-SUMMARY.md @.planning/phases/18-desktop-client-fertigstellen/18-03-SUMMARY.md @.planning/phases/18-desktop-client-fertigstellen/18-04-SUMMARY.md @.planning/phases/18-desktop-client-fertigstellen/18-05-SUMMARY.md@docs/anleitung-anwender.md @docs/anleitung-betrieb.md @docs/anleitung-entwicklung.md @docs/ci-cd-setup.md @CHANGELOG.md @.planning/REQUIREMENTS.md
Task 1: Anwenderhandbuch — Kapitel "Desktop-App"; CHANGELOG-Stichpunkt docs/anleitung-anwender.md, CHANGELOG.md docs/anleitung-anwender.md (Inhaltsverzeichnis Zeilen 6-22, Kapitel "Persönliche Einstellungen" ab Zeile 143 und "Einen Fehler melden" ab Zeile 160 als Stilvorlage), CHANGELOG.md (Zeilen 1-14), apps/web/src/messages/de.json (Bloecke `auth.desktopDownload` und `settings.desktop` aus 18-03 — Beschriftungen woertlich uebernehmen), apps/desktop/src-tauri/src/lib.rs (Tray-Texte und Benachrichtigungstext aus 18-04), apps/desktop/src/setup.html (Texte der Erststart-Seite aus 18-04) **Kapitel einfuegen** zwischen `## Persönliche Einstellungen` und `## Einen Fehler melden`: `## Desktop-App`, im Inhaltsverzeichnis als neuer Punkt 8 (`[Desktop-App](#desktop-app)`), die folgenden Punkte auf 9-11 umnummerieren. Unterabschnitte (`###`) in dieser Reihenfolge, Sie-Form, kurze Absaetze, Beschriftungen exakt wie in der Oberflaeche:- Was die Desktop-App ist — eigenes Fenster statt Browser-Tab, Symbol im Infobereich der Taskleiste, dieselben Funktionen wie im Browser.
- Herunterladen — auf der Anmeldeseite unter dem Formular „Desktop-App herunterladen (Windows)" und „Linux-Version"; oder angemeldet unter Einstellungen → Allgemein → Desktop-App mit Version, Dateiname und Dateigroesse. Kein Zugang zu Gitea noetig.
- Installation unter Windows — Datei
Tessera-Setup-X.Y.Z.exeausfuehren; Windows-SmartScreen zeigt „Der Computer wurde durch Windows geschützt": auf „Weitere Informationen" und dann „Trotzdem ausführen" klicken; Grund in einem Satz (die App ist fuer den internen Gebrauch nicht signiert, das Paket stammt aus Ihrem Tessera-Server). Danach Startmenue-Eintrag „Tessera". Eine neuere Version wird einfach darueber installiert; die Server-Adresse bleibt erhalten. - Installation unter Linux —
Tessera-X.Y.Z.AppImageausfuehrbar machen (Dateieigenschaften oderchmod +x) und starten; keine Installation noetig. - Erster Start: Server-Adresse — die Adresse, unter der Sie Tessera im
Browser oeffnen (Beispiel
https://tessera.example.com); die App prueft die Adresse und meldet „Tessera X.Y.Z gefunden"; beihttperscheint ein Hinweis, die Verbindung ist trotzdem moeglich; danach die gewohnte Anmeldung. - Fenster, Infobereich und Beenden — Schliessen (X) legt Tessera in den Infobereich; Linksklick auf das Symbol oeffnet das Fenster; Rechtsklick zeigt „Öffnen", „Update herunterladen", „Mit Windows starten" (Haken; unter Linux „Beim Anmelden starten") und „Beenden"; nur „Beenden" beendet die App; Fenstergroesse und -position werden gemerkt.
- Automatischer Start — Haken im Menue setzen/entfernen; ab Werk aus.
- Neue Version — Benachrichtigung „Neue Version X.Y.Z verfügbar" beim Start, Menueeintrag „Version X.Y.Z herunterladen" oeffnet die Seite Einstellungen → Desktop-App im Browser; dort herunterladen und wie oben installieren. Kein automatisches Update.
- Wenn etwas nicht klappt — drei Faelle: „Unter dieser Adresse antwortet kein Tessera-Server" (Adresse pruefen, es ist die Browser-Adresse, nicht eine interne API-Adresse); der Download-Link fehlt auf der Anmeldeseite (der Server traegt noch keine Pakete — Betrieb fragen); SmartScreen blockiert (siehe Installation).
CHANGELOG (## Unveröffentlicht → ### Neu): als neuen Stichpunkt in
der bestehenden Liste - Desktop-App für Windows und Linux: Download auf der Anmeldeseite und unter Einstellungen → Desktop-App (D-17, Wortlaut exakt).
<acceptance_criteria>
- grep -c '^## Desktop-App$' docs/anleitung-anwender.md ergibt 1; grep -c '(#desktop-app)' docs/anleitung-anwender.md ergibt 1.
- grep -c '^### ' docs/anleitung-anwender.md ist um 9 groesser als vorher (neun Unterabschnitte); die Ueberschriften enthalten Herunterladen, Installation unter Windows, Installation unter Linux, Erster Start, Infobereich, Automatischer Start, Neue Version.
- grep -c 'Trotzdem ausführen' docs/anleitung-anwender.md ergibt mindestens 1; grep -c 'Desktop-App herunterladen (Windows)' docs/anleitung-anwender.md ergibt mindestens 1; grep -c 'Mit Windows starten' docs/anleitung-anwender.md ergibt mindestens 1.
- grep -c 'ctl.de\|vicolab' docs/anleitung-anwender.md ergibt 0 im neuen Kapitel (keine firmenspezifische Adresse).
- grep -c '^- Desktop-App für Windows und Linux: Download auf der Anmeldeseite und unter Einstellungen → Desktop-App$' CHANGELOG.md ergibt 1, und die Zeile steht oberhalb der ersten ## 1. Versionsueberschrift.
</acceptance_criteria>
cd /home/vicolab/projects/tessera-ctl && grep -q '^## Desktop-App$' docs/anleitung-anwender.md && grep -q '(#desktop-app)' docs/anleitung-anwender.md && grep -q 'Trotzdem ausführen' docs/anleitung-anwender.md && grep -q 'Desktop-App herunterladen (Windows)' docs/anleitung-anwender.md && grep -q 'Mit Windows starten' docs/anleitung-anwender.md && test "$(awk '/^## Desktop-App$/{f=1;next} /^## /{f=0} f' docs/anleitung-anwender.md | grep -c '^### ')" -ge 9 && test "$(awk '/^## Desktop-App$/{f=1;next} /^## /{f=0} f' docs/anleitung-anwender.md | grep -ci 'ctl.de|vicolab')" = "0" && node -e "const c=require('fs').readFileSync('CHANGELOG.md','utf8');const u=c.indexOf('## Unveröffentlicht'),v=c.search(/\n## [0-9]/);const b=c.indexOf('- Desktop-App für Windows und Linux: Download auf der Anmeldeseite und unter Einstellungen → Desktop-App');if(u===-1||b===-1||b>v||b<u)process.exit(1)" && echo DOCS1-OK
<fails_when>Kapitel, Inhaltsverzeichnis-Eintrag, eine Pflichtbeschriftung oder ein Unterabschnitt fehlt, das Kapitel nennt eine Firmenadresse, oder der CHANGELOG-Stichpunkt steht nicht unter „Unveröffentlicht" — DOCS1-OK fehlt.</fails_when>
Kapitel „Desktop-App" mit neun Unterabschnitten im Anwenderhandbuch samt
Inhaltsverzeichnis; CHANGELOG-Stichpunkt im Wortlaut von D-17.
docs/ci-cd-setup.md — Abschnitt 4: aus „drei" werden „vier" Jobs;
Job desktop zwischen test und publish beschreiben: Bedingung (main
und Tags v*), Schritte (Rust per rustup, apt-Pakete, cargo-xwin,
rustup target add x86_64-pc-windows-msvc, Version aus dem Tag per
desktop-version.sh — immer rein numerisch, Grund Windows-Ressourcen;
AppImage, dann NSIS-Cross-Bau; desktop-collect.sh mit Manifest;
Uebergabe an publish per actions/cache mit Schluessel desktop-dist-{sha}
und warum nicht upload-artifact (auf Gitea unzuverlaessig);
Cache-Pfade und Schluessel desktop-cargo-<Cargo.lock-Hash>); publish:
Restore mit hartem Abbruch, Pruefung des Manifests, Release-Upload der
Manifest-Dateien (idempotent: vorhandene Datei gleichen Namens wird
ersetzt). Abschnitt 6 Fehlerbehebung: neue Unterabschnitte „Job desktop
schlaegt fehl" (apt-Paketname, pkg-config, openssl-sys beim Windows-Ziel →
rustls-tls, NSIS-Plugin-Download, Speicher → CARGO_BUILD_JOBS),
„publish: cache miss" (Schluessel/Cache-Server, Abschnitt 2 Runner-Config
[cache] enabled), „Release-Upload 413" (GITEA_API auf die Host-Adresse
http://172.18.0.1:3002/api/v1 — nur, wenn der Proxy die Groesse
abweist). Reale Fehlerbilder aus 18-05-SUMMARY (Rundentabelle) hier
eintragen.
docs/anleitung-entwicklung.md — (1) Im Monorepo-Aufbau die Zeile zu
desktop/ und den Absatz bei Zeile 39, der apps/desktop als blosses
Grundgeruest mit einer einzelnen setup.html beschreibt, ersetzen (das Wort
„Grundgerüst" darf im Dokument danach nicht mehr im Zusammenhang mit Tauri
stehen — Negativ-Tor in <verify>): apps/desktop ist der fertige
Desktop-Client (Tauri 2): src-tauri/src/lib.rs (Tray, Erststart-Kommandos,
Versionspruefung), src/setup.html (Erststart-Seite), Pakete entstehen im
CI; packages/shared enthaelt jetzt auch die Manifest-Typen der
Desktop-Pakete. (2) Unter „Lokale Entwicklungsumgebung" neuer Abschnitt
### Desktop-App lokal bauen: Voraussetzungen (Rust stable per rustup,
Ubuntu/Debian-Pakete libwebkit2gtk-4.1-dev libjavascriptcoregtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev libgtk-3-dev libssl-dev patchelf),
Befehle sh .gitea/scripts/desktop-version.sh (schreibt die Version des
letzten Tags — die eingecheckten Versionsdateien sind nur eine Basislinie),
pnpm --filter @tessera/desktop exec tauri build --bundles appimage,
Ausgabe unter apps/desktop/src-tauri/target/release/bundle/appimage/,
sh .gitea/scripts/desktop-collect.sh --require linux fuer desktop-dist/
(vom Git ausgeschlossen bis auf den Platzhalter), Hinweis: der
Windows-Installer wird nur im CI gebaut (cargo-xwin, NSIS), lokal genuegt
cargo check/cargo clippy; lokaler Docker-Stack: nach docker compose build api
liefert die API die Pakete unter /desktop/latest. (3) Unter „Tests":
pnpm --filter @tessera/api exec vitest run src/desktop (HTTP-Durchstich
ueber NestFactory, echtes Temp-Verzeichnis) und die Rust-Pruefungen
ergaenzen.
<acceptance_criteria>
- grep -c '^## 10. Desktop-App' docs/anleitung-betrieb.md ergibt 1; das Inhaltsverzeichnis enthaelt einen Eintrag 10.; grep -c 'DESKTOP_DIST_DIR' docs/anleitung-betrieb.md ergibt mindestens 1; grep -c '/app/desktop-dist' docs/anleitung-betrieb.md ergibt mindestens 1; grep -c '### Fehlerbilder' docs/anleitung-betrieb.md ergibt 1.
- grep -c 'vier aufeinander aufbauenden Jobs\|vier Jobs' docs/ci-cd-setup.md ergibt mindestens 1; grep -c 'cargo-xwin' docs/ci-cd-setup.md ergibt mindestens 2; grep -c 'upload-artifact' docs/ci-cd-setup.md ergibt mindestens 1 (Begruendung, warum nicht); grep -c 'desktop-dist-' docs/ci-cd-setup.md ergibt mindestens 1.
- grep -c 'Tauri-Grundgerüst' docs/anleitung-entwicklung.md ergibt 0; grep -c '### Desktop-App lokal bauen' docs/anleitung-entwicklung.md ergibt 1; grep -c 'desktop-version.sh' docs/anleitung-entwicklung.md ergibt mindestens 1; grep -c 'vitest run src/desktop' docs/anleitung-entwicklung.md ergibt mindestens 1.
- Keine firmenspezifische Adresse in den neuen Abschnitten (die bestehenden Nennungen von git.vicolab.de im CI/CD-Runbook sind Infrastruktur und bleiben).
</acceptance_criteria>
Gesamtlaeufe (Endstand der Phase): pnpm --filter @tessera/api exec vitest run,
pnpm --filter @tessera/web exec vitest run, pnpm --filter @tessera/api type-check,
pnpm --filter @tessera/web type-check, cargo check in
apps/desktop/src-tauri. Ergebnisse (Anzahl Dateien/Tests) im SUMMARY
festhalten. biome check ist kein Tor (bekannter Fehler in der
Wurzel-biome.json, nicht anfassen).
Bedienprobe vorbereiten: Den Text der <human-check> unten als
Schrittfolge in das SUMMARY uebernehmen, damit der Nutzer sie zur Hand hat;
die Testserver-Adresse dort einsetzen (alpha.tessera.ctl.de, nur im
SUMMARY/Gespraech, nie im Handbuch).
<acceptance_criteria>
- grep -c '\*\*DESK-0[1-5]\*\*' .planning/REQUIREMENTS.md ergibt 5; grep -c '^| DESK-0[1-5] |' .planning/REQUIREMENTS.md ergibt 5.
- pnpm --filter @tessera/api exec vitest run und pnpm --filter @tessera/web exec vitest run melden 0 fehlgeschlagene Tests; beide Typpruefungen fehlerfrei; cargo check gruen.
- Der Nutzer hat die Bedienprobe (human-check) durchgefuehrt und das Ergebnis liegt vor.
</acceptance_criteria>
cd /home/vicolab/projects/tessera-ctl && test "$(grep -c '**DESK-0[1-5]**' .planning/REQUIREMENTS.md)" = "5" && test "$(grep -c '^| DESK-0[1-5] |' .planning/REQUIREMENTS.md)" = "5" && echo REQ-OK
<fails_when>Weniger oder mehr als fuenf DESK-Eintraege bzw. Traceability-Zeilen — REQ-OK fehlt.</fails_when>
cd /home/vicolab/projects/tessera-ctl && pnpm --filter @tessera/api exec vitest run && pnpm --filter @tessera/web exec vitest run && pnpm --filter @tessera/api type-check && pnpm --filter @tessera/web type-check && (cd apps/desktop/src-tauri && cargo check 2>&1 | tail -1 | grep -q Finished) && echo ALL-GREEN
<fails_when>Eine Suite meldet "failed", tsc gibt Fehler aus, oder cargo check endet ohne Finished — ALL-GREEN fehlt.</fails_when>
Bedienprobe des Nutzers (Du-Form im Gespraech; Voraussetzung: der Testserver
laeuft auf dem Beta-Stand mit den Paketen — docker compose pull und
docker compose up -d --force-recreate machst du dort selbst; Windows-PC
mit Browser):
- Anmeldeseite des Testservers im Browser oeffnen: Unter dem Formular steht „Desktop-App herunterladen (Windows)", daneben „Linux-Version", darunter „Version 1.1.0".
- Auf den Windows-Link klicken: Es laedt
Tessera-Setup-1.1.0-beta.{kennung}.exe(wenige MB). - Datei ausfuehren. Windows zeigt die SmartScreen-Warnung: „Weitere Informationen" → „Trotzdem ausführen". Die Installation laeuft ohne weitere Fragen durch; Tessera startet (sonst ueber das Startmenue).
- Erststart-Seite: dunkle Karte mit Tessera-Zeichen und gelbem Schriftzug,
Feld „Adresse Ihres Tessera-Servers". Adresse des Testservers eintragen
(
https://…), „Verbinden": kurz „Tessera 1.1.0 gefunden – Verbindung wird hergestellt …", dann erscheint die Tessera-Anmeldung im App-Fenster. - Anmelden. Fenster mit X schliessen: Die App bleibt im Infobereich (Symbol mit Tessera-Zeichen). Linksklick auf das Symbol: Fenster ist wieder da.
- Rechtsklick auf das Symbol: Menue „Öffnen", „Update herunterladen" (ausgegraut, weil du die aktuelle Version hast), „Mit Windows starten" (ohne Haken), „Beenden" — mit Umlauten.
- „Mit Windows starten" anklicken: Haken erscheint; erneut anklicken: Haken verschwindet.
- „Beenden": App ist weg (auch aus dem Infobereich).
- App erneut starten: Sie geht direkt zu Tessera (Adresse gemerkt), Fenstergroesse und -position wie beim Beenden.
- In der App: Einstellungen → Allgemein → „Desktop-App": Seite mit „Aktuelle Version: 1.1.0", „Beta-Ausgabe, Stand {kennung}", zwei gelbe Knoepfe „Für Windows herunterladen" / „Für Linux herunterladen", darunter Dateiname und Groesse (z. B. „… · 101,5 MB" fuer Linux), und vier Saetze Erklaerung.
- Falls ein Linux-Rechner greifbar ist: AppImage herunterladen, ausfuehrbar machen, starten — Erststart-Seite wie unter 4.
Zwei Punkte lassen sich erst beim naechsten Freigabe-Tag pruefen und
gehoeren in die Abnahme dieser Version, nicht in diese Phase: (a) Nach dem
Tag v1.2.0 zeigt der installierte 1.1.0-Client beim Start die
Benachrichtigung „Neue Version 1.2.0 verfügbar …", und der Menueeintrag
heisst „Version 1.2.0 herunterladen" und oeffnet die Seite Desktop-App im
Browser. (b) Der Gitea-Release v1.2.0 traegt Tessera-Setup-1.2.0.exe
und Tessera-1.2.0.AppImage als Dateien.
REQUIREMENTS.md fuehrt DESK-01..05 mit Nachverfolgung; alle Suiten und
Typpruefungen gruen; die Bedienprobe des Nutzers ist durchgefuehrt und im
SUMMARY dokumentiert (inklusive der zwei auf den naechsten Tag vertagten
Punkte).
<threat_model>
Trust Boundaries
| Boundary | Description |
|---|---|
| Handbuecher -> Anwender | Anleitungen praegen das Verhalten der Anwender bei Sicherheitswarnungen (SmartScreen). |
| Testserver -> Nutzer-PC | Der Nutzer installiert ein unsigniertes Paket vom Beta-Kanal. |
STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|---|---|---|---|---|---|
| T-18-19 | Spoofing | SmartScreen-Anleitung („Trotzdem ausführen") | low | mitigate | Das Handbuch koppelt die Anweisung an die Herkunft (Download nur aus dem eigenen Tessera-Server, Dateiname Tessera-Setup-…) und nennt keine allgemeine Empfehlung, Warnungen zu ignorieren. |
| T-18-20 | Information Disclosure | Handbuecher mit Server-Adressen | low | mitigate | Nur Platzhalter (https://tessera.example.com); die Testserver-Adresse steht ausschliesslich im SUMMARY/Gespraech. |
| T-18-SC | Tampering | Paketinstallationen | low | accept | Dieser Plan installiert kein Paket. |
| </threat_model> |
<success_criteria>
- Anwender-, Betriebs- und Entwicklungshandbuch beschreiben Installation, Erststart, Tray-Verhalten, Pipeline, Release-Dateien und Umgebungsvariablen (Erfolgskriterium 4).
- Der installierte Client zeigt nach Eingabe der Server-Adresse die Anmeldung und verhaelt sich im Infobereich wie beschrieben (Erfolgskriterium 3, Bedienprobe).
- Alle Suiten gruen; CHANGELOG und REQUIREMENTS nachgezogen. </success_criteria>