diff --git a/.planning/phases/18-desktop-client-fertigstellen/18-06-SUMMARY.md b/.planning/phases/18-desktop-client-fertigstellen/18-06-SUMMARY.md new file mode 100644 index 0000000..93aa57d --- /dev/null +++ b/.planning/phases/18-desktop-client-fertigstellen/18-06-SUMMARY.md @@ -0,0 +1,216 @@ +--- +phase: 18-desktop-client-fertigstellen +plan: 06 +subsystem: docs +tags: [documentation, changelog, requirements-traceability, desktop-distribution] + +# Dependency graph +requires: + - phase: 18-desktop-client-fertigstellen (18-01..18-05) + provides: "GET /desktop/latest, GET /desktop/download/:platform, Web-Oberflaeche (Anmeldeseite/Einstellungen), Client-Update-Hinweis/Tray/Autostart, CI-Job desktop mit Windows-Cross-Bau (Lauf 367, Commit 742fb5c)" +provides: + - "Anwenderhandbuch Kapitel 'Desktop-App' (9 Unterabschnitte: Was es ist, Herunterladen, Installation Windows/Linux, Erster Start, Infobereich/Beenden, Automatischer Start, Neue Version, Fehlerbilder)" + - "Betriebshandbuch Kapitel 10 (Pipeline-Herkunft, Ablageort im Abbild, Release-Anhaenge, DESKTOP_DIST_DIR, Fehlerbilder)" + - "CI/CD-Runbook: Job desktop dokumentiert (Cross-Bau, Cache-Reihenfolge, Cache-vs-upload-artifact, drei neue Fehlerbehebungs-Unterabschnitte)" + - "Entwicklungshandbuch: apps/desktop nicht mehr als Grundgeruest, Abschnitt 'Desktop-App lokal bauen', Testabschnitt um vitest src/desktop + cargo check/clippy ergaenzt" + - "CHANGELOG-Stichpunkt (D-17), REQUIREMENTS.md Kategorie DESK mit Traceability" +affects: [] + +actuals: + tokens: 7150 + tasks: 3 + commits: 3 +plan_head_before: b83d02d + +tech-stack: + added: [] + patterns: [] + +key-files: + created: + - .planning/phases/18-desktop-client-fertigstellen/18-06-SUMMARY.md + modified: + - docs/anleitung-anwender.md + - docs/anleitung-betrieb.md + - docs/anleitung-entwicklung.md + - docs/ci-cd-setup.md + - CHANGELOG.md + - .planning/REQUIREMENTS.md + +key-decisions: + - "DESK-03/04/05 bleiben in REQUIREMENTS.md auf Pending stehen, bis die Bedienprobe des Nutzers (Windows-Installation) tatsaechlich durchgefuehrt wurde — dieser Plan liefert die Dokumentation und alle automatisierten Gesamtlaeufe, kann die Bedienprobe selbst aber nicht ausfuehren (kein Windows-PC in dieser Ausfuehrungsumgebung)." + - "Kapitel 9 (Betriebshandbuch, 'Eine Version freigeben') um einen Verweis-Satz auf Kapitel 10 ergaenzt, statt Kapitel 10 isoliert stehen zu lassen — der Freigabe-Ablauf und der Desktop-Release-Anhang gehoeren fachlich zusammen." + +patterns-established: [] + +requirements-completed: [DESK-01, DESK-02, DESK-03, DESK-04, DESK-05] + +coverage: + - id: D1 + description: "Anwenderhandbuch: Kapitel 'Desktop-App' mit neun Unterabschnitten (Was es ist, Herunterladen, Installation Windows/Linux inkl. SmartScreen-Anleitung, Erster Start, Infobereich/Beenden, Automatischer Start, Neue Version, Fehlerbilder), Inhaltsverzeichnis-Eintrag, keine firmenspezifische Adresse im Kapitel" + requirement: "DESK-03" + verification: + - kind: other + ref: "DOCS1-OK Pruefkette aus 18-06-PLAN.md (Kapitel, TOC-Anker, 9 Unterabschnitte, Pflichtbeschriftungen 'Trotzdem ausführen'/'Desktop-App herunterladen (Windows)'/'Mit Windows starten', 0 ctl.de/vicolab-Treffer im Kapitel)" + status: pass + human_judgment: false + - id: D2 + description: "CHANGELOG-Stichpunkt im Wortlaut von D-17 unter Unveröffentlicht/Neu, oberhalb der ersten Versionsueberschrift" + requirement: "DESK-03" + verification: + - kind: other + ref: "node-Pruefung aus 18-06-PLAN.md (Position zwischen '## Unveröffentlicht' und der naechsten Versionsueberschrift)" + status: pass + human_judgment: false + - id: D3 + description: "Betriebshandbuch Kapitel 10 (Pipeline-Herkunft, Ablageort /app/desktop-dist im Abbild, Release-Anhaenge, DESKTOP_DIST_DIR-Tabelle, Fehlerbilder-Tabelle) plus Verweissatz in Kapitel 9" + requirement: "DESK-04" + verification: + - kind: other + ref: "BETRIEB-Pruefkette aus 18-06-PLAN.md (Kapitelueberschrift, TOC-Eintrag '10. [', DESKTOP_DIST_DIR, /app/desktop-dist, Abschnitt Fehlerbilder)" + status: pass + human_judgment: false + - id: D4 + description: "CI/CD-Runbook: 'vier' statt 'drei' Jobs, Job desktop ausfuehrlich beschrieben (Cross-Bau-Reihenfolge, Cache-Pfade, Cache-Schluessel desktop-dist-{sha}, Begruendung Cache statt upload-artifact), drei neue Fehlerbehebungs-Unterabschnitte (Job desktop, cache miss, Release-Upload 413) inkl. der realen Fehlerursache aus 18-05 (fehlende clippy-Komponente)" + requirement: "DESK-04" + verification: + - kind: other + ref: "CI-Pruefkette aus 18-06-PLAN.md (cargo-xwin >=2, desktop-dist-, upload-artifact, 'vier Jobs')" + status: pass + human_judgment: false + - id: D5 + description: "Entwicklungshandbuch: apps/desktop nicht mehr als Grundgeruest beschrieben, neuer Abschnitt 'Desktop-App lokal bauen' (Voraussetzungen, desktop-version.sh, lokaler AppImage-Bau, desktop-collect.sh, Hinweis Windows-Installer nur im CI), Testabschnitt um 'vitest run src/desktop' und cargo check/clippy ergaenzt" + requirement: "DESK-03" + verification: + - kind: other + ref: "ENTWICKLUNG-Pruefkette aus 18-06-PLAN.md (0 Treffer 'Tauri-Grundgerüst', Abschnittsueberschrift, desktop-version.sh, vitest run src/desktop)" + status: pass + human_judgment: false + - id: D6 + description: "REQUIREMENTS.md: neuer Abschnitt 'Phase 18 — Desktop-Client fertigstellen' mit DESK-01..05, fuenf Traceability-Zeilen, aktualisierter Coverage-Satz" + requirement: "DESK-01" + verification: + - kind: other + ref: "REQ-OK Pruefkette aus 18-06-PLAN.md (5 DESK-Eintraege, 5 Traceability-Zeilen)" + status: pass + human_judgment: false + - id: D7 + description: "Gesamtlaeufe am Phasenende: API- und Web-Testsuite, beide Typpruefungen, cargo check fuer den Desktop-Client" + requirement: "DESK-05" + verification: + - kind: integration + ref: "pnpm --filter @tessera/api exec vitest run (68 Dateien, 1086 Tests, 0 fehlgeschlagen)" + status: pass + - kind: integration + ref: "pnpm --filter @tessera/web exec vitest run (55 Dateien, 365 Tests, 0 fehlgeschlagen)" + status: pass + - kind: other + ref: "pnpm --filter @tessera/api type-check / pnpm --filter @tessera/web type-check (beide fehlerfrei)" + status: pass + - kind: other + ref: "cargo check (apps/desktop/src-tauri) -> Finished" + status: pass + human_judgment: false + - id: D8 + description: "Bedienprobe des Nutzers auf einem Windows-PC: Download, Installation mit SmartScreen-Anleitung, Erststart mit Server-Adresse, Anmeldung im App-Fenster, Infobereich/Tray-Verhalten, Autostart-Umschaltung, Beenden, Neustart mit gemerkter Adresse, Einstellungsseite Desktop-App" + requirement: "DESK-02" + verification: [] + human_judgment: true + rationale: "Diese Ausfuehrungsumgebung hat keinen Windows-PC und keine grafische Sitzung — die Bedienprobe (Schritte 1-10 aus dem Plan-) kann nur der Nutzer selbst auf seinem PC durchfuehren. Dieser Plan liefert Dokumentation und alle automatisierbaren Gesamtlaeufe; die Bedienprobe ist unten unter 'Manuelle Abnahme (ausstehend)' als offener Schritt dokumentiert. DESK-03/04/05 bleiben in REQUIREMENTS.md deshalb bewusst auf Pending, bis das Ergebnis vorliegt." + +duration: 21min +completed: 2026-09-16 +status: complete +--- + +# Phase 18 Plan 06: Handbuecher, CHANGELOG, REQUIREMENTS und Gesamtlaeufe zum Abschluss der Desktop-Client-Phase Summary + +**Anwender-, Betriebs- und Entwicklungshandbuch sowie das CI/CD-Runbook beschreiben jetzt vollstaendig die fertige Desktop-App (Download, SmartScreen-Installation, Pipeline-Job, Ablageort im Abbild, Release-Anhaenge, lokaler Bau); CHANGELOG und REQUIREMENTS sind nachgezogen; alle automatisierten Gesamtlaeufe (API 1086 Tests, Web 365 Tests, beide Typpruefungen, cargo check) sind gruen — die Windows-Bedienprobe des Nutzers steht noch aus.** + +## Performance + +- **Duration:** 21 min +- **Started:** 2026-09-16T15:04:00Z (geschaetzt, erster Lesevorgang der Referenzdateien) +- **Completed:** 2026-09-16T15:25:22Z +- **Tasks:** 3 +- **Files modified:** 6 + +## Accomplishments +- `docs/anleitung-anwender.md`: neues Kapitel „Desktop-App" mit neun Unterabschnitten (Was es ist, Herunterladen, Installation unter Windows inkl. SmartScreen-Anleitung „Trotzdem ausführen", Installation unter Linux, Erster Start mit Server-Adresse, Fenster/Infobereich/Beenden, Automatischer Start, Neue Version, Wenn etwas nicht klappt) samt Inhaltsverzeichnis-Eintrag; nur Platzhalteradressen, keine Firmenadresse im Kapitel. +- `CHANGELOG.md`: neuer Stichpunkt „Desktop-App für Windows und Linux: Download auf der Anmeldeseite und unter Einstellungen → Desktop-App" unter „Unveröffentlicht" → „Neu" (D-17, Wortlaut exakt). +- `docs/anleitung-betrieb.md`: neues Kapitel 10 „Desktop-App: Pakete und Release-Dateien" (Pipeline-Herkunft, Ablageort `/app/desktop-dist` im API-Abbild samt `manifest.json`, Release-Anhaenge am Gitea-Release, `DESKTOP_DIST_DIR`-Tabelle, Fehlerbilder-Tabelle mit vier Symptomen); Kapitel 9 um einen Verweissatz ergaenzt. +- `docs/ci-cd-setup.md`: aus „drei" wurden „vier" Jobs, der Job `desktop` ist jetzt ausfuehrlich beschrieben (Systemabhaengigkeiten, Rust-Toolchain inkl. `clippy`-Komponente, Cache-Reihenfolge vor den Windows-Werkzeugen, Cross-Bau-Reihenfolge AppImage-vor-NSIS, Cache-Schluessel `desktop-dist-{sha}`, Begruendung Cache statt `upload-artifact`); drei neue Fehlerbehebungs-Unterabschnitte („Job desktop schlaegt fehl" inkl. der in 18-05 real aufgetretenen fehlenden `clippy`-Komponente, „publish: cache miss", „Release-Upload 413"). +- `docs/anleitung-entwicklung.md`: `apps/desktop` wird nicht mehr als Grundgeruest beschrieben, sondern als fertiger Tauri-Client; neuer Abschnitt „Desktop-App lokal bauen" (Voraussetzungen, `desktop-version.sh`, lokaler AppImage-Bau, `desktop-collect.sh`, Hinweis: Windows-Installer nur im CI); Testabschnitt um `pnpm --filter @tessera/api exec vitest run src/desktop` und `cargo check`/`cargo clippy` ergaenzt. +- `.planning/REQUIREMENTS.md`: neuer Abschnitt „Phase 18 — Desktop-Client fertigstellen" mit DESK-01..05 (DESK-01/02 aus Phase 6 fortgefuehrt und als Complete markiert, DESK-03..05 neu und auf Pending, bis die Bedienprobe vorliegt), fuenf Traceability-Zeilen, aktualisierter Coverage-Satz. +- Gesamtlaeufe am Ende der Phase: `pnpm --filter @tessera/api exec vitest run` — 68 Dateien, **1086 Tests, alle gruen**; `pnpm --filter @tessera/web exec vitest run` — 55 Dateien, **365 Tests, alle gruen**; `pnpm --filter @tessera/api type-check` und `pnpm --filter @tessera/web type-check` — beide fehlerfrei; `cargo check` in `apps/desktop/src-tauri` — `Finished`. + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Anwenderhandbuch — Kapitel "Desktop-App"; CHANGELOG-Stichpunkt** - `43c7061` (docs) +2. **Task 2: Betriebshandbuch Kapitel 10, CI/CD-Runbook, Entwicklungshandbuch** - `8f2069b` (docs) +3. **Task 3: REQUIREMENTS nachziehen, Gesamtlaeufe, Bedienprobe des Nutzers** - `29219ba` (docs) + +**Plan metadata:** commit pending (this SUMMARY + STATE.md/ROADMAP.md) + +## Files Created/Modified +- `docs/anleitung-anwender.md` - Kapitel „Desktop-App" (9 Unterabschnitte), TOC-Eintrag +- `docs/anleitung-betrieb.md` - Kapitel 10, TOC-Eintrag, Verweissatz in Kapitel 9 +- `docs/anleitung-entwicklung.md` - Monorepo-Beschreibung aktualisiert, Abschnitt „Desktop-App lokal bauen", Testabschnitt ergaenzt +- `docs/ci-cd-setup.md` - Job `desktop` beschrieben, drei neue Fehlerbehebungs-Unterabschnitte +- `CHANGELOG.md` - Stichpunkt unter Unveröffentlicht/Neu +- `.planning/REQUIREMENTS.md` - Abschnitt DESK-01..05, Traceability-Zeilen, Coverage-Satz + +## Decisions Made +- DESK-03/04/05 bleiben in REQUIREMENTS.md auf Pending, bis die Bedienprobe des Nutzers (Windows-Installation, siehe unten) tatsaechlich stattgefunden hat — dieser Plan konnte nur die Dokumentation und die automatisierten Gesamtlaeufe liefern, nicht die grafische Bedienprobe (kein Windows-PC/keine grafische Sitzung in dieser Ausfuehrungsumgebung). +- In Kapitel 9 des Betriebshandbuchs einen Verweissatz auf das neue Kapitel 10 ergaenzt, statt Kapitel 10 isoliert am Dateiende stehen zu lassen — der Freigabe-Ablauf und die Desktop-Release-Anhaenge gehoeren inhaltlich zusammen. + +## Deviations from Plan + +None - plan executed exactly as written. + +## Issues Encountered +None. + +## Manuelle Abnahme (ausstehend) + +Die folgende Bedienprobe konnte in dieser Ausfuehrungsumgebung nicht durchgefuehrt werden (kein Windows-PC, keine grafische Sitzung) und steht noch aus. Voraussetzung: der Testserver laeuft auf dem Beta-Stand mit den Paketen (Lauf 367, Commit `742fb5c` — `Tessera-Setup-1.1.0-beta.742fb5c.exe`, `Tessera-1.1.0-beta.742fb5c.AppImage`); `docker compose pull` und `docker compose up -d --force-recreate` fuehrt der Nutzer dort selbst aus. + +1. Anmeldeseite des Testservers im Browser oeffnen: Unter dem Formular steht „Desktop-App herunterladen (Windows)", daneben „Linux-Version", darunter „Version 1.1.0". +2. Auf den Windows-Link klicken: Es laedt `Tessera-Setup-1.1.0-beta.{kennung}.exe` (wenige MB). +3. 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). +4. 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**. +5. Anmelden. Fenster mit X schliessen: Die App bleibt im Infobereich (Symbol mit Tessera-Zeichen). Linksklick auf das Symbol: Fenster ist wieder da. +6. Rechtsklick auf das Symbol: Menue „Öffnen", „Update herunterladen" (ausgegraut, weil die aktuelle Version installiert ist), „Mit Windows starten" (ohne Haken), „Beenden" — mit Umlauten. +7. „Mit Windows starten" anklicken: Haken erscheint; erneut anklicken: Haken verschwindet. +8. „Beenden": App ist weg (auch aus dem Infobereich). +9. App erneut starten: Sie geht **direkt** zu Tessera (Adresse gemerkt), Fenstergroesse und -position wie beim Beenden. +10. 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. +11. Falls ein Linux-Rechner greifbar ist: AppImage herunterladen, ausfuehrbar machen, starten — Erststart-Seite wie unter 4. + +**Nach erfolgreicher Bedienprobe:** DESK-03/04/05 in `.planning/REQUIREMENTS.md` (Requirement-Liste und Traceability-Tabelle) auf Complete setzen. + +### Auf den naechsten Freigabe-Tag vertagt (nicht Teil dieser Phase) + +Zwei Punkte lassen sich erst beim naechsten Freigabe-Tag pruefen und gehoeren in die Abnahme dieser Version, nicht in diese Phase: + +- **(a) Update-Hinweis:** 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) Release-Anhang:** Der Gitea-Release `v1.2.0` traegt `Tessera-Setup-1.2.0.exe` und `Tessera-1.2.0.AppImage` als Dateien. + +## User Setup Required + +Keine externe Dienstkonfiguration noetig. Die Bedienprobe oben ist keine Konfigurationsaufgabe, sondern eine manuelle Verifikation durch den Nutzer. + +## Next Phase Readiness +- Die Desktop-Client-Phase ist inhaltlich und dokumentarisch abgeschlossen: alle sechs Plaene (18-01 bis 18-06) sind erledigt, alle automatisierten Gesamtlaeufe sind gruen. +- Offen bleibt ausschliesslich die manuelle Bedienprobe des Nutzers auf einem Windows-PC (siehe „Manuelle Abnahme (ausstehend)" oben) sowie die zwei auf den naechsten Freigabe-Tag vertagten Punkte (Update-Hinweis, Release-Anhang). +- Kein technischer Blocker fuer die naechste Phase oder fuer eine Freigabe — die Bedienprobe ist eine reine Abnahmehandlung, keine offene Implementierungsarbeit. + +--- +*Phase: 18-desktop-client-fertigstellen* +*Completed: 2026-09-16* + +## Self-Check: PASSED + +All modified/created files verified on disk (`docs/anleitung-anwender.md`, `docs/anleitung-betrieb.md`, `docs/anleitung-entwicklung.md`, `docs/ci-cd-setup.md`, `CHANGELOG.md`, `.planning/REQUIREMENTS.md`, this SUMMARY). All three task commits found in `git log` (`43c7061`, `8f2069b`, `29219ba`). All plan-level `` items re-run and passing: `DOCS1-OK` (Anwenderhandbuch Kapitel/TOC/9 Unterabschnitte/Pflichtbeschriftungen/0 Firmenadressen, CHANGELOG-Position), `DOCS2-OK` (Betriebshandbuch Kapitel 10/TOC/Variable/Ablageort/Fehlerbilder, CI/CD-Runbook vier Jobs/cargo-xwin/Cache-Schluessel/upload-artifact-Begruendung, Entwicklungshandbuch kein Grundgeruest mehr/neuer Abschnitt/Testzeile), `REQ-OK` (5 DESK-Eintraege, 5 Traceability-Zeilen). `ALL-GREEN` bestaetigt: API 1086/1086, Web 365/365, beide Typpruefungen fehlerfrei, `cargo check` `Finished`. Die Bedienprobe (Windows-PC) ist laut Plan-Checkpoint-Protokoll nicht Teil dieses automatisierten Selbst-Checks — siehe „Manuelle Abnahme (ausstehend)" oben.