113 lines
6.4 KiB
Markdown
113 lines
6.4 KiB
Markdown
# Interim-UI → David-Handover — Agent-Anleitung
|
||
|
||
**Zweck:** Wenn ein Ticket mit einer **Interim-UI** (Vorschau-Screen aus `~/ui`, AD-28) fertig wird, kann der
|
||
Interim-Screen an Designer David übergeben werden, damit er die finale Subframe-Optik bauen kann. Diese Doc ist
|
||
die Schritt-für-Schritt-Anleitung, wie ein Agent diese Übergabe erzeugt. Basis-Regeln: `INTERIM-UI-PLAYBOOK.md`
|
||
+ `INTERIM-UI-DESIGN-STANDARDS.md`.
|
||
|
||
> **Wann triggern:** Immer wenn im Zuge eines Tickets **mindestens ein** Interim-Screen
|
||
> (`apps/web/app/components/screens/<domain>/<Screen>Page.tsx`) neu entsteht. **Nicht ungefragt bauen** — das
|
||
> ist Arbeit außerhalb des Ticket-Scopes. Der Agent **fragt den User** (Rückfrage), ob zusätzlich die zwei
|
||
> Handover-Artefakte erzeugt werden sollen. Erst nach **explizitem OK** ausführen.
|
||
|
||
## Was erzeugt wird — zwei Artefakte
|
||
|
||
1. **One-Liner Brief-Pointer** — eine Zeile im passenden `.planning/designer-briefs/PXX-*.md` dieses Repos,
|
||
die David von seinem gewohnten Intake-Kanal auf die Handover-Seite verweist. (Lokale Doc-Änderung in
|
||
HiveGrid-Cloud; erreicht David beim nächsten `git pull` seines gebundelten `hivegrid-cloud/`-Checkouts.)
|
||
2. **Handover-Seite** — eine Domänen-Seite in Davids Vault
|
||
`../HiveGrid-Wireframes/Tickets/Interim-Handover/PXX-<Domain>.md` mit je Screen: D-*-Ziel, Archetyp, Route,
|
||
VM-Quelle, benötigte `~/ui`-Elemente, Actions, States, leerer „Davids Delta"-Block. **Plus** eine Zeile im
|
||
`INDEX.md` desselben Ordners.
|
||
|
||
Grundregel (Designer-First): Die Handover-Seite listet nur **Elemente / Daten / Aktionen / States** —
|
||
**NIE Layout**. Anordnung ist Davids freie Hand.
|
||
|
||
## Schritt 0 — Rückfrage an den User
|
||
|
||
Melde: „Für Ticket `<ID>` ist eine Interim-UI (`<N>` Screen(s) in `screens/<domain>/`) entstanden. Soll ich
|
||
zusätzlich (a) den One-Liner-Brief-Pointer in `designer-briefs/<PXX>.md` und (b) die David-Handover-Seite in
|
||
`../HiveGrid-Wireframes/Tickets/Interim-Handover/` erzeugen?" — Erst bei OK weiter.
|
||
|
||
Kläre bei OK zwei Dinge: **welcher Designer-Brief `PXX`** und **welches `D-*`-Ziel-Ticket** die Domäne hat
|
||
(steht im Header-Kommentar der `<Screen>Page.tsx` und in der Ticket-Doc). Bei Unklarheit nachfragen.
|
||
|
||
## Schritt 1 — Screens extrahieren (read-only)
|
||
|
||
Für jede `apps/web/app/components/screens/<domain>/<Screen>Page.tsx` (Test-/reine Helfer-Dateien wie
|
||
`DateField` überspringen) diese Felder rein aus dem Code ziehen — **nichts raten**:
|
||
|
||
| Feld | Quelle im Code |
|
||
|---|---|
|
||
| D-*-Ziel + Archetyp (A1–A7) | Header-Kommentar oben in der `<Screen>Page.tsx` (nennt „D-… , archetype A…") |
|
||
| Route(n) | passende Datei unter `apps/web/app/routes/app.$tenant/<domain>.*.tsx` (bzw. `routes/admin/*` für Admin-Host) |
|
||
| Daten (VM) | der aus `@hivegrid/view-models` importierte VM-Typ + Quelle `packages/view-models/src/<domain>/*.vm.ts` |
|
||
| Benötigte UI-Elemente | die `~/ui/components/*`-Imports + `@subframe/core`-Icon-Imports (= das, was David nachbauen muss) |
|
||
| Interaktionen (Actions) | die exportierte `…Actions`-Typ-Shape (Callback-Namen + Argumente); bei server-`<form>`-Screens die `intent`-Werte |
|
||
| States | Empty / Loading / Permission-Denied(404) — im JSX belegt (EmptyState, `status!=="ready"`, Guard/404) |
|
||
|
||
Bei vielen Screens: pro Domäne **einen read-only Subagenten** parallel laufen lassen, der die Datensätze im
|
||
unten stehenden Format zurückgibt. Keine Datei editieren, nur lesen + Markdown zurückliefern.
|
||
|
||
## Schritt 2 — Handover-Seite schreiben (in Davids Vault)
|
||
|
||
Lege bei Bedarf `../HiveGrid-Wireframes/Tickets/Interim-Handover/` an. Schreibe `PXX-<Domain>.md` mit Kopf-Notiz
|
||
+ je Screen einem `###`-Record nach dieser Vorlage:
|
||
|
||
```md
|
||
# PXX · <Domäne> (<Bau-Ticket> → <D-*-Ziel>)
|
||
|
||
> Interim-UI-Referenz (AD-28). Lauffähige `~/ui`-Vorschau-Screens (VM als Prop) im gebundelten
|
||
> `03 Quellen und Referenzen/hivegrid-cloud/`-Checkout. **Layout = Davids freie Hand.**
|
||
|
||
### <ScreenName> · <D-*-Screen-Titel + Archetyp>
|
||
- **Interim-Screen:** `apps/web/app/components/screens/<domain>/<Screen>Page.tsx`
|
||
- **Route(n):** `<url>` (`routes/app.$tenant/<file>.tsx`)
|
||
- **Daten (VM):** `<VMTypeName>` — `packages/view-models/src/<domain>/<file>.vm.ts`
|
||
- **Benötigte UI-Elemente (KEIN Layout):** <~/ui-Komponenten> · Icons: <Icons>
|
||
- **Interaktionen (Actions):** <callbackName(args), …>
|
||
- **States:** <Empty / Loading / Permission-Denied(404) — was zutrifft>
|
||
- **Davids Delta (offen):**
|
||
- [ ] Überschriebene/geänderte Spec-Punkte:
|
||
- [ ] Neue UI/UX-Entscheidungen:
|
||
- [ ] Subframe-Screen-Link(s):
|
||
- [ ] Offene Fragen an Dev:
|
||
```
|
||
|
||
Danach im `INDEX.md` desselben Ordners je Screen eine Zeile ergänzen (anlegen, falls INDEX noch fehlt — mit
|
||
Intro „Was ist das?" + Domänen-Übersichtstabelle + Screen-Index):
|
||
|
||
```md
|
||
| <ScreenName> | <D-*> | <Ax> | <Route> | offen |
|
||
```
|
||
|
||
Ist die Domäne bei David bereits fertig (`D-*` liegt als `Tickets/Fertige Tickets/D-*.md` vor), Status-Spalte
|
||
= `David fertig` und Kopf-Notiz „dient dem Konsistenz-Abgleich, kein neuer Design-Request".
|
||
|
||
## Schritt 3 — One-Liner Brief-Pointer setzen (in diesem Repo)
|
||
|
||
Im passenden `.planning/designer-briefs/PXX-*.md` **direkt unter die `**Subframe:**`-Zeile** des Kopfblocks
|
||
diese eine Zeile splicen (chirurgisch, keine JSON-/Struktur-Umbauten):
|
||
|
||
```md
|
||
🖥️ **Interim-UI gebaut (AD-28):** lauffähige Screen-Referenz + genutzte Elemente/VM/Actions in `../HiveGrid-Wireframes/Tickets/Interim-Handover/PXX-<Domain>.md`. Layout bleibt frei.
|
||
```
|
||
|
||
## Schritt 4 — Ausliefern
|
||
|
||
- **Handover-Seite(n) + INDEX** liegen in **Davids Vault** (eigenes Repo). Auf einem **eigenen Branch**
|
||
committen (z.B. `interim-ui-handover`), **nicht auf `main`**. Der Push/PR gehört dem User — Push nur mit
|
||
expliziter Freigabe; im Zweifel Branch + Commit lokal lassen und dem User den Push-Befehl geben:
|
||
`git -C ../HiveGrid-Wireframes push -u origin <branch>`.
|
||
- **Brief-Pointer** ist eine Doc-Änderung in **diesem** Repo (HiveGrid-Cloud) — läuft über den normalen
|
||
Ticket-/Commit-Flow dieses Repos, **nicht** in den gebundelten `hivegrid-cloud/`-Checkout des Vaults schreiben
|
||
(der ist read-only / nur-zum-Pullen).
|
||
|
||
## Verifikation
|
||
|
||
- Jede `<Screen>Page.tsx` der Domäne taucht genau einmal in Handover-Seite **und** INDEX auf
|
||
(Gegencheck: `ls apps/web/app/components/screens/<domain>/*Page.tsx`).
|
||
- Jedes `D-*`-Ziel + Archetyp stammt aus dem Header-Kommentar (nicht geraten).
|
||
- Kein Layout in der Handover-Seite (nur Elemente/Daten/Actions/States).
|
||
- Brief-Pointer greppbar: `grep -rl "Interim-Handover" .planning/designer-briefs/`.
|