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

16 KiB

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

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

  • 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.
  • Native Desktop-Grundfunktionen: Single Instance, Fensterzustand, native Menüs, Deep Links, Badge, sichere externe Links und Offline-Fallback sind implementiert.
  • 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.
  • 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.
  • 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.
  • 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:

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
  • Electron Updates
  • Electron Distribution
  • Electron 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.