116 lines
10 KiB
Markdown
116 lines
10 KiB
Markdown
# AK-P14b · P14 Email-Marketing (Kampagnen + A/B)
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Typ** | Dev (Code) |
|
||
| **Owner** | Akeshan |
|
||
| **Phase** | P14 — Email & Marketing |
|
||
| **Cycle/Fenster** | W3 — Kern-Kette & Kommunikation (Demo 2) · fällig 2026-06-29 · Gate W3 |
|
||
| **Status** | geplant |
|
||
|
||
## Abhängigkeiten & Parallelität
|
||
- **Blocked by:** `AK-P14a` (verifizierte Sende-Domain + Tracking-Infra + Suppression)
|
||
- **Blocks:** — (Endpunkt der Email-Schiene)
|
||
- **Läuft parallel zu:** Raffaels Kern-Kette. Eigene `prisma/schema/email.prisma` (gleicher Namespace wie AK-P14a, additive Tabellen — AD-21); Segmente lesen CRM-Kontakte read-only (R-P6). **Sync-Punkt:** R-P6 (Kontakt/Tag/Custom-Feld) muss stehen, damit Segment-Filter auflösen.
|
||
- **Konflikt-Risiko:** keines auf Schema-Ebene; CRM nur lesend.
|
||
|
||
## Was wir bauen
|
||
Das **vollständige DSGVO-konforme Email-Marketing** (bleibt VOLL inkl. A/B): ein mehrstufiger **Kampagnen-Builder** (Basis → Inhalt mit Rich-Text/HTML-Toggle + Personalisierungs-Tokens inkl. Custom-Felder + Pflicht-Footer-Auto-Injektion + Desktop-/Mobile-Vorschau → Empfänger → Test-Versand → Zeitpunkt → Bestätigung mit Klartext-Checkliste), **Segmente** mit verschachteltem AND/OR-Filter-Baum und Auto-Exclusion, **Double-Opt-In**, **One-Click-Unsubscribe** + List-Unsubscribe-Header, eine **BullMQ-Versand-Engine** mit Rate-Limiting/Throttling/geplantem (timezone-aware) Versand, **Reporting** (Open/Click/Bounce/Abmeldung, Klick-Map) und **A/B-Varianten**. Versand wird bei rotem Pflicht-Check (Domain/Unsubscribe/Impressum) **blockiert**.
|
||
|
||
## Benötigte Screens (Backend bedient — Design liefert `D-KAMP` + `D-P14`)
|
||
| Screen [Route] | Kern-Inhalt |
|
||
|---|---|
|
||
| Kampagnen-Editor [`/email-marketing/campaigns/new`] | Mehrstufiger Wizard (Basis/Inhalt/Empfänger/Test/Zeitpunkt/Bestätigung), Token-Einfügen, Pflicht-Footer, Vorschau, Pflicht-Checkliste mit Versand-Blockade — **BESPOKE** |
|
||
| Kampagnen-Liste + -Detail [`/email-marketing/campaigns`] | Liste (Status/Empfänger/Datum/Stats); Detail mit KPI-Header, Klick-Map, Pro-Empfänger-Tabelle, A/B-Vergleich |
|
||
| Segmente [`/email-marketing/segments`] | Verschachtelter AND/OR-Filter-Baum, Live-Empfänger-Anzahl, Auto-Exclusion-Aufschlüsselung, Sample-Vorschau, dynamisch/statischer Snapshot |
|
||
| Templates [`/email-marketing/templates`] | Template-Liste, Vorschau, als Ausgangspunkt verwenden |
|
||
| 🌐 Unsubscribe-Page [`/unsubscribe/{token}`] | Bestätigungs-Button, optionale Grund-Auswahl, Erfolgs-Meldung, Tenant-Branding |
|
||
|
||
## Definition of Done
|
||
- [ ] **Block-/Rich-Text-Editor** + Personalisierungs-Tokens (auch Custom-Felder) + Pflicht-Footer-Auto-Injektion + Desktop-/Mobile-Vorschau
|
||
- [ ] **Segmente**: verschachtelter AND/OR-Filter-Baum, Live-Auflösung, Auto-Exclusion (Unsubscribe/Suppression/kein Opt-In/archiviert/keine Email), dynamisch vs. statischer Snapshot
|
||
- [ ] **Versand-Engine** (BullMQ, Rate-Limit, Throttling, geplanter timezone-aware Versand)
|
||
- [ ] **Double-Opt-In** (aus Form-Submissions) + **Suppression-Check vor jedem Versand** + **One-Click-Unsubscribe** + List-Unsubscribe-Header
|
||
- [ ] **Pflicht-Checkliste** vor Versand (Domain verifiziert / Unsubscribe / Impressum / Subject / >0 Empfänger / Daily-Cap) — Block + Fix-Link bei rotem Check
|
||
- [ ] **Reporting** (Open/Click/Bounce/Abmeldung in %, Klick-Map, Pro-Empfänger) + **A/B-Varianten**
|
||
- [ ] Konnektor `tenantHasModule('email')`; RLS auf allen Tenant-Tabellen; `is_demo_data` auf Demo-Kampagnen/-Segmenten/-Templates
|
||
|
||
## Technische Bausteine
|
||
- **Entities** (eigene `prisma/schema/email.prisma`): `Campaign` (subject, template_id, sender_id, recipient_segment_id, status, delivered/opened/clicked_count), `OutboundEmail` (campaign_id, recipient_kontakt_id, tracking_token, unsubscribe_token, delivery_status), `OutboundEmailOpen`/`Click`, `RecipientSegment` (entity_type, filter_definition JSONB, is_static_snapshot), `Unsubscribe` (kontakt_id, scope, reason). `crm.prisma` nur lesend (Kontakt/Tag/CustomFieldValue).
|
||
- **Versand** über BullMQ mit Provider-Abstraktion (Mailjet, AD-6), Rate-Limit-Worker, timezone-aware Scheduling.
|
||
- **Segment-Engine**: JSONB-Filter → typsicherer Query-Builder gegen CRM (read-only), Auto-Exclusion gegen `Unsubscribe`/`EmailSuppressionList` aus AK-P14a.
|
||
- **RLS** überall; **Tracking** mit IP-Anonymisierung.
|
||
- **Konnektor** `tenantHasModule('email')`; `is_demo_data` auf seedbaren Demo-Daten.
|
||
|
||
## Quellen (granular)
|
||
- `ENTITY-MODEL.md` → **Domäne 8: Kommunikation** (Campaign, OutboundEmail +Open/Click, RecipientSegment, Unsubscribe)
|
||
- `REQUIREMENTS.md` → `REQ-marketing-datenmodell`, `REQ-marketing-double-optin`, `REQ-marketing-versand`
|
||
- `ROADMAP.md` → Phase 14 · `PHASE-SOURCES.md` → Phase 14 (M100-editor, M101-segmente, M102-versand-engine, M103-ab-tests-reporting, M104-unsubscribe-bounces — Marketing bleibt VOLL inkl. A/B)
|
||
- `designer-briefs/P14-email-marketing.md` (Kampagnen-Editor BESPOKE, Segmente, Unsubscribe-Page)
|
||
- `_bmad-output/specs/M10-email-marketing.md`
|
||
|
||
## Umsetzung (Akeshan)
|
||
|
||
### 2026-06-29 — Typisierte Backend-Foundation (S1–S7), ~78 % DoD
|
||
Branch `feat/AK-P14b` (von `feat/AK-P14a`, noch nicht gepusht). Plan-Entscheidung (User, 2026-06-29):
|
||
**typisierter Pfad** (neuer Code liest R-P6 `Kontakt`, KEIN neuer Entity-Builder-Konsument, AD-2) +
|
||
**Backend-Foundation jetzt**, bespoke Editor/Unsubscribe-Page + Lead/Projekt-Segment-Dimensionen + e2e/Visual
|
||
zurückgestellt. Der bestehende Entity-Builder-Kampagnen-Pfad (`CrmService`/`EntityViewsApi`/
|
||
`OutboundEmail.contactRowId`) bleibt **unangetastet** (gehört R-P14C).
|
||
|
||
**Gebaut + verifiziert (46 neue Unit-Tests grün, alle Typechecks 0 Fehler, verify:i18n exit 0):**
|
||
- **S1 Schema** (`prisma/schema/email.prisma`, additiv, `db push`, keine Migration — AD-21): neu `RecipientSegment`
|
||
(+`SegmentSnapshotMember`), `CampaignVariant` (A/B), `KontaktMarketingConsent` (in email.prisma, **nicht**
|
||
crm.prisma), `Unsubscribe`; `Campaign` (+`recipientSegmentId`/`scheduledAt`/`timezone`/`previewText`/
|
||
`footerHtml`/`isDemoData`/`archivedAt`), `OutboundEmail` (+`kontaktId`/`campaignVariantId`/`unsubscribeToken`/
|
||
`trackingToken`). Bare `tenantId`/`kontaktId`-Scalars. RLS-Artefakt `prisma/rls/email-isolation.sql` +
|
||
`TENANT_SCOPED_MODELS`-Registry nachgezogen. `models.test.ts` (11) grün.
|
||
- **S2 Segment-Engine** (typisiert, Kontakt-only): pure `segmentFilter.ts` (Validierung Tiefen-/Node-Cap,
|
||
Lookup-Collection, JSONB→`Prisma.KontaktWhereInput`) + `SegmentService.server.ts` (Lookup-Auflösung Tag/
|
||
Custom-Feld, Auto-Exclusion archiviert/keine-Email/Unsubscribe/Suppression/kein-Double-OptIn als
|
||
non-overlapping Breakdown, Live-Count+Sample, Snapshot). 13 Tests.
|
||
- **S3 Versand-Engine**: pure `personalization.ts` (Token inkl. `cf.<key>`, idempotente Footer-Injektion) +
|
||
`campaignSendPlan.ts` (A/B per d'Hondt interleaved, Throttle→BullMQ-`delay`, timezone-`startAt`) +
|
||
`CampaignSendService.server.ts` (Audience→harter Checklisten-Gate→Suppression-Re-Check→OutboundEmail-Row→
|
||
ein `mail.transactional`-Job je Empfänger mit List-Unsubscribe-Header; kein neuer Worker-Queue). 14 Tests.
|
||
- **S4 Double-Opt-In + Ein-Klick-Abmeldung**: `marketingToken.server.ts` (HMAC unsub/optin, 5 Tests) +
|
||
`ConsentService.server.ts` (startDoubleOptIn/confirmOptIn/unsubscribeKontakt, idempotent) + public Routes
|
||
`optin.$token` + `unsubscribe.$token` (erweitert um Marketing-Token, RFC-8058 One-Click). i18n `marketing.optin.*`.
|
||
- **S5 VMs** (`packages/view-models/src/email/`, pure): `presend-checklist.vm` (kanonischer Checklisten-Kern,
|
||
von der Send-Engine importiert), `campaign-detail.vm` (KPI%/Klick-Map/Pro-Empfänger/A-B), `campaign-list.vm`,
|
||
`segment.vm`. 7 Tests.
|
||
- **S6 Permissions**: `emailMarketing.view/.manage` in 4 Registries (permissions-seed Array+Rollen-Map,
|
||
DefaultPermissions, roleDisplay-Scope, i18n en/de). roleDisplay.test (7) grün.
|
||
- **S7 Segmente-Route** (`app.$tenant/email-marketing/segments.tsx`, reachable, gated, i18n en/de, Empty-State):
|
||
Liste + Erstellen aus AND/OR-Filter + Live-Preview gegen typisierte Kontakte. Tab im Modul-Shell.
|
||
|
||
**Proof:** 46/46 neue Unit-Tests grün; `@hivegrid/web`+`@hivegrid/db`+`@hivegrid/view-models`+`@hivegrid/cli`
|
||
typecheck 0 Fehler; `prisma validate` + `db push` (lokal) grün; `verify:i18n` exit 0 (Parität en/de);
|
||
hardcoded-strings auf Baseline; lefthook pre-commit je Commit grün. 7 Commits (S1–S7) auf `feat/AK-P14b`.
|
||
|
||
### DoD-Stand
|
||
- [~] Block-/Rich-Text-Editor + Tokens (inkl. Custom-Felder) + Pflicht-Footer + Desktop/Mobile-Vorschau —
|
||
Token-/Footer-Logik ✅ (pure, getestet); Rich-Text-Editor + Vorschau-UI **blockiert (David D-KAMP)**.
|
||
- [x] Segmente: verschachtelter AND/OR-Baum, Live-Auflösung, Auto-Exclusion, dynamisch/statisch — ✅
|
||
(Kontakt-Dimensionen). Lead/Projekt-Dimension **blockiert (R-P7/R-P8 offen)**.
|
||
- [x] Versand-Engine (BullMQ, Rate-Limit/Throttling, timezone-Scheduling) — ✅ (Throttle via per-Empfänger-
|
||
`delay`-Spreizung; worker-seitiger Limiter unverändert).
|
||
- [~] Double-Opt-In + Suppression-Check vor Versand + One-Click-Unsubscribe + List-Unsubscribe-Header — ✅
|
||
Kern; volle Form-Widget-Verdrahtung (Submission→Opt-In-Mail-Trigger) **teilweise** (Service da, Auto-Trigger offen).
|
||
- [x] Pflicht-Checkliste (Domain/Unsub/Impressum/Subject/>0/Daily-Cap) + Block + Fix-Link — ✅ Logik + harter
|
||
Server-Gate; Checklisten-**UI** Teil des bespoke Editors (blockiert David).
|
||
- [x] Reporting (Open/Click/Bounce/Abmeldung %, Klick-Map, Pro-Empfänger) + A/B-Varianten — ✅ VMs + A/B-Schema/
|
||
-Versand; Reporting-**UI** blockiert (David).
|
||
- [x] Konnektor `tenantHasModule('email')` + RLS + `is_demo_data` — ✅ (Feature `email-marketing` + RLS-Artefakt
|
||
+ `emailMarketing.*`-Permissions).
|
||
|
||
**Stand: 5/7 DoD voll + 2 partiell ≈ ~78 % done.** Extern blockiert: bespoke Kampagnen-Editor + Reporting-UI +
|
||
Unsubscribe-Page-Branding (Davids `D-KAMP`/`D-P14`-Delta), Lead/Projekt-Segmentdimension (R-P7/R-P8), e2e-Smoke
|
||
(braucht Stack+Seed) + Visual-Regression (braucht finale UI), Form-Widget→Opt-In-Auto-Trigger. Selbst-machbar
|
||
offen: Form-Widget-Trigger verdrahten (klein). **Nicht** anfassen: Alt-Pfad-Migration (R-P14C, Raffael).
|
||
|
||
## Dev-Nachzug (nach Davids `D-KAMP`/`D-P14`-Delta)
|
||
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
|
||
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
|
||
- [ ] Plane-Ticket `AK-P14b` aktualisiert
|