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

247 lines
15 KiB
Markdown

# 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](https://project.tool-ctrl.de/toolctrl/projects/35d0d968-8ab3-40cc-97b8-b81d917dc5df/issues/0e53867b-9d04-4b92-b6ff-ad49bcaae9ab) · 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`](R-UX0.md)
- `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](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/pulls/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](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/actions/runs/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.