Files
HiveGrid-Wireframes/hivegrid-cloud/.planning/ticket-docs/R-P1c.md
T

81 lines
7.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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** | geplant |
## 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
- [x] **VM-Konvention** (View-Model im Loader) + **Action-Callback-Contract** + **Subframe-Adapter** stehen
- [x] `packages/ui-mock` + **Visual-Regression-Gate** + Hot-Swap-Drill (grün)
- [x] **Walking-Skeleton-Route** in Sidebar registriert, Konnektor-Gate `tenantHasModule()` exemplarisch angewandt
- [x] **PWA-Manifest** (installierbar; PWA-only v1, AD-17 — kein native/Store)
- [x] 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 · `PHASE-SOURCES.md` → Phase 1, 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/PHASE-SOURCES 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 `@toolctrl/view-models` + `defineAdapter` in `@toolctrl/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 „Toolctrl 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 — Test-Isolations-Flake (Suite verlässlich grün):** Die zusätzlichen Test-Dateien
kippten die Parallelität über eine Schwelle, die einen latenten Race exponierte:
`verify-email-marketing-` und `verify-kb-widgets-workflow-marketing-decision-report.test.mjs`
mutierten die **geteilte** `docs/feature-manifests/plugin-candidates.json` in-place (von Geschwister-
Verifiern gelesen → cross-file Race). Beide auf das bereits bewährte Temp-Fixture-Muster von
`verify-portals-sites-decision-report.test.mjs` umgestellt (Verifier-Root via `process.argv[2]`,
Mutation nur in `node_modules/.tmp`). Der neue isolierte Test deckte zudem auf, dass ein früher
abgebrochener Lauf die echte `plugin-candidates.json` dirty hinterlassen hatte → aus git
wiederhergestellt. Danach 2× grün + Datei bleibt sauber.
**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).