Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/R-UX2.md
T
raffaelandClaude Opus 5.5 d09f79b673 chore(infra): Gitea-Host auf git.hg-int.dev umstellen
Gitea läuft seit 2026-11-11 auf hivegrid-control (git.hg-int.dev);
git.tool-ctrl.de wird abgeschaltet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 18:53:32 +01:00

15 KiB

R-UX2 · E-Mail-Marketing: Kampagnen, Segmente und Versand-Flow vereinfachen

Typ Dev (UX-/Produkt-Nachzug)
Owner Raffael
Phase Querschnitt · Tenant UX
Cycle/Fenster noch nicht eingeplant
Status umgesetzt · wartet auf lokale Gesamtabnahme
Plane HIVEGRID-201 · Parent HIVEGRID-199

🎨 design-nachzug: offen · AD-28-Interim-UI ist die verifizierte Abnahmebaseline.

Abhängigkeiten & Parallelität

  • Baut auf: AK-P14a (Sende-Domain/BCC/Tracking) und AK-P14b (Kampagnen, Segmente, A/B, Reporting).
  • Design-Bezug: D-P14 und D-KAMP; finale Deltas sind nach AD-28 keine Hard-Blocker.
  • Hard-Block vor Umsetzung: aktuelle Forced-RLS-Fähigkeit der P14-Queries und Status der typisierten Ablösung des Entity-Builders prüfen. Dieses Ticket darf keinen neuen Entity-Builder-Konsumenten erzeugen.
  • Nicht koppeln: allgemeine Inbox-/OAuth-Flows aus P23 sind kein Bestandteil dieses Tickets.

Zielnutzer und Hauptaufgaben

Nutzer Hauptaufgabe
Marketing/Büro Kampagne vorbereiten, Empfänger bestimmen, testen und versenden
Admin Sende-Domain und Absender betriebsbereit machen
Leitung Freigabestatus und Ergebnisse verstehen
Lesende Rolle Kampagnen und Reports ansehen, ohne Versandaktionen

Belegter Ist-Flow

  1. Navigation ist teilweise nur feature-, nicht permission-gegated.
  2. Einzelne P14-Queries binden Forced-RLS-Kontext nicht verlässlich.
  3. Segment- und Domain-Actions sind nicht durchgehend CSRF-geschützt.
  4. Segmente verlangen technische JSON-Regeln oder rohe IDs.
  5. Die Kampagne ist ein langes Formular ohne klaren Fortschritt, zuverlässigen Test-/Preview-Schritt oder verständliche Terminierung.
  6. Versand kann als Ein-Klick-Aktion erfolgen; UI-Checkliste und serverseitiger Preflight können auseinanderlaufen.
  7. Report und Lifecycle sind unvollständig; Providerfehler können als Entwicklerinformation sichtbar werden.

Freigegebener Ziel-Flow

  1. Bei nicht bereitem Versand führt der Einstieg nach /email-marketing/setup mit Domain-, Absender- und Fußzeilenstatus.
  2. Segmente werden in Alltagssprache aus Kontaktfeldern aufgebaut und zeigen eine sichere Vorschau.
  3. Neue Kampagne ist ein autospeichernder Sechs-Schritt-Flow: Grundlagen → Inhalt → Empfänger → Test → Zeitpunkt → Prüfung.
  4. Testversand erlaubt bis zu fünf klar benannte Adressen und zeigt Ergebnis/Fehler pro Empfänger.
  5. Terminierung trennt Datum, Uhrzeit und Zeitzone.
  6. Der Review-Schritt verwendet exakt dieselbe serverseitige Versandbereitschaft wie der echte Send-Command.
  7. Versand/Scheduling verlangt eine Klartext-Bestätigung mit Empfängerzahl und Zeitpunkt.
  8. Report zeigt Lifecycle, Versandstatus und verständliche Fehler ohne Provider-Interna.

Vorher/Nachher

Vorher Nachher
technische Domain-/Segmentflächen geführtes Setup und visueller Segment-Builder
langes Kampagnenformular sechs klar benannte, autospeichernde Schritte
Freitext-Zeitpunkt Datum, Uhrzeit und Zeitzone
Versand per Ein-Klick servergleiche Checkliste plus Bestätigungsdialog
unvollständiger Status/Report nachvollziehbare Timeline und verständliche Ergebnisse
Providerfehler im UI redigierte Klartextdiagnose mit internem Korrelationsbezug

Screen- und Komponentenmatrix

