Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,80 @@
# 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).