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

182 lines
9.5 KiB
Markdown

# R-UX0 · Tenant-UX-Overhaul: E-Mail-Marketing, Personal und Passwörter
| | |
|---|---|
| **Typ** | Epic (Planung/Dev) |
| **Owner** | Raffael |
| **Phase** | Querschnitt · Tenant UX |
| **Cycle/Fenster** | noch nicht eingeplant |
| **Status** | geplant |
| **Plane** | [HIVEGRID-199](https://project.tool-ctrl.de/toolctrl/projects/35d0d968-8ab3-40cc-97b8-b81d917dc5df/issues/869b2189-d711-4e4e-8156-c10b25745c72) |
## Zielbild
Drei bestehende Bereiche werden für nichttechnische Handwerksbetriebe auf konkrete Nutzeraufgaben
ausgerichtet:
1. **E-Mail-Marketing:** Versand vorbereiten, Empfänger auswählen, testen, terminieren und auswerten.
2. **Personal:** eigene Aufgaben, Teamaufgaben und Verwaltung klar voneinander trennen.
3. **Passwörter:** als eigenständigen, besonders geschützten Arbeitsbereich vervollständigen.
Das Epic ist ein Produkt- und UX-Nachzug auf vorhandenen Funktionen. Es schreibt die historische
Umsetzung der P14-/P17-Tickets nicht um.
## Child-Tickets
| Ticket | Ergebnis |
|---|---|
| [`R-UX2`](R-UX2.md) | E-Mail-Marketing-Setup, Segmente, Kampagnen, Versand und Reporting |
| [`R-UX3`](R-UX3.md) | Rollenbasierter Personal-Hub für Mitarbeitende, Teamleitungen und Verwaltung |
| [`R-UX4`](R-UX4.md) | Eigenständiger Passwort-Manager mit Einträgen, Freigaben, Audit und Export |
## Gemeinsame Informationsarchitektur
| Bereich | Primärer Einstieg | Alltagssprache |
|---|---|---|
| E-Mail-Marketing | Kampagnenübersicht mit Versandbereitschaft | Empfänger, Test senden, Versand prüfen, Terminieren |
| Personal | Tabs **Für mich / Mein Team / Verwaltung** | Antrag, Genehmigung, Dokument, Mitarbeitende |
| Passwörter | eigener Hauptnavigationseintrag | Passwort-Tresor, Eintrag, Freigabe, Aktivität |
Passwörter sind kein Unterpunkt von Personal. Berechtigungsabhängige Navigation wird vollständig
ausgeblendet; ein Direktaufruf ohne Recht liefert 404 statt 403.
## Gemeinsame UX-Verträge
- Jede Seite beginnt mit genau einer klaren Hauptaufgabe und höchstens einer primären Aktion.
- Suche und Filter stehen an derselben Stelle, bleiben in der URL erhalten und lassen sich gesammelt
zurücksetzen.
- Auswahlfelder zeigen Namen und Kontext, niemals rohe interne IDs.
- Status werden deutsch benannt und erklären zulässige nächste Schritte.
- Destruktive oder schwer umkehrbare Aktionen benötigen einen Klartext-Dialog mit betroffener Entität
und Ergebnis.
- Loading-, Empty-, Fehler-, Offline- und Erfolgszustände nennen den Zustand und die nächste mögliche
Aktion.
- Sensible Werte werden nie in Listen geladen oder angezeigt. Reveal, Copy, Export und
Berechtigungsänderungen werden serverseitig geprüft und auditiert.
- Desktop nutzt Tabellen für dichte Arbeitsvorräte; Mobile nutzt priorisierte Karten mit denselben
Aufgaben, ohne horizontales Tabellen-Scrolling als Hauptbedienung.
## Verbindliche UI-Richtung: `/forms` und Interim-UI
Die vorhandenen Screens unter `/forms` sind die visuelle Referenz des Designers:
- `PageShell`, `PageHeader` und `PageBody` als app-chrome-freie Seitenstruktur;
- Filterzeilen, `SearchInput`, `Select`, Tabellen und mobile Karten;
- Tabs, sichtbarer Autosave-Status, Preview und klare Publish-/Bestätigungsaktionen;
- vollständige Empty-/Fehlerzustände und kompakte mobile Aktionsflächen.
Die Referenz legt die Richtung fest, nicht die Fachlogik. Neue Screens verwenden den bestehenden
App-Shell und importieren kein `DefaultPageLayout`. Sie laufen im normalen Dokumentfluss; kein
Subframe-Inner-Scroll mit `h-full`/`basis-0`.
Bis zu Davids finalem Delta gilt AD-28: Interim-Screens werden aus `~/ui` komponiert, erhalten ihr
View-Model und ihre Action-Callbacks als Props und enthalten keine handgeschriebene Ersatz-UI. Der
`design-nachzug`-Tag und das gleichnamige Plane-Label werden erst gesetzt, wenn eine solche
Interim-UI tatsächlich gebaut und als Baseline verifiziert wurde.
## Gemeinsame Screen-Muster
| Muster | Wiederverwendete Bausteine | Einsatz |
|---|---|---|
| Arbeitsliste | `PageShell`, `PageHeader`, `PageBody`, `SearchInput`, Filter, `Table`, mobile Cards | Kampagnen, Mitarbeitende, Tresore |
| Detail-Arbeitsplatz | Header, Status, Tabs, Activity, kontextuelle Actions | Kampagne, Person, Tresor |
| Geführter Ablauf | Stepper/Wizard, Validierungsübersicht, Save-State, Review | Kampagnenversand |
| Verwaltung | Tabellen/Karten, Comboboxen, Drawer/Dialog, Audit-Hinweis | Rollen, Zielgruppen, Freigaben |
| Bestätigung | `DialogLayout` + `Dialog` mit Klartext-Folge | Versand, Archiv, Export, Freigabeentzug |
Neue UI-Primitives werden nur angelegt, wenn der Bestand unter `~/ui` und die vorhandenen
Screen-Kompositionen die Aufgabe nachweislich nicht abdecken.
## Rollen- und Sicherheitsgrundsätze
| Rolle | E-Mail-Marketing | Personal | Passwörter |
|---|---|---|---|
| Standard-Mitarbeitende | kein Zugriff | eigene Daten/Aufgaben | nur explizit freigegebene Tresore |
| Teamleitung | optional lesend | eigenes Team, definierte Genehmigungen | nur explizit freigegebene Tresore |
| Fachverwaltung | Kampagnen verwalten | Personalverwaltung laut Einzelrechten | Tresorverwaltung nur mit Vault-Recht |
| Tenant-Admin | Domain/Versand-Setup | nicht automatisch HR-Vollzugriff | Metadatenverwaltung, keine automatischen Geheimnisse |
App-Permission, Objektberechtigung und erzwungene PostgreSQL-RLS werden getrennt getestet.
## Umsetzungsreihenfolge
1. Pro Child zuerst P0-Sicherheits-, RLS- und Permission-Lücken schließen.
2. `R-UX4` Passwörter, weil Navigation, Export und Reveal sicherheitskritisch sind.
3. `R-UX3` Personal, inklusive sauberer Trennung von Selbst-, Team- und Verwaltungsaufgaben.
4. `R-UX2` E-Mail-Marketing; dessen P0-Sicherheitskorrekturen werden vorgezogen, sobald das Modul
produktiv aktiviert ist.
Die Child-Tickets dürfen danach parallel umgesetzt werden, sofern ihre eigenen
`blocked-by`-Prüfungen und die Querschnittsverträge grün sind.
## Technische Leitplanken
- Route-Loader und Actions bauen und verbrauchen typisierte View-Models; UI erhält `vm` und `actions`.
- Keine Prisma-/DB-Imports in `packages/ui-app/**`, kein direkter Route-Import aus
`packages/ui-subframe`, kein `useLoaderData` in UI-Paketen.
- Direkte DB-Zugriffe in Web/Worker laufen unter `runWithRlsContext`/`withTenantRLS`; Mock-Tests
ersetzen keinen Forced-RLS-Proof.
- Schreibaktionen nutzen Audit, Activity und Notifications aus den Querschnittsservices.
- Suchbare Entitäten werden über `packages/search/` registriert; keine zweite Suche je Modul.
- Vollständige deutsche i18n-Texte; keine Providerfehler, Statuscodes, UUIDs oder Entwicklerbegriffe
in Nutzer-Flows.
## Empfohlene Umsetzungs-Slices
| Slice | Inhalt | Abschluss-Gate |
|---|---|---|
| E0 | gemeinsame Begriffe, Navigation, Permission- und Statusverträge | alle drei Specs konsistent |
| E1 | P0-Sicherheit je Child | Permission-, Action- und Forced-RLS-Tests grün |
| E2 | View-Models und Server-Actions | pure VM-Tests und klare Action-Ergebnisse |
| E3 | `/forms`-orientierte Interim-UI | Desktop/Mobile, States, Keyboard, keine zweite App-Shell |
| E4 | Integration und Regression | Smoke, Visual, Hot-Swap, i18n, Accessibility |
| E5 | Rollout und Design-Nachzug | Feature-/Rollout-Plan, Interim-Baseline, Nachzug getrackt |
## Epic Definition of Done
- [ ] Alle drei Child-Tickets sind umgesetzt oder bewusst mit dokumentiertem externem Blocker
abgegrenzt.
- [ ] Gemeinsame Navigation, Begriffe, Suche, Status, Auswahlfelder und Bestätigungsdialoge sind
in den drei Bereichen konsistent.
- [ ] Alle P0-Permission-, Objektberechtigungs- und Forced-RLS-Lücken der Child-Tickets sind
geschlossen.
- [ ] Kein Nutzer-Flow zeigt rohe IDs, Providerfehler oder Entwicklerbegriffe.
- [ ] Alle Hauptflows sind auf Desktop und Mobile per Playwright-Smoke und Visual-Regression
abgesichert.
- [ ] View-Model-Unit-, Action-/Permission-, RLS-, Hot-Swap-, Accessibility-, Tastatur- und
i18n-Prüfungen sind grün.
- [ ] Interim-UI und späterer Subframe-Nachzug folgen AD-28; Baselines und `design-nachzug`-Status
sind je Child korrekt dokumentiert.
- [ ] Rollout-, Rollback- und Metrikplan je Child ist dokumentiert; keine historische P14/P17-
Umsetzung wurde umgedeutet.
## Risiken und Abhängigkeiten
- Falsch angenommene Tenant- oder Objektberechtigungen können unter Forced RLS als leere Listen
statt als sichtbarer Fehler erscheinen.
- Die breiten P17-Screens dürfen nicht erneut Personal, Verwaltung und Passwörter in einer
gleichrangigen Navigation vermischen.
- Bei E-Mail-Marketing müssen UI-Checkliste und serverseitiger Versand-Preflight dieselbe Quelle
nutzen, sonst bleibt ein scheinbar freigegebener Versand blockiert oder umgekehrt.
- Design-Tickets `D-P14`, `D-KAMP` und `D-HR` sind Bezugsquellen, aber nach AD-28 keine
Hard-Blocker für eine verifizierte Interim-UI.
## Quellen
- `AGENTS.md`
- `.planning/INTERIM-UI-PLAYBOOK.md`
- `.planning/INTERIM-UI-DESIGN-STANDARDS.md`
- `.planning/ticket-docs/AK-P14a.md`, `AK-P14b.md`, `D-P14.md`, `D-KAMP.md`
- `.planning/ticket-docs/AK-P17a.md`, `AK-P17b.md`, `D-HR.md`
- Referenzimplementierung: `apps/web/app/components/screens/forms/**`,
`apps/web/app/components/screens/shared/PageShell.tsx`,
`apps/web/app/routes/app.$tenant/forms*.tsx`
## Planungsnotiz
**2026-07-25:** Epic-Spec nach Freigabe der gemeinsamen Vorher-/Nachher-Planung angelegt.
**2026-07-25:** `R-UX1` auf Nutzerwunsch aus diesem Stack entfernt. Der bereits auf `main`
gemergte Leads-Stand von Akeshan bleibt kanonisch und wird durch dieses Epic nicht verändert.
**Stand: 0/8 DoD = 0 % done.** Diese Freigabe autorisiert Planung und Plane-Anlage, keine
Implementierung.