281 lines
16 KiB
Markdown
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.**
|