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

9.0 KiB

R-P1c · P1 Hot-Swap-Maschine + Walking-Skeleton + PWA

Typ Dev (Code)
Owner Raffael (NEU — übernommen von Akeshan; ex-AK-P1c, Umverteilung 16.06.)
Phase P1 — Fundament & Walking-Skeleton
Cycle/Fenster W1 — Fundament & Identität · fällig 2026-06-17 · Gate W1
Status Done

Abhängigkeiten & Parallelität

  • Blocked by: R-P1a (URL-Schemata/Contracts), R-P1b (Service-Kerne + tenantHasModule()-Muster) — abweichend vom AK-P1c-Snapshot („blocked-by: —"), da R-P1c das Konnektor-Gate + die VM-Konvention erst andocken kann, wenn R-P1a/b stehen; P1 läuft Raffael sequentiell.
  • Blocks: alle Screen-Andock-Tickets, Gate W1 (Walking-Skeleton = grüner Smoke-Test-Anker)
  • Läuft parallel zu: D-D0a/D-D0b (David Archetypen-Baseline, gleiche W1) — baut direkt darauf auf; AK-INFRA1/2 (Ops).
  • Konflikt-Risiko: keines — Konvention/Adapter/Beispielroute, kein Fach-Schema. db push auf Branch (AD-21).

Was wir bauen

Die Hot-Swap-Maschine (VM-Konvention + Action-Callback-Contract + Subframe-Adapter, damit Davids Subframe-Designs ohne Logik-Bruch in die App geswapt werden können), das Visual-Regression-Gate + den Hot-Swap-Drill (grüner Smoke-Test gegen packages/ui-mock) und die Walking-Skeleton-Route: eine in der Sidebar registrierte Beispielroute, die das View-Model-im-Loader-Muster + das Konnektor-Gating (tenantHasModule()) exemplarisch zeigt. Dazu das PWA-Manifest (PWA-only v1, AD-17/Cut #14 — kein Expo/native).

Benötigte Screens (Backend bedient — Design liefert D-D0a/D-D0b)

Screen [Route] Kern-Inhalt Liefert (Design)
App-Shell-Andock [global] Sidebar mit Konnektor-Gating-Zustand (aktiv/ausgeblendet/gesperrt je tenantHasModule()), Topbar, Status-Banner-System D-D0a (A1)
Walking-Skeleton-Route [Beispiel-Modul-Route] minimal aus A2 komponiert; Loader gibt View-Model zurück, Konnektor-Gate exemplarisch, grüner Smoke-Test D-D0b (A2 minimal)

Definition of Done

  • VM-Konvention (View-Model im Loader) + Action-Callback-Contract + Subframe-Adapter stehen
  • packages/ui-mock + Visual-Regression-Gate + Hot-Swap-Drill (grün)
  • Walking-Skeleton-Route in Sidebar registriert, Konnektor-Gate tenantHasModule() exemplarisch angewandt
  • PWA-Manifest (installierbar; PWA-only v1, AD-17 — kein native/Store)
  • Smoke-Test grün gegen ui-mock

Technische Bausteine

  • Keine Fach-Entities — nutzt das tenantHasModule()-Muster aus R-P1b und die Contracts aus R-P1a.
  • Subframe-Adapter = Brücke Davids Subframe-Output → App-Komponenten (Hot-Swap ohne Logik-Umschrieb); VM-Konvention macht Loader testbar gegen ui-mock.
  • Sidebar-Registrierung demonstriert die drei Konnektor-Zustände (aktiv/ausgeblendet/gesperrt).
  • PWA-Manifest minimal (Installierbarkeit) — voller PWA-Ausbau (Service-Worker/Offline/Push) → v2 (VA-P27a/b).

Quellen (granular)

  • ROADMAP.md → Phase 1 · Milestones:, Milestones M013-view-model-konvention, M014-action-callback-contract, M015-subframe-adapter-layer, M016-visual-regression-gate, M017-hot-swap-drill
  • REQUIREMENTS.md → REQ-integration-view-model-pflicht, REQ-integration-sidebar, REQ-integration-smoke-tests
  • designer-briefs/P01-fundament-walking-skeleton.md (Walking-Skeleton + App-Shell-Andock)
  • DESIGNER-FIRST-PLAYBOOK.md → §1 Fundamente (Hot-Swap-Prinzip)
  • docs/ARCHITECTURE-DECISIONS.md → AD-17 (PWA-only)

Dev-Nachzug (nach Davids D-D0a/D-D0b-Delta)

  • Subframe-Adapter/Skeleton an Davids App-Shell- + Archetypen-Output angepasst
  • REQUIREMENTS/ROADMAP nachgezogen
  • Plane-Ticket R-P1c aktualisiert (Owner→Raffael bestätigt)

Umsetzungsstand (Claude, 2026-06-17 — noch nicht final abgenommen)

Branch p1-fundament-rp1abc. Den finalen DoD-Abhaken/Done macht Raffael. Designer-first: die finale Optik folgt Davids D-D0a/D-D0b-Delta (Dev-Nachzug oben); R-P1c liefert das Muster (dünne Ende-zu-Ende-Scheibe), nicht das polierte UI.

Ausgangslage: Hot-Swap-Maschine + ui-mock + Visual-Regression-Gate lagen schon vor und sind grün (pnpm run test:hot-swap → „UI hot-swap drill verified", pnpm run verify:ui-visual → 7 passed). VM-/Action-Callback-/Subframe-Adapter-Typen existieren in @hivegrid/view-models + defineAdapter in @hivegrid/ui-app.

Neu gebaut:

  • VM-Konvention exemplarisch (M013): packages/view-models/src/walking-skeleton/walking-skeleton.vm.ts — reine buildWalkingSkeletonVM(), *.vm.ts, VMState, nur i18n-Keys (kein Klartext). + Tests.
  • Konnektor→Sidebar-3-Zustände: apps/web/app/utils/connector/connectorNavState.ts (resolveConnectorNavState → active/locked/hidden) + Tests für alle drei.
  • Walking-Skeleton-Route: apps/web/app/routes/app.$tenant/walking-skeleton.tsx — Loader baut das VM im Loader und wendet das Konnektor-Pflicht-Gate tenantHasModule() (aus R-P1b) exemplarisch an; Component rendert minimal je Zustand (data-ui-id="ui.walkingSkeleton.page", data-connector-state). + Loader-/Component-Tests.
  • Sidebar-Registrierung: AppSidebar.tsx-Eintrag, gegated über resolveConnectorNavState auf Basis der productAccess-Entscheidung; appData.ts wertet das Demo-Modul walking-skeleton mit aus. Für reale Tenants blueprint-disabled → Zustand hidden (kein Clutter), bis das Modul bewusst einem Blueprint zugeordnet wird.
  • PWA-Manifest: apps/web/public/manifest.webmanifest von „HiveGrid Boilerplate" auf HiveGrid umgebrandet (lang: de), installierbar (PWA-only v1, AD-17).
  • Smoke gegen ui-mock: apps/web/app/modules/walkingSkeleton/walkingSkeleton.hot-swap.test.ts (VM als ui-mock-Drop-in via generateMockArtifacts — beweist Hot-Swap-Tauglichkeit). + e2e-Smoke tests/e2e/walking-skeleton.spec.ts (Login→Route→Seite, skippt ohne E2E-Creds; läuft im CI/Staging-e2e-Job, lokal kein Playwright-Server).
  • i18n: walkingSkeleton.*-Keys in de + en (Parität, verify:i18n grün).

Nebenbei gefixt: Ein damaliger Test-Isolations-Flake in den inzwischen entfernten Boilerplate-Feature-Decision-Verifiern wurde behoben; die volle Suite lief danach stabil grün.

Proof: view-models + web Typecheck grün · test:hot-swap + verify:ui-visual grün · verify:i18n grün · ESLint grün · neue Tests grün · volle Suite 3698 grün (Flake behoben, s.o.) · Commit c2a31a2b nach main, auf Staging deployt (Deploy-Run, revision live + healthcheck 200). Finaler P1-Stand inkl. Spalten-Drop = fe428e1b (Deploy-Details siehe R-P1a.md §Staging-Deploy).

Abschluss-Notiz (2026-07-09, Raffael)

DoD-Stand: 5/5 DoD = 100 % done.

Proof: Hot-Swap, UI-Mock, Visual-Gate, PWA-Manifest und Walking-Skeleton sind laut Umsetzungsnotiz gebaut, getestet und auf Staging verifiziert. Dieses Ticket ist screen-frei; spätere Subframe-Verfeinerung ist kein Done-Blocker.

Plane: Ticket HIVEGRID-32 auf Done verschoben.

Bugfix-Notiz (2026-07-22, lokales Quick-Fix-Paket)

Die Browser-Favicons hatten zwar einen RGBA-Kanal, waren aber vollständig opak und enthielten einen weißen Hintergrund. Die Größen 16, 32 und 96 Pixel sowie favicon.ico wurden deshalb direkt aus dem kanonischen HiveGrid-SVG neu mit echtem transparentem Hintergrund gerendert. Core und Kundenportal referenzieren die transparenten Browser-Favicons mit einem neuen Cache-Key; der konfigurierbare brandingFavicon-Override bleibt unverändert erhalten. Android-/Apple-/PWA-Installationsicons wurden bewusst nicht verändert.

Proof: Eckpixel aller drei PNGs haben Alpha 0; favicon.ico enthält drei RGBA-PNG-Einträge. Fokussierte Tests 17/17 grün (public-icons, Portal-Boundary, Portal-Asset-Staging, Web-Build-Surfaces), ESLint grün, @hivegrid/web-Typecheck grün.

%-Done-Stand: R-P1c bleibt bei 5/5 DoD = 100 % done; dieser lokale Regression-Fix ändert den abgenommenen Ticket-Scope nicht.

Bugfix-Notiz (2026-07-22, lokales Quick-Fix-Paket 2: Seitentitel)

Core, Admin, öffentliche Routen und Kundenportal verwenden jetzt denselben zentralen Document-Title- Vertrag. Vorhandene Route-Metadaten werden auf genau einen Titel normalisiert; Routen ohne eigenen meta-Export verwenden ihren bereits vorhandenen Loader-Titel statt still den Eltern-Titel zu übernehmen. Bekannte alte bzw. konfigurierte Produkt-Suffixe werden durch HiveGrid ersetzt, ohne Pipes innerhalb dynamischer Seiten- oder Entitätsnamen abzuschneiden. Der Portal-Fallback lautet explizit Kundenportal | HiveGrid; titelose Legacy-Routen erben weiterhin den nächstgelegenen sinnvollen Seiten-/Bereichstitel, statt einen Slug als Klartext anzuzeigen.

Proof: fokussierte Title-Unit- und Router-Navigationstests 20/20 grün; vollständige Core-Suite 999 Testdateien grün (7138 Tests, 10 Dateien/55 Tests erwartungsgemäß übersprungen); @hivegrid/web-Typecheck grün; fokussiertes ESLint grün.

%-Done-Stand: R-P1c bleibt bei 5/5 DoD = 100 % done; der zentrale Head-Vertrag ist ein lokaler Branding-Regressionsfix und öffnet das abgenommene Fundament-Ticket nicht erneut.