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

9.5 KiB

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

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 E-Mail-Marketing-Setup, Segmente, Kampagnen, Versand und Reporting
R-UX3 Rollenbasierter Personal-Hub für Mitarbeitende, Teamleitungen und Verwaltung
R-UX4 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.