Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/DESKTOP-1.md
T

281 lines
16 KiB
Markdown

<!-- markdownlint-disable MD013 MD060 -->
# DESKTOP-1 · Electron-Client produktionsreif fertigstellen
| Feld | Wert |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Typ** | Dev (Desktop / Release) |
| **Owner** | Raffael |
| **Phase** | Nachzug außerhalb der aktuellen v1/v2-Kernkette |
| **Cycle/Fenster** | Backlog · bewusst später |
| **Status** | Backlog · Prototyp 6/12 DoD = 50 % done |
| **Plane** | [HIVEGRID-249](https://project.tool-ctrl.de/toolctrl/projects/35d0d968-8ab3-40cc-97b8-b81d917dc5df/issues/64897557-907f-4f7c-8431-0fe352ab66df) |
## Entscheidung und aktueller Kontext
Der User hat am 2026-08-03 einen ersten Desktop-Prototyp für macOS, Windows und
Linux ausdrücklich beauftragt und anschließend entschieden, die
Produktionsreife als Backlog-Nachzug zu parken. Der Desktop-Client bleibt eine
dünne Electron-Hülle um die bestehende HiveGrid-Web-App. Es entsteht keine
zweite UI-, Fachlogik-, Auth- oder Datenschicht.
Die Desktop-Entscheidung ist im lokalen Prototyp-Branch als **AD-33** vorbereitet.
Sie ändert **AD-17 nicht**: Mobile bleibt responsive Web/PWA-only. Vor einem
Code-Merge müssen der AD-33-Eintrag und die zugehörige operative Klarstellung in
`AGENTS.md` gemeinsam mit dem Desktop-Paket geprüft und übernommen werden. Damit
wird die noch auf `main` vorhandene allgemeine Anti-Listen-Formulierung nicht
stillschweigend durch diese Ticket-Doc gelockert.
**Wichtig:** Der Prototyp-Branch und seine Commits existieren zum Zeitpunkt
dieser Doc nur lokal und wurden noch nicht gepusht.
- Worktree:
`/Users/raffaelsheikh/Documents/GitHub/HiveGrid-Cloud-feat-desktop-client-prototype`
- Branch: `feat/desktop-client-prototype`
- Basis: `origin/main@b1f14d63e5252e0a70029ece139591b98e26d3b8`
- Paket-Dokumentation im Prototyp-Branch: `apps/desktop/README.md`
- Lokale Build-Artefakte: `artifacts/desktop/` (gitignored)
## Abhängigkeiten & Parallelität
- **blocked-by:** Keine Plane- oder Ticket-Abhängigkeit hinterlegt.
- **blocks:** Keine Plane- oder Ticket-Abhängigkeit hinterlegt.
- **Externe Voraussetzungen vor Release:** Apple Developer ID und
Notarisierungszugang, Windows-Authenticode-Zertifikat sowie ausführbare
macOS-/Windows-/Linux-Release-Runner oder gleichwertige kontrollierte
Build-Maschinen. Verfügbarkeit und Owner werden beim Wiederaufnehmen geprüft;
sie sind aktuell nicht als formale Plane-Blocker modelliert.
- Die Arbeit ist unabhängig von Prisma, RLS, Entity Model und der fachlichen
v1/v2-Kernkette. Es gibt keine Schema- oder Migrationsänderung.
- Web-App, Auth und fachliche Screens bleiben alleinige Produktquelle. Änderungen
an diesen Flächen gehören in ihre jeweiligen Tickets, nicht in `DESKTOP-1`.
- Mobile und App-Store-Scope bleiben außerhalb dieses Tickets. Desktop-Store-
Distribution darf nur nach eigener Produktentscheidung ergänzt werden.
## Was wir bauen
Der vorhandene Prototyp wird zu einem reproduzierbar veröffentlichten,
signierten und updatefähigen Desktop-Client für:
- macOS Apple Silicon und Intel,
- Windows x64,
- Linux x64.
Der Client lädt ausschließlich die freigegebene HiveGrid-Web-Origin. Native
Zuständigkeit bleibt auf sicheren Web-Container, Lifecycle, Single Instance,
Fensterzustand, Menüs, Deep Links, Badge, Offline-Fallback und Updates begrenzt.
Der Produktionsnachzug umfasst außerdem:
- native Signierung, Notarisierung und installierbare Paketformate,
- reproduzierbare Gitea-Release-Jobs auf den Zielplattformen,
- unveränderliche Release-Artefakte und Prüfsummen,
- einen signierten Update-Kanal mit echtem Upgrade-/Rollback-Drill,
- native Smoke-Tests auf allen Zielbetriebssystemen,
- Installations-, Release- und Rollback-Dokumentation.
## Benötigte Screens
Keine neue Fach- oder Subframe-Oberfläche. Die bestehende Web-App bleibt die
vollständige sichtbare Produktsurface.
Native beziehungsweise lokale Systemflächen sind auf Folgendes begrenzt:
| Fläche | Inhalt |
| ---------------- | ---------------------------------------------------------------------- |
| App-Menü | Zurück/Vorwärts, Reload, Zoom, Vollbild, Update-Prüfung, Hilfe |
| Offline-Fallback | Klartextstatus, Ziel-Origin und erneuter Verbindungsversuch |
| Update-Dialog | Update verfügbar, Downloadstatus, Neustart jetzt/später |
| Betriebssystem | Installer, Signatur-/Notarisierungsdialoge und Deep-Link-Registrierung |
Die finale Web-Optik wird nicht im Electron-Paket dupliziert. Es gibt keinen
`design-nachzug` und keinen eigenen Subframe-Screen für dieses Ticket.
## Definition of Done
- [x] **Dünne Sicherheitsarchitektur:** `apps/desktop` lädt nur die bestehende
Web-App; Node-Integration und Webviews sind aus, Context Isolation,
Sandbox, Web Security, enge Navigation und validierte Preload-IPC sind
aktiv. AD-17 bleibt für Mobile unverändert.
- [x] **Native Desktop-Grundfunktionen:** Single Instance, Fensterzustand,
native Menüs, Deep Links, Badge, sichere externe Links und Offline-Fallback
sind implementiert.
- [x] **Vier reproduzierbare Prototyp-Builds:** macOS arm64/x64, Windows x64 und
Linux x64 werden aus demselben Workspace gebaut; ASAR-Integrität,
gehärtete Electron-Fuses und HiveGrid-Branding sind enthalten.
- [x] **Update-Grundlage fail-closed:** macOS/Windows verwenden Electrons
`autoUpdater`, Linux einen manuellen Downloadpfad; ohne konfigurierte
Release-URL bleiben automatische Updates deaktiviert. Öffentliche URLs
sind build-time einbettbar und zur Laufzeit überschreibbar.
- [x] **Automatisierte Qualität:** Desktop-Typecheck, Unit-Tests, Build und
echter Electron-E2E sind vorhanden; Root-Docker- und Gitea-CI-Verträge
berücksichtigen das Workspace-Paket.
- [x] **Lokaler macOS-Proof:** Der finale arm64-Prototyp startet nativ, stellt
das App-Menü bereit und beendet sich über den normalen App-Lifecycle;
Binärformat, ZIP-Integrität, lokale Signatur und Fuses sind geprüft.
- [ ] **Branch gesichert und integriert:** Der lokale Prototyp-Branch ist
gepusht, per PR geprüft und mit normalem Merge-Commit in `main` integriert;
AD-33, `AGENTS.md` und diese Ticket-Doc sind widerspruchsfrei.
- [ ] **Echte Zielsystem-Smokes:** Installation, Start, Login, Session-Restore,
Navigation, Deep Link, Offline-Fallback und Deinstallation sind auf
Windows x64 und Linux x64 sowie erneut auf einem produktionssignierten
macOS-Build geprüft.
- [ ] **Produktionspakete signiert:** macOS besitzt Developer-ID-Signatur und
Notarisierung; Windows besitzt Authenticode und einen update-kompatiblen
Installer; Linux besitzt mindestens AppImage sowie die entschiedenen
DEB-/RPM-Pakete. Keine produktive Warnung wird durch Test-Flags umgangen.
- [ ] **Release-Automation:** Native Gitea-Runner bauen aus einem Tag
unveränderliche Artefakte, veröffentlichen SHA-256-Prüfsummen und hängen
sie an einen versionierten Gitea-Release. Secrets bleiben ausschließlich
im jeweiligen Runner-/Signing-Kontext.
- [ ] **Update- und Rollback-Drill:** Ein signierter Build aktualisiert sich über
den veröffentlichten Kanal auf die nächste Version; Feed, Signatur,
Neustart, fehlgeschlagener Download und Rückkehr zum letzten freigegebenen
Artefakt sind auf macOS und Windows bewiesen. Linux folgt dem dokumentierten
Paketmanager-/Downloadpfad.
- [ ] **Release-Abnahme:** Security-Review, Lizenz-/SBOM-Prüfung, Installations-,
Release- und Rollback-Runbook sowie abschließender UAT sind dokumentiert;
Ticket-Doc und Plane enthalten den Proof.
**Fortschritt: 6/12 DoD = 50 % done · 6 Punkte offen · aktuell keine formale
`blocked-by`-Kante; das Ticket ist bewusst zurückgestellt.**
## DoD-Proof und Nicht-genug-Kriterien
| DoD | Fertigkeitskriterium | Proof | Zählt nicht als fertig |
| --- | --------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------ |
| 1 | Sicherheitsoptionen und IPC-Grenze im Release-Build aktiv | Unit-/E2E-Test und Fuse-Ausgabe | nur ein `BrowserWindow`, das eine URL lädt |
| 2 | Alle begrenzten nativen Flows funktionieren | Desktop-Tests und manueller Smoke | Menüpunkte ohne funktionalen Handler |
| 3 | vier portable Test-Bundles reproduzierbar | Paketbefehle, `file`, `unzip -t`, Fuses | nur der Host-Mac-Build |
| 4 | kein Feed führt sicher zu deaktivierten Updates | Unit-Test und Status-API | ungeprüfte oder hartkodierte Download-URL |
| 5 | Desktop ist Teil der lokalen/CI-Qualitätsverträge | grüne fokussierte Tests und CI-Verifier | nur ein lokaler manueller Start |
| 6 | finaler arm64-Build startet und beendet sauber | nativer macOS-Smoke | nur Dev-Electron über Playwright |
| 7 | Commits sind remote geprüft und normal gemerged | PR, grüne CI, Merge-Commit | lokaler Branch oder Squash-Merge |
| 8 | Nutzerflows laufen auf echten Zielsystemen | UAT-Protokoll je OS | Cross-Packaging auf macOS |
| 9 | OS-Vertrauenskette und Installer sind produktiv | Signatur-, Notarisierungs- und Installer-Proof | ad-hoc signiertes ZIP |
| 10 | Tag erzeugt veröffentlichte immutable Releases | grüner Release-Run, Assets, Prüfsummen | manuell erzeugtes `artifacts/`-Verzeichnis |
| 11 | echtes N→N+1-Update und Rollback bewiesen | Feed-/Installer-/Rollback-Protokoll | Unit-Test des Update-Controllers |
| 12 | Übergabe ist operativ vollständig | Review, SBOM, Runbooks, UAT-Sign-off | README ohne ausgeführten Release-Proof |
## Technische Bausteine
- `apps/desktop/src/main.ts`: Lifecycle und gehärtetes `BrowserWindow`.
- `apps/desktop/src/preload.ts` und `ipc.ts`: kleine, validierte Native-Bridge.
- `apps/desktop/src/url-policy.ts`: Trusted-Origin-, Deep-Link- und
External-Navigation-Vertrag.
- `apps/desktop/src/updates.ts` und `update-settings.ts`: Update-Modi,
Statusmodell und öffentliche Release-Konfiguration.
- `apps/desktop/scripts/build.mjs`: deterministischer Main-/Preload-Build.
- `apps/desktop/scripts/package.mjs`: Plattformpakete, Branding, ASAR,
Signatur-Hook und Fuses.
- `apps/desktop/scripts/e2e.mjs`: echter Electron-E2E gegen einen lokalen
Testserver.
- `scripts/ci/run-quality-groups.sh`: Desktop-Qualitätsgruppe nach den
bestehenden bounded Core-Gruppen.
Öffentliche Konfiguration:
- `HIVEGRID_DESKTOP_WEB_URL`: Ziel-Web-App; im Paket nur HTTPS.
- `HIVEGRID_DESKTOP_UPDATE_URL`: macOS-/Windows-Update-Feed.
- `HIVEGRID_DESKTOP_DOWNLOAD_URL`: manueller Linux-/Fallback-Download.
- `HIVEGRID_DESKTOP_MAC_SIGN_IDENTITY`: macOS-Signing-Identität beim Build.
Keine Signing-Zertifikate, Passwörter, PATs oder Update-Secrets werden in Git,
Plane, Build-Logs oder Artefakt-Metadaten geschrieben.
## Vorhandener Prototyp-Proof (2026-08-03)
Atomare lokale Commits:
1. `0e7c8e906` · `feat(desktop): add secure Electron shell`
2. `df496a297` · `feat(desktop): add native lifecycle and updates`
3. `5c5cc3af3` · `build(desktop): package branded cross-platform clients`
4. `6d9f322c8` · `feat(desktop): embed public update configuration`
5. `006d319f2` · `ci(desktop): enforce client quality gates`
6. `8b9071fa3` · `docs(desktop): record client release contract`
7. `1f66d3562` · `fix(desktop): guard shutdown navigation race`
Prüfstand:
- `pnpm typecheck` und `pnpm lint` grün.
- `pnpm test`: 1.194 Testdateien und 8.325 Tests grün; 60 bewusst
deaktivierte Integrationstests übersprungen.
- Desktop: 44/44 Unit-Tests, Typecheck, Build und echter Electron-E2E auf
macOS arm64 grün.
- Alle vier ZIPs bestehen `unzip -t`; Binärformate sind Mach-O arm64/x64,
PE32+ x64 und ELF x64.
- Beide Mac-Prototypen bestehen die lokale ad-hoc-Signaturprüfung; alle vier
Builds besitzen die erwarteten gehärteten Fuses.
- Der native Mac-Smoke nutzte für den wiederholt ad-hoc signierten lokalen
Build Chromiums isolierten Test-Keychain. Das ist kein Release-Flag und darf
in produktiven Startpfaden nicht verwendet werden; eine stabile Developer-ID-
Signatur muss den regulären Keychain-Pfad beweisen.
Lokale SHA-256-Prüfsummen des letzten Prototyp-Builds:
- macOS arm64: `252bb76b248a378106a8f7e071a61cd806cc1e8928589c50ec3a82a9d5edc3b1`
- macOS x64: `05c23c17db3a051fab472bc54507158ccd2a7d7dba775884f2ca36781d8c6137`
- Linux x64: `3fd15c50439750f9b8bb1f8b97c449e46d6002855770d16dc5169284d8d61be1`
- Windows x64: `1ccb839161f66c00511b02c8e658b51b5a5429fd69f6eb22769648bbf4ca04ea`
Die Prüfsummen sind nur lokaler Proof. Sie werden nicht als veröffentlichter
Release-Vertrag behandelt, weil `artifacts/desktop/` gitignored ist.
## Verifikation vor Commit, Push und Release
Fokussiert:
```bash
pnpm --filter @hivegrid/desktop typecheck
pnpm --filter @hivegrid/desktop test
pnpm --filter @hivegrid/desktop build
pnpm --filter @hivegrid/desktop test:e2e
```
Vor Push/PR zusätzlich die vollständige `docs/AGENT-CHECKLIST.md` und alle
betroffenen CI-/Docker-Verifier. Vor Release außerdem:
- ZIP-/Installer-Integrität und SHA-256,
- Fuse- und ASAR-Integritätsprüfung,
- native Signatur- und Notarisierungsprüfung,
- SBOM-/Lizenz- und Production-Audit,
- echter Installations-/Update-/Rollback-Smoke je Zielbetriebssystem.
## Rollback
- Vor dem Merge: den Desktop-PR schließen; die bestehende Web-App bleibt
unverändert nutzbar.
- Nach dem Merge ohne Release: die Desktop-Commits normal reverten. Es gibt
keine Datenbankmigration und keinen serverseitigen Zustand zurückzusetzen.
- Nach Release: Update-Feed auf das letzte freigegebene, weiterhin signierte
Artefakt zurücksetzen und dieses erneut als aktuelle Version veröffentlichen.
Bereits installierte Clients werden nicht durch Löschen alter Assets
unbrauchbar gemacht.
- Zertifikate oder Secrets werden nur nach ausdrücklichem Auftrag rotiert.
## Quellen
- Plane: `HIVEGRID-249` / `DESKTOP-1`.
- User-Auftrag und ausdrückliche Desktop-Freigabe vom 2026-08-03.
- Lokaler Branch `feat/desktop-client-prototype`, insbesondere
`apps/desktop/README.md` und der dort vorbereitete AD-33-Nachzug.
- `AGENTS.md` · Arbeitsmodus, Ticket-Treue, Desktop-/Mobile-Grenzen und
operative Checkliste.
- [Electron Security](https://www.electronjs.org/docs/latest/tutorial/security)
- [Electron Updates](https://www.electronjs.org/docs/latest/tutorial/updates)
- [Electron Distribution](https://www.electronjs.org/docs/latest/tutorial/application-distribution)
- [Electron Code Signing](https://www.electronjs.org/docs/latest/tutorial/code-signing)
## Umsetzungs-Notiz
### 2026-08-03 · Prototyp gebaut und Produktionsnachzug geparkt
Der sichere Desktop-Prototyp wurde in sieben atomaren lokalen Commits erstellt,
für vier Plattform-/Architekturziele paketiert und auf macOS arm64 automatisiert
sowie nativ geprüft. Plane-Ticket `HIVEGRID-249` wurde im Backlog mit Priorität
Low und Owner Raffael angelegt. Der User hat entschieden, die Produktionsreife
erst nach anderen Aufgaben fortzusetzen.
**DESKTOP-1: 6/12 DoD = 50 % done · 6 Punkte offen · 0 formale Plane-Blocker ·
bewusst zurückgestellt.**