Screen Kernaufgabe Vorhandene Bausteine
Setup /email-marketing/setup Domain, Absender, Footer, Freigabestatus PageShell, Status-Cards, Checklist, Alert, Buttons
Kampagnenliste suchen, filtern, fortsetzen, Report öffnen /forms-artige Header-/Filterleiste, SearchInput, Select, Table, mobile Cards
Segmentliste/-editor Zielgruppe bauen und Vorschau prüfen Rule-Groups, Comboboxen, Count-Preview, Drawer/Dialog
Kampagnen-Wizard Inhalte und Versand schrittweise vorbereiten Stepper, Tabs, Rich-Text-Editor, Upload, Autosave-State, Preview
Test/Review/Bestätigung Risiken vor Versand sichtbar machen Checklist, Recipient-Chips, Dialog, Zeit-/Zeitzonenfelder
Report Lifecycle und Wirkung verstehen KPI-Cards, Timeline, Tabellen, Charts nur aus vorhandenen Daten

Die /forms-Richtung ist verbindlich für Header, Tabs, sichtbaren Autosave, Preview, Filter-/Suchmuster und mobile Zustände. Kein rekursiver App-Chrome, kein DefaultPageLayout.

Actions und erwartete Ergebnisse

Action Serverprüfung Sichtbares Ergebnis
saveSendingSetup Adminrecht, CSRF, Tenant/RLS, valide Domain/Absender/Footer Statuscheck mit konkretem nächsten Schritt
saveSegment Marketing-Schreibrecht, CSRF, erlaubte Felder/Operatoren benannte Regel und aktualisierte Empfängervorschau
saveDraft Schreibrecht, CSRF, typisierte Payload Autosave „Gespeichert“ oder konkreter Fehler
sendTest Schreibrecht, max. 5 valide Ziele, Domain bereit Ergebnis pro Adresse, kein Kampagnen-Lifecycle-Sprung
scheduleCampaign vollständiger Preflight, Zeitzone, Zukunftszeit Status „Geplant“ mit lokaler Zeit
sendCampaign identischer Preflight, idempotenter Command bestätigter Versandauftrag mit Empfängerzahl
cancelSchedule zulässiger Status und Recht zurück zu Entwurf/abgebrochen gemäß State-Machine

Rollen und Berechtigungen

Fähigkeit Lesend Marketing Admin
Liste/Report sehen ja, mit Read-Recht ja ja
Entwurf/Segment bearbeiten nein ja ja
Test senden nein ja ja
final versenden/terminieren nein eigenes Versandrecht ja
Domain/Absender/Footer verwalten nein nein ja

Sidebar, Route, Loader und Action prüfen Feature und Permission. Ein Tenant-Admin erhält Versandzugriff nur über den definierten Permission-Bundle, nicht durch eine UI-Annahme.

Mobile-Verhalten

  • Kampagnenliste als Karten mit Status, Zielgruppe, Zeitpunkt und einer Hauptaktion.
  • Wizard zeigt einen Schritt pro Screen; Fortschritt und Autosave bleiben sichtbar.
  • Rich-Text-Bearbeitung, Preview und Testempfänger funktionieren ohne horizontalen Overflow.
  • Filter und Segmentregeln verwenden Drawer/Accordion statt breiter Desktop-Zeilen.
  • Versandbestätigung bleibt vollständig lesbar und nennt Empfängerzahl, Zeitpunkt und Absender.

Loading-, Empty-, Fehler- und Erfolgszustände

  • Setup-Empty: Domain oder Absender fehlt, direkte Konfigurationsaktion.
  • Kampagnen-Empty: „Noch keine Kampagne“ plus „Kampagne erstellen“.
  • Segment-Preview: zählt/lädt separat und meldet veraltete Vorschau.
  • Autosave: Speichern, Gespeichert, Ungespeichert, Fehler mit Wiederholen.
  • Preflight-Fehler: gruppiert nach Setup, Inhalt, Empfänger, Recht und Zeitpunkt.
  • Providerfehler: redigierter Klartext; technische Details nur im serverseitigen Log.
  • Erfolg: Testresultat, geplante lokale Zeit oder angenommener Versandauftrag.

View-Models und Actions

  • Setup-VM ist die eine Quelle für Domain-, Absender-, Footer- und Versandbereitschaft.
  • Segment-VM liefert erlaubte Felder/Operatoren, benannte Optionen, Regelgruppen und Preview-Count.
  • Campaign-Draft-VM enthält Step-Status, canContinue, Autosave-Version und Preview-Daten.
  • Versand-Preflight wird serverseitig einmal berechnet und sowohl Review-UI als auch Send/Schedule-Action übergeben bzw. erneut geprüft.
  • Report-VM redigiert Providerdetails und bildet vollständige Lifecycle-Zustände in deutsche Anzeigenamen ab.
  • Routes injizieren View-Model und Actions; Screens berechnen keine Empfängermengen oder Versandbereitschaft neu.

Daten, RLS und Querschnitt

  • P14 wird bei Berührung typisiert weitergeführt; kein Entity-Builder-Neukonsument.
  • Alle Queries und Commands laufen unter gebundenem Tenant-/User-Kontext; Forced-RLS-Proof umfasst Domain, Segment, Campaign, Recipient und Event.
  • CSRF für jede mutierende Setup-, Segment-, Kampagnen- und Versandaction.
  • Draft-, Test-, Schedule-, Send-, Cancel- und Setup-Aktionen werden auditiert; relevante Lifecycle-Ereignisse nutzen Activity/Notification.
  • Kampagnen-/Segment-Suche nutzt die zentrale Search-Registry, sofern fachlich als globale Suche freigegeben.
  • Idempotenz verhindert Doppelversand bei Retry oder Doppelklick.

Priorisierung

Priorität Inhalt
P0 Forced RLS, CSRF, Permission-Gates, ein Preflight, echte Footerprüfung, Versandbestätigung, Lifecycle, Fehlerredaktion
P1 Setup-Health, Segment-Builder, sechs Schritte, Autosave, Preview/Test, Datum/Zeit/Zone, Report, Mobile
P2 zusätzliche Report-Komfortfunktionen nur aus vorhandenen P14-Daten

Definition of Done

Status Fertigkeitskriterium Proof Zählt nicht als fertig
[x] Sidebar, Routen und Actions sind feature- und permission-gegated. Permission-/Reachability-Tests nur versteckter Button
[x] Alle P14-Datenpfade binden Forced-RLS-Kontext und verhindern Cross-Tenant-Zugriff. echte RLS-Integrationstests permissiver DB-Mock
[x] Jede mutierende Action validiert CSRF und eine typisierte Payload. Action-Tests CSRF nur im Kampagnenformular
[x] /email-marketing/setup zeigt Domain, Absender, Footer und nächste Aktion verständlich. VM-/Component-Test technischer Settings-Link ohne Status
[x] Segmente lassen sich ohne JSON oder rohe IDs bauen und sicher vorab zählen. VM-Test + E2E JSON hinter einem Textfeld
[x] Kampagnen laufen durch sechs Schritte mit stabilem Autosave und Wiederaufnahme. E2E + Autosave-Test Tabs ohne Fortschritts-/Save-Vertrag
[x] Inhalt hat Preview und Testversand an bis zu fünf Empfänger mit Einzelergebnis. Action-/E2E-Test Test nur an eingeloggten User
[x] Terminierung nutzt Datum, Uhrzeit, Zeitzone und zeigt die resultierende lokale Zeit. VM-/Action-Test freies ISO-Datumsfeld
[x] Review und Send/Schedule nutzen denselben serverseitigen Preflight. Contract-Test ähnliche, doppelt gepflegte Checklisten
[x] Finaler Versand verlangt Klartextbestätigung und ist idempotent. Command-/E2E-Test Browser-confirm oder nur deaktivierter Button
[x] Lifecycle und Report sind vollständig; Providerdetails werden redigiert. VM-/Visual-/Security-Test Rohfehler im UI
[x] Audit, Activity und Notification sind für relevante Aktionen verdrahtet. Integrationstest nur Providerlog
[x] Desktop/Mobile, States, Tastatur, Accessibility, deutsche i18n und ID-Freiheit sind verifiziert. Visual + a11y + i18n Desktop-only Happy Path
[x] VM-/Action-/Permission-/RLS-, Playwright-Smoke-, Hot-Swap- und Visual-Tests sind grün. CI-Artefakte Unit-Tests ohne Versand-Hauptflow

Rollout und Rollback

  • P0-Sicherheitskorrekturen vor UI-Rollout ausliefern, sobald E-Mail-Marketing produktiv aktiv ist.
  • Wizard hinter bestehendem Modulflag tenantweise aktivieren; Entwürfe bleiben kompatibel.
  • Metriken: Abbruch je Schritt, Testversandquote, Preflight-Fehlerklassen, Schedule-Fehler, Doppelcommand-Verhinderung und Report-Aufrufe.
  • Rollback schaltet neuen Screen/Wizard ab, ohne Drafts oder Versandhistorie zu löschen. Status-/Schemaänderungen erfolgen forward-only mit Inverse-SQL-Kommentar.

Abgrenzung

Keine allgemeine E-Mail-Inbox, keine OAuth-Providerverwaltung aus P23, keine externen Benchmarks, keine neue Deliverability-Plattform und keine Reportdaten, die P14 nicht zuverlässig erhebt.

Quellen

  • R-UX0
  • AK-P14a, AK-P14b, D-P14, D-KAMP
  • docs/ARCHITECTURE-DECISIONS.md · AD-2/AD-21/AD-28
  • .planning/INTERIM-UI-PLAYBOOK.md
  • /forms: Autosave, Tabs, Preview, Header-/Filterstruktur
  • bestehende Email-Marketing-Routes, Services, View-Models, Actions und Tests

Planungsnotiz

2026-07-25: Umsetzungsreife UX-Spec nach Freigabe angelegt.

2026-07-25 · Umsetzungs-Proof: Der geführte E-Mail-Marketing-Flow wurde mit den Commits c5cc6596d und 029f7522c umgesetzt. PR #251 bleibt bis zur lokalen Gesamtabnahme offen.

  • Security-/RLS-Proof: Sidebar, Parent-Route, Loader und Actions unterscheiden emailMarketing.view und emailMarketing.manage; mutierende Actions prüfen CSRF vor dem Form-Parsing und validieren typisierte Zod-Payloads. Die berührten Domain-, Sender-, Segment-, Campaign-, Recipient-, Outbound- und Event-Pfade laufen unter gebundenem Tenant-Kontext. Der Forced-RLS-Livevertrag wurde um Domain, Segment, Campaign, Recipient und Events erweitert.
  • Flow-/Daten-Proof: /email-marketing/setup, visueller Segment-Builder mit Empfängervorschau und der autospeichernde Sechs-Schritt-Wizard verwenden serverseitige VMs. Review und Send/Schedule teilen denselben Preflight. Versandcommands sind inhaltlich idempotent; Schedule-Cancellation nutzt Outbox, Pending-Event-Cleanup und eine Worker-Delivery-Fence gegen verspätete Zustellung.
  • UX-/Report-Proof: Kampagnenliste, Setup, Segmentregeln, Wizard, Bestätigungsdialog und Report decken Desktop, 390 px und 320 px ab. Testversand akzeptiert höchstens fünf benannte Adressen, Terminierung zeigt Datum, Uhrzeit, Zone und resultierende Zeit. Lifecycle und Providerfehler werden vollständig beziehungsweise redigiert dargestellt; rohe IDs erscheinen nicht.
  • Querschnitt-Proof: Draft, Test, Schedule, Send, Cancel, Setup, Sender und Suppression sind auditiert; relevante Kampagnenereignisse erzeugen Activity und Notifications.
  • Test-Proof: pnpm typecheck, pnpm lint, pnpm test (1.062 Testdateien / 7.547 Tests), pnpm --filter @hivegrid/web build, verify:i18n, verify:sidebar-routes, verify:tenant-policy-contract (301/301), verify:permissions-audit-baseline, verify:ui-visual, test:hot-swap, verify:a11y-coverage, gezielte Security-/VM-/Action-/ Worker-Tests sowie der Playwright-Hauptflow und Mobile-A11y bei 390 px und 320 px sind lokal grün. Der vollständige PR-CI-Lauf 11207 ist mit allen elf Jobs einschließlich Docker-Smoke, Database Checks, Build/Bundle und Typecheck/Tests grün.
  • Interim-Baseline: apps/web/app/components/screens/email-marketing/__snapshots__/email-marketing-interim.visual.test.tsx.snap; die finale Subframe-Optik bleibt als design-nachzug offen und blockiert Done nach AD-28 nicht.
  • Bekannte Main-Baseline: pnpm run verify:permission-matrix referenziert weiterhin drei vor diesem Ticket nach settings/compliance/ verschobene Testpfade unter settings/logs/. Die verifier-eigenen Permission-Audit-Tests und alle ticketbezogenen Permission-, CSRF- und Forced-RLS-Tests sind grün. Dieser scope-fremde Baseline-Nachzug wird auf R-UX2 nicht still geändert.

Stand: 14/14 DoD = 100 % done. Offen bleibt ausschließlich der nach AD-28 nicht Done-blockierende design-nachzug; Merge und Plane-Done warten auf die lokale Gesamtabnahme.