Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
1 parent
5e99e14772
commit
7f88026f79
5955 files changed
+1177325
-188362
No files matched your search
@@ -0,0 +1,246 @@
|
||||
# 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.
|
||||
Reference in new issue
Block a user