Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/INTERIM-UI-PLAYBOOK.md
T

317 lines
19 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.
# Interim-UI-Playbook — Vorschau-Screens aus `~/ui` vor Davids Delta
**Stand:** 2026-07-05 · **Verbindliche Grundlage:** `docs/ARCHITECTURE-DECISIONS.md` **AD-28**
**Verwandt:** `.planning/INTERIM-UI-DESIGN-STANDARDS.md` (Davids Layout-/Komponenten-/State-Werte) ·
`DESIGNER-FIRST-PLAYBOOK.md` · `docs/INTEGRATION-CONTRACTS.md` · `ticket-docs/README.md`
## Warum dieses Playbook
Viele Dev-Tickets (R-P8/9/11/12, R-P2, AK-P3/4/14/16/17/19/20/21, v2: VR-P22b/VR-MCP) sind
serverseitig fertig, bleiben aber **On Hold**, weil die finale Optik an „Davids Delta" im
jeweiligen `D-*`-Screen-Ticket hängt — und diese Screens dauern noch. Die Component-Basis liegt
aber **schon im Repo**: `apps/web/app/ui/` (Alias `~/ui/*`) enthält 79 gesyncte Subframe-Components
+ die Layouts `DefaultPageLayout`/`DrawerLayout`/`DialogLayout` (gepflegt über `.subframe/sync.json`).
Statt auf David zu warten, baut der Dev **jetzt** aus denselben `~/ui`-Components eine **Interim-UI**
(Vorschau-Screen), stellt das Ticket damit fertig, testet es und schiebt es auf **Done**. Der spätere
Tausch gegen Davids finalen Subframe-Screen ist ein **getrackter Nachzug** hinter der stabilen
VM/Loader-Grenze — ein Component-Swap, kein Rewrite (Hot-Swap-Gedanke, M015/M017).
> **Begriff:** „Interim-UI" / „Interim-Screen". Nicht verwechseln mit `packages/ui-mock` — das ist
> der M017-Hot-Swap-Drop-in (bewusst hässliches Alt-Markup zum Beweis der Austauschbarkeit), etwas
> völlig anderes.
## Die goldene Regel (macht „später wenig Arbeit" real)
Ein Interim-Screen **muss**:
1. aus `~/ui`-Components + einem `~/ui/layouts/*` komponiert sein — **nie** handgeschriebenes
Tailwind-Markup (Negativ-Beispiel: `apps/web/app/routes/app.$tenant/tasks._index.tsx`, das eine
handgeschriebene `<table>` rendert und „Subframe polish follows David's D-P4 delta" trägt);
2. seine Daten aus dem bestehenden **View-Model** (`packages/view-models/**`) beziehen, das als Prop
hereingereicht wird;
3. alle statischen Texte über i18n-Keys (`t()`) auflösen.
Nur so ist Davids Delta hinterher hauptsächlich Anordnung/Feinschliff, und der Swap bleibt billig.
Wird Interim-UI als handgeschriebenes Tailwind gebaut, ist der Nachzug ein Neubau — das verfehlt den
ganzen Zweck und ist ein PR-Block wie ein Anti-Listen-Verstoß.
**Nach Davids Standards bauen (`~/ui`-Defaults + Design-Werte):** Damit die Interim-UI wirklich nah an
Davids kommende Pages kommt, folgt der Screen denselben Layout-/Komponenten-/State-Standards, nach denen
David selbst baut — festgehalten (mit exakten Werten: Page-Padding 24, Card 16, Dialog-Größen, Control-Höhen,
State-Regeln, Screen-Naming) in **`.planning/INTERIM-UI-DESIGN-STANDARDS.md`** (In-Repo-Spiegel von Davids
Vault `../HiveGrid-Wireframes/`). Kernpunkt: **`~/ui`-Component-Defaults sind führend** — Höhen/Paddings/
Dialog-Struktur nicht mit Tailwind nachbauen, wenn die Komponente/Variante sie schon abbildet. Modale immer
als echter `Dialog` (`DialogLayout → Dialog → Dialog.Content`), nie als Card-Fake. Diese Doc **vor dem
Screen-Bau lesen**.
## Wo der Interim-Screen lebt
```
apps/web/app/components/screens/<domain>/<Screen>Page.tsx
└─ export function <Screen>Page({ vm, actions }: { vm: <Screen>VM; actions: <Screen>Actions }) { … }
komponiert ~/ui-Components als app-chrome-freien Content, rendert vm.data, ruft actions.onX
```
Die Route bleibt beim etablierten Muster und rendert nur:
```tsx
// apps/web/app/routes/app.$tenant/<modul>._index.tsx
export default function XRoute() {
const { vm } = useLoaderData<LoaderData>();
return <XPage vm={vm} actions={{ onEdit, onArchive }} />;
}
```
Das ist genau das AGENTS.md-Zielmuster `<XPage vm={} actions={} />` — die Interim-UI füllt die heute
fehlende „mittlere Komposition" zwischen VM und `~/ui`-Primitives.
### App-Shell-Grenze: keine rekursive Subframe-Sidebar
Die HiveGrid-App-Routes laufen bereits innerhalb der echten App-Shell mit Sidebar, Tenant-Layout und
Navigation. Deshalb dürfen Screen-Komponenten unter `apps/web/app/components/screens/**` **keine**
generierten Subframe-Page-Layouts rendern, die selbst App-Chrome enthalten, insbesondere nicht
`~/ui/layouts/DefaultPageLayout`. Dieses Layout bringt eine eigene Beispiel-Sidebar inklusive Logo/Nav mit
und erzeugt sonst eine doppelte Sidebar in der App. Erlaubt sind app-chrome-freie Content-Shells aus `div`/
`section` plus `~/ui`-Komponenten. `DialogLayout` und `DrawerLayout` bleiben für echte Modale/Drawer erlaubt,
wenn sie nicht zusätzlich App-Navigation rendern.
### Scroll-Verhalten: Dokumentfluss statt Subframe-Inner-Scroll
Subframe-Page-Exporte kommen mit einem eigenen Scroll-Gerüst: Screen-Root
`h-full min-h-[0px] … overflow-hidden` plus Inhaltsbereich `grow shrink-0 basis-0 … overflow-y-auto`.
Das funktioniert nur, wenn der Screen eine definite Höhe vom Parent erbt. Die `SubframeAppShell` rendert
Screens aber in ein block-level `<main class="flex-1 overflow-auto">` — dort kollabiert der
`basis-0`-Bereich auf **0px** und der komplette Inhalt ist unsichtbar (im DOM vorhanden, Höhe 0; so
geschehen bei WF-P16 S00/S02 und den Automations-Übersichten, 2026-07-10). Beim Integrieren deshalb
**beide Klassen-Sets entfernen** und den Screen im normalen Dokumentfluss rendern — das Scrollen
übernimmt die `<main>` der Shell (wie bei allen anderen App-Screens). Der Guard-Test
`apps/web/app/components/screens/subframe-layout-boundary.test.ts` schlägt bei dem Muster statisch fehl.
### Lokales UI-Kit ≠ Cloud-Export: bekannte Prop-Abweichungen
Der Subframe-Cloud-Export nutzt teils andere Prop-APIs als das lokale Kit unter `apps/web/app/ui`.
Bei Unsicherheit die Komponente lesen. Real getroffen (Stand 2026-07-13):
- `SearchInput`: flache Props (`value`/`onChange`/`placeholder` direkt), KEIN `<SearchInput.Input>`-Child.
- `Table.Cell`: kennt nur `align-left`/`align-center`; rechtsbündig = Default + `justify-end`-Div.
- `BadgeFeedback`: Farb-Prop heißt `farbe`.
- `BadgeShortcut`: Props heißen `icon`/`iconRight` (Default-Icon ⌘), NICHT `iconLeft1`/`iconLeft2` aus dem Export; ⇧-Kombos als Text-Children (z. B. `⇧Z`).
- `HelpCircle`: hat KEIN `tooltipText` — Tooltip via `SubframeCore.Tooltip.Root/Trigger/Portal/Content asChild` + `~/ui`-`Tooltip` als Content (Muster: `select-tenant.component.tsx`).
- Radix `SubframeCore.ContextMenu.Content`: akzeptiert KEIN `side`/`align` (Kontextmenüs positionieren am Pointer) — die Props aus dem Export entfernen, nur `asChild` behalten.
### Component-Sync: nie blind `sync --all` übernehmen (real getroffen 2026-07-18)
`pnpm subframe:sync` (`@subframe/cli sync --all`) schreibt den **kompletten** Cloud-Stand nach
`apps/web/app/ui` — inklusive **Löschungen**: lokale Komponenten ohne Cloud-Pendant
(`ConfirmDialog`, `ResultDialog`, `layers.ts`, …) und sogar colocated **Testdateien**
(`Dialog.layering.test.tsx`) flogen raus; parallel kamen umbenannte Duplikate (`DialogFullscreen`
neben `FullscreenDialog`) rein. Vorgehen:
1. Sync laufen lassen, dann `git status` sichten und **nur die für das Ticket nötigen Komponenten
behalten** (Rest per `git stash`/`checkout` zurück — der volle Stand bleibt im Stash als Referenz).
2. Synchronisierte Komponenten auf **Breaking-API** prüfen (2026-07-18: `KanbanCard` wechselte von
`name`/`price`/`topRow` auf Slot-Props `tagsSlot`/`titleSlot`/`valueSlot`/`footer*Slot`) und ALLE
Konsumenten im selben PR migrieren — auch fremde Module (LeadBoard), Abhängige müssen grün bleiben.
3. Wrapper wie `SortableKanbanBoard` forwarden neue Props **nicht** automatisch — Interface + Forwarding
nachziehen, sonst greifen neue Defaults still (2026-07-18: `showSum=false` zeigte überall
„Summe gesperrt" statt der Spaltensumme).
### Layer-Regeln bleiben unangetastet
Die drei Anti-Patterns (AGENTS.md) gelten weiter:
- kein `@prisma/client`/`~/db` in `packages/ui-app/**`;
- kein `packages/ui-subframe`-Direktimport in `app/routes/**`;
- kein `useLoaderData` in `packages/ui-app/**` — VM wird als Prop injiziert.
`~/ui`-Direktimport in `apps/web/app/components/**` bzw. `app/routes/**` ist **erlaubt** — er verletzt
kein Anti-Pattern (die verbieten nur `packages/ui-subframe`-Direktimporte). Wer den formalen
ui-app/ui-subframe-Adapterpfad nutzen will, kann das; für Interim-Screens ist die direkte
`~/ui`-Komposition der pragmatische, schnellere Weg.
## Done-Semantik (AD-28)
Ein UI-lastiges Ticket ist **Done-fähig**, sobald:
- **Dev-DoD 100 %** (alle nicht-Optik-Punkte grün) **und**
- **Interim-Screen** aus `~/ui` steht (goldene Regel erfüllt) **und**
- **Tests grün** (siehe DoD-Mapping unten).
Die **finale Subframe-Optik** ist dann **kein Done-Blocker** mehr, sondern ein **getrackter Nachzug**.
`/planning` bleibt die **Single Source of Truth** — der Nachzug wird zuerst in der Ticket-Doc markiert,
Plane spiegelt nur:
- **`.planning/ticket-docs/<ID>.md` (führend):** der standardisierte **`🎨 design-nachzug`-Tag** direkt
unter der Header-Tabelle (Format unten) **plus** der ausführliche Interim-UI-Vermerk in der Sektion
**„Dev-Nachzug (nach Davids `D-*`-Delta)"** (Muster unten),
- **Plane-Label `design-nachzug` (spiegelt die Doc):** nur für Board-Queries; wird aus dem Doc-Tag
abgeleitet, nie umgekehrt,
- die Interim-Visual-Baseline ist als „interim" markiert und wird beim Nachzug neu gezogen.
### Header-Tag in der Ticket-Doc (Single Source of Truth)
Direkt unter die Header-Tabelle der Ticket-Doc, damit `/planning` per `grep` autoritativ auswertbar ist
(`grep -rl "design-nachzug: offen" .planning/ticket-docs/`):
```md
**🎨 design-nachzug: offen** (seit YYYY-MM-DD) — Interim-UI aus `~/ui` steht; finale Subframe-Optik aus `D-<XXX>` ausstehend.
```
Beim David-Nachzug wird der Tag auf erledigt gesetzt (Historie bleibt in der Doc):
```md
**🎨 design-nachzug: erledigt** (YYYY-MM-DD) — finale `D-<XXX>`-Optik integriert, Visual-Baseline neu gezogen.
```
Done setzen weiterhin nur **mit expliziter Freigabe** und nach dem Abschluss-Audit (`plan-ticket` §8).
## DoD-Mapping — was Interim-UI erfüllt vs. was Nachzug bleibt
| DoD | Punkt | Mit Interim-UI |
|---|---|---|
| B 6–10 | Sidebar · Permission-Gate · Route · Breadcrumbs · i18n | **jetzt erfüllbar** |
| B 11/12 | Mobile-Tab-Bar · Customer-Portal | nur „falls relevant"; bei PWA-only (AD-17) i. d. R. Nachzug/deferred |
| D 18 | VM-Unit-Test | **jetzt erfüllbar** (reine Funktion) |
| D 19 | Smoke-Test `e2e/smoke/<modul>.spec.ts` | **jetzt erfüllbar** gegen Interim-Screen |
| D 20 | Hot-Swap-Drill (`packages/ui-mock`) | **jetzt erfüllbar** |
| D 21 | Visual-Regression (M016) | gegen **Interim-Baseline** erfüllbar; **Re-Baseline-Pflicht** beim David-Nachzug |
| — | finale Subframe-Optik | **Nachzug** (Label `design-nachzug`) |
## Refactor-Ablauf, wenn Davids Delta landet
**Davids Delta erscheint als:** neue/aktualisierte Datei in `../HiveGrid-Wireframes/Tickets/Fertige Tickets/D-*.md`
+ Paket-Status im `Screen Paket Tracker` auf `Fertig` + `design/`-Subframe-Links je Screen (Team `f023064a5ca0`).
1. VM/Loader/Route **unverändert** lassen.
2. Internals von `<XPage>` gegen Davids Subframe-Screen tauschen (gleiche `~/ui`-Components → meist
Umstellen/Neuanordnen, kein neuer Datenpfad).
3. Visual-Baseline neu ziehen (Interim-Snapshot ersetzen), Smoke/Hot-Swap erneut grün.
4. Plane-Label `design-nachzug` entfernen; Umsetzungs-Notiz + „Dev-Nachzug"-Sektion der Ticket-Doc
mit Datum + Proof ergänzen.
## Pro-Ticket-Checkliste (Interim-UI)
- [ ] Interim-`<XPage>` in `apps/web/app/components/screens/<domain>/` aus `~/ui` + Layout, VM als Prop.
- [ ] Route rendert `<XPage vm={} actions={} />`; kein handgeschriebenes Tailwind.
- [ ] Keine rekursive App-Shell: Screen-Komponenten importieren nicht `~/ui/layouts/DefaultPageLayout` und rendern keine zusätzliche Sidebar/Header-Navigation.
- [ ] Kein Subframe-Inner-Scroll: `h-full`/`overflow-hidden`-Root und `basis-0`/`overflow-y-auto`-Inhaltsbereich aus dem Page-Export entfernt — Screen läuft im Dokumentfluss, die Shell-`<main>` scrollt (siehe §„Scroll-Verhalten").
- [ ] **Davids Design-Standards befolgt** (`.planning/INTERIM-UI-DESIGN-STANDARDS.md`): Spacing/Padding/
Dialog-Struktur/Control-Höhen/States aus `~/ui`-Defaults; Screen-IDs/Naming an Davids Tracker angelehnt.
- [ ] Reachability B 6–10 verdrahtet (Sidebar/Permission/Route/Breadcrumb/i18n).
- [ ] Tests: VM-Unit (18) · Smoke (19) · Hot-Swap (20) · Visual-Regression gegen Interim-Baseline (21).
- [ ] Ticket-Doc (führend): `🎨 design-nachzug: offen`-Tag unter der Header-Tabelle **und** Interim-UI-Vermerk in der „Dev-Nachzug"-Sektion (Muster unten).
- [ ] Plane-Label `design-nachzug` gesetzt (spiegelt den Doc-Tag).
- [ ] Done nur bei Dev-DoD 100 % + Interim-UI + Tests grün + Freigabe.
### Muster: Interim-UI-Vermerk in „Dev-Nachzug (nach Davids `D-*`-Delta)"
```md
**Interim-UI (Vorschau, Stand YYYY-MM-DD):** Screen aus `~/ui` gebaut —
`apps/web/app/components/screens/<domain>/<Screen>Page.tsx`. Proof: Smoke `e2e/smoke/<modul>.spec.ts`,
Hot-Swap-Drill grün, Interim-Visual-Baseline `<pfad>` (als interim markiert).
Refactor-Nachzug offen: finale Subframe-Optik aus `D-<XXX>` (Plane-Label `design-nachzug`).
```
## Nachzug-Tracking
- **`/planning` ist führend:** Der `🎨 design-nachzug`-Tag in `.planning/ticket-docs/<ID>.md` ist die
autoritative Quelle. Offene Nachzüge findet man per `grep -rl "design-nachzug: offen" .planning/ticket-docs/` —
unabhängig von Plane und ohne API-Zugang.
- **Plane spiegelt:** Das Plane-Label **`design-nachzug`** (anlegbar über `.planning/plane-sync/scrub_plane.py`
oder manuell via `POST /labels/`) wird aus dem Doc-Tag abgeleitet und dient nur der Board-Sicht — nie
umgekehrt. Divergiert Plane vom Doc, gewinnt das Doc.
- Es gibt **kein** Skript, das Plane-Kommentare postet. Kommentar/Status weiter manuell via API
(`POST /issues/{iid}/comments/`, Identität vorab `GET users/me`); Done nur mit Freigabe.
## Footgun: FK-Constraints auf Tabellen unter `FORCE ROW LEVEL SECURITY`
**Symptom.** Eine Migration, die eine Foreign Key Constraint anlegt, bricht ab mit
`ERROR: query would be affected by row-level security policy for table "<X>"` —
obwohl der Migrator der Tabellen-Owner ist.
**Ursache.** Seit dem App-weiten RLS-Cutover tragen die Tabellen `FORCE ROW LEVEL
SECURITY`, und `FORCE` gilt **auch für den Owner**. Postgres validiert eine neue
FK-Constraint mit einem internen `SELECT` über die betroffenen Tabellen, und
genau dieses `SELECT` wird von der Policy abgelehnt. Es trifft **beide** Seiten:
die Tabelle, die die Constraint bekommt, **und** die referenzierte Tabelle.
**Fix.** `FORCE` für die Dauer der Constraint-Erzeugung abschalten und sofort
wieder setzen. Die Policy selbst bleibt die ganze Zeit **aktiviert**, und im
Fenster steht kein DML — es ist also kein Sicherheitsloch:
```sql
ALTER TABLE "Pipeline" NO FORCE ROW LEVEL SECURITY;
ALTER TABLE "Pipeline" ADD CONSTRAINT "…_fkey" FOREIGN KEY (…) REFERENCES "Pipeline"("id") …;
ALTER TABLE "PipelineFieldGroup" ADD CONSTRAINT "…_fkey" FOREIGN KEY (…) REFERENCES "Pipeline"("id") …;
ALTER TABLE "Pipeline" FORCE ROW LEVEL SECURITY;
```
**Merke.** Mehrere FKs auf dieselbe Zieltabelle in **ein** Fenster packen, statt
`FORCE` mehrfach zu togglen. Neu angelegte Tabellen sind nicht betroffen,
solange ihre Policies erst am Ende der Migration gesetzt werden — das ist ein
weiterer Grund, den RLS-Block ans Ende des Migrationsfiles zu stellen.
**Gefunden:** 2026-07-28, WF-P8-Baseline (`20260728120000_wf_p8_subframe_baseline`).
Der Fehler erscheint erst bei `verify:migrations-parity` bzw. beim Replay gegen
eine leere DB, **nicht** beim lokalen `prisma db push` — der Feature-Branch-Pfad
verschleiert ihn also.
## Footgun: eine neue Relation kann die Policy-Form einer bestehenden Tabelle kippen
**Symptom.** `verify:rls-live` meldet gegen die frische Migrationskette
`rls_expected_policy_mismatch` **und** `rls_unexpected_policy`, obwohl
`verify:tenant-policy-contract --check` grün ist und die Migration für jede neue
Tabelle brav eine Policy anlegt.
**Ursache.** Der Generator entscheidet die **Form** der Policies aus dem Modell:
eine Tabelle mit direktem `tenantId` bekommt **eine** `FOR ALL`-Policy
(`hg_<T>_all`), eine Tabelle mit abgeleiteter Ownership bekommt **vier**
Per-Command-Policies (`_select`/`_insert`/`_update`/`_delete`). Fügt man einer
**bestehenden** Tabelle eine Relation hinzu, kann sie dadurch zum
Derived-Ownership-Modell werden und ihre Policy-Form wechseln. Bei WF-P8 hat
genau das die Selbstrelation `Pipeline.nachfolgePipelineId` ausgelöst:
`hg_Pipeline_all` → vier Policies.
**Fix.** Die Policy-DDL **nie von Hand schreiben**, sondern wörtlich aus
`prisma/rls/tenant-policy-contract-isolation.sql` in die Migration kopieren —
inklusive der Tabellen, die man gar nicht angefasst zu haben glaubt. Die alte
Policy muss dabei explizit gedroppt werden:
```sql
DROP POLICY IF EXISTS "hg_Pipeline_all" ON "Pipeline";
-- danach die vier generierten Per-Command-Policies
```
**Merke.** Postgres verknüpft permissive Policies mit **ODER**. Eine
stehengebliebene alte Policy hebt die neue also nicht auf, sondern hält den
schwächeren Ausdruck daneben am Leben — ein stiller Sicherheitsverlust, den
kein Test bemerkt, der nur „Zeile sichtbar?" prüft. Ein `git diff` gegen
`packages/db/src/rls-runtime-contract.generated.ts` zeigt nach jeder
Schema-Änderung sofort, welche Tabellen ihre Policy-Form gewechselt haben.
**Gefunden:** 2026-07-28, WF-P8-Baseline. Sichtbar nur in `verify:rls-live`,
`Database Checks` und `Docker Smoke` — lokal auf `RLS_RUNTIME_MODE=off` nicht.
## Footgun: `~/ui`-Felder in einer umbrechenden Flex-Zeile
**Symptom.** Mehrere Eingabefelder nebeneinander rendern kaputt: jedes Feld
steht auf einer eigenen, sehr hohen Zeile, das Label klebt weit über dem Input
und kollidiert mit dem nächsten Feld. Im DOM ist die Reihenfolge korrekt — es
ist rein Layout.
**Ursache.** Die Roots von `~/ui`-`TextInput`/`Select` tragen selbst
`h-full w-full … justify-center`. Als Flex-Kind beansprucht ein solches Feld
damit die **ganze** Zeile (eine `flex-wrap`-Zeile bricht also nach jedem Feld
um) und dehnt sich zusätzlich auf die Zeilenhöhe, wobei `justify-center` den
Input in der Mitte dieser Höhe parkt.
**Fix.** Die Zeile als **Grid** auslegen, dann füllt jedes Feld seine Spur:
```tsx
<div className="grid w-full items-end gap-3 sm:grid-cols-2">
<TextInput className="w-full" … />
<TextInput className="w-full" … />
</div>
```
**Merke.** `className="grow"` hilft **nicht** — es überschreibt das `w-full` des
Feldes nicht. Eine nicht umbrechende `flex`-Zeile ist dagegen unkritisch, weil
die Felder dort schlicht schrumpfen. Guard:
`apps/web/app/components/screens/subframe-layout-boundary.test.ts`.
**Gefunden:** 2026-07-29, WF-P8 „Termin erstellen" (S02-T) und S05
„Neue Feldgruppe". Nur im Browser sichtbar, nicht im Unit-Test.