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/desktoplä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
mainintegriert; AD-33,AGENTS.mdund 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ärtetesBrowserWindow.apps/desktop/src/preload.tsundipc.ts: kleine, validierte Native-Bridge.apps/desktop/src/url-policy.ts: Trusted-Origin-, Deep-Link- und External-Navigation-Vertrag.apps/desktop/src/updates.tsundupdate-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:
0e7c8e906·feat(desktop): add secure Electron shelldf496a297·feat(desktop): add native lifecycle and updates5c5cc3af3·build(desktop): package branded cross-platform clients6d9f322c8·feat(desktop): embed public update configuration006d319f2·ci(desktop): enforce client quality gates8b9071fa3·docs(desktop): record client release contract1f66d3562·fix(desktop): guard shutdown navigation race
Prüfstand:
pnpm typecheckundpnpm lintgrü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, insbesondereapps/desktop/README.mdund 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.