18 KiB
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 | Plane: Done · funktional + Interim-UI fertig (AD-28) · Stand 2026-07-17: 6/7 DoD voll + 1 partiell ≈ ~86 % (tz-Versand-Lücke aus Audit gefixt, e2e-Smoke neu) · design-nachzug: Rich-Text-Editor/Vorschau (D-KAMP) · extern: Lead/Projekt-Segment-Dim (R-P7/R-P8-Folge) · offen: Interim-Visual-Baseline (D21) |
🎨 design-nachzug: offen (seit 2026-07-09) — Interim-UI aus ~/ui steht; finale Subframe-Optik aus D-P14/D-KAMP ausstehend.
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.
UX-Nachzug (2026-07-25): R-UX2 übernimmt den freigegebenen Produkt-/UX-Nachzug für Setup,
Segmente, Kampagnen-Wizard, Versand und Reporting. AK-P14b bleibt das technische Fundament; die
typisierte Ablösung nach AD-2 und bestehende Versandverträge sind zu erhalten.
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
Stand 2026-07-17: Checkliste per Code-Audit gegen
mainan den realen Stand angeglichen (Proofs in der Audit-Notiz unten). Die Versand-Engine war zuvor fälschlich als voll abgehakt gemeldet — der timezone-aware Versand fehlte real und wurde jetzt gefixt.
- Block-/Rich-Text-Editor + Personalisierungs-Tokens (auch Custom-Felder) + Pflicht-Footer-Auto-Injektion + Desktop-/Mobile-Vorschau — teilweise: Token-/Footer-Logik ✅ (pure, getestet), AD-28-Interim-Editor steht; Rich-Text-Toggle + Desktop-/Mobile-Vorschau = design-nachzug (David
D-KAMP) - Segmente: verschachtelter AND/OR-Filter-Baum, Live-Auflösung, Auto-Exclusion (Unsubscribe/Suppression/kein Opt-In/archiviert/keine Email), dynamisch vs. statischer Snapshot — Kontakt-Dimensionen ✅; Lead/Projekt-Dimension extern (R-P7/R-P8-Folge)
- Versand-Engine (BullMQ, Rate-Limit, Throttling, geplanter timezone-aware Versand) — tz-Auflösung 2026-07-17 nachgezogen (
campaignSchedule.ts, Audit-Befund) - 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 — Logik + harter Server-Gate ✅; finale Optik = design-nachzug
- Reporting (Open/Click/Bounce/Abmeldung in %, Klick-Map, Pro-Empfänger) + A/B-Varianten — VMs + A/B-Schema/-Versand ✅; finale Optik = design-nachzug
- Konnektor
tenantHasModule('email'); RLS auf allen Tenant-Tabellen;is_demo_dataauf 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.prismanur 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/EmailSuppressionListaus AK-P14a. - RLS überall; Tracking mit IP-Anonymisierung.
- Konnektor
tenantHasModule('email');is_demo_dataauf 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-versandROADMAP.md→ Phase 14 · Milestones: (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)
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): neuRecipientSegment(+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). BaretenantId/kontaktId-Scalars. RLS-Artefaktprisma/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→ einmail.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 Routesoptin.$token+unsubscribe.$token(erweitert um Marketing-Token, RFC-8058 One-Click). i18nmarketing.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/.managein 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).
- Segmente: verschachtelter AND/OR-Baum, Live-Auflösung, Auto-Exclusion, dynamisch/statisch — ✅ (Kontakt-Dimensionen). Lead/Projekt-Dimension blockiert (R-P7/R-P8 offen).
- 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).
- Pflicht-Checkliste (Domain/Unsub/Impressum/Subject/>0/Daily-Cap) + Block + Fix-Link — ✅ Logik + harter Server-Gate; Checklisten-UI Teil des bespoke Editors (blockiert David).
- Reporting (Open/Click/Bounce/Abmeldung %, Klick-Map, Pro-Empfänger) + A/B-Varianten — ✅ VMs + A/B-Schema/ -Versand; Reporting-UI blockiert (David).
- Konnektor
tenantHasModule('email')+ RLS +is_demo_data— ✅ (Featureemail-marketing+ RLS-ArtefaktemailMarketing.*-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).
2026-07-09 — Interim-UI + Campaign-Routen (AD-28)
Interim-Screens aus ~/ui nachgezogen: Kampagnenliste (/email-marketing/campaigns), Draft-Editor (/campaigns/new), Kampagnen-Detail/Reporting mit Pre-Send-Checkliste und Send-Action (/campaigns/:id), Templates-Liste, Segmente-Screen als SegmentsPage, Public Opt-in/Unsubscribe-Result-Screen. Backend ergänzt: Draft-Erstellung auf typisiertem Campaign, Detail-Aggregation über CampaignDetailVM, Checklisten-Anzeige, Send-Action auf dispatchCampaign, Suppression-Verwaltung aus AK-P14a. Subframe geprüft: kein P14/D-KAMP-Screen vorhanden, daher AD-28-Interim statt finaler Subframe-Optik.
Proof: pnpm typecheck grün; pnpm lint grün; JSON-Parse en/de grün; pnpm --filter @hivegrid/view-models test -- --runInBand grün; gezielte Web-Tests emailMarketing + unsubscribe.$token + unsubscribeToken grün. Breites pnpm test bleibt auf Windows rot durch bestehende/unabhängige Guards (URLSearchParams-Undici, Symlink-EPERM, Decision-Report-Drift), nicht durch P14.
2026-07-09 — Campaign-Route-Fix + Form-Submission Double-Opt-in
Nachzug auf dem Interim-Stand: Parent-Route /email-marketing/campaigns ist jetzt reine Layout-Route mit Outlet; die Liste liegt unter campaigns/index.tsx, damit /campaigns/new und /campaigns/:id wirklich rendern. Draft-Save validiert Sender und Segment tenant-scoped vor Campaign.create und zeigt einen Klartext-Fehler bei ungültiger Auswahl.
Form-Widget-Post-Submit-Actions um start_double_opt_in erweitert: Builder-Auswahl, Save-Parser, Prisma-Enum, Worker-Runner, FormActionLog, Consent-Upsert und bestehende mail.transactional.send-Outbox. Der Runner resolved Kontakt per kontaktId oder E-Mail/Telefon aus dem Field-Mapping, schreibt KontaktMarketingConsent(single) mit Opt-in-Token und queued die Bestätigungs-Mail auf /optin/{token}. Die Marketing-Token-HMAC-Logik liegt jetzt in @hivegrid/foundation/marketing-token, Web re-exportiert den bisherigen Server-Helper weiter.
Proof: pnpm --filter @hivegrid/web typecheck grün; pnpm --filter @hivegrid/worker typecheck grün; pnpm lint grün; pnpm exec vitest run apps/worker/src/jobs/form-submission-actions.test.ts apps/worker/src/jobs/form-submission-route.test.ts 'apps/web/app/routes/app.$tenant/forms.$id.action.test.ts' grün (23 Tests); pnpm exec vitest run apps/web/app/utils/email/marketingToken.test.ts grün (5 Tests). pnpm --filter @hivegrid/foundation typecheck bleibt rot durch bestehende Test-Typfehler in outbound-http.test.ts/permissions.test.ts, nicht durch marketing-token.ts.
Stand: 6/7 DoD voll + 1 partiell ≈ ~86 % done. Selbst-machbar offen: e2e-Smoke/Visual-Baseline gegen laufenden Stack. Extern blockiert: finale Subframe-Optik (Davids D-P14/D-KAMP-Delta) und Lead/Projekt-Segmentdimension, soweit Folge-Tickets sie produktisieren.
2026-07-17 — Stand-Audit + Restarbeiten (Branch fix/ak-p14-audit-restwork)
Vollständiges Code-Audit gegen main. Kern bestätigt: Segmente (segmentFilter.ts + SegmentService.server.ts, 5-fach-Auto-Exclusion, Snapshot), Versand (campaignSendPlan.ts d'Hondt-A/B + Throttle, CampaignSendService.server.ts harter Checklisten-Gate + Suppression-Re-Check + List-Unsubscribe), DOI/Unsubscribe (ConsentService.server.ts, RFC-8058, Form-Action start_double_opt_in), Reporting-VMs, Gating/RLS/Migrationen (20260703150000_ak_schema_parity_catchup + 20260709213000_ak_p14_form_action_double_opt_in).
Audit-Befund + Fix: Der „timezone-aware Versand" war nur nominell — scheduledAt wurde per new Date() in Server-Lokalzeit geparst, campaign.timezone gespeichert aber nie benutzt (CampaignSendService.server.ts nutzte scheduledAt.getTime() direkt). Gefixt: neues pures apps/web/app/utils/integrations/email/campaignSchedule.ts (parseScheduledAt via date-fns-tz/fromZonedTime, explizite Offsets bleiben, invalide Zone/Datum → Klartext-Fehler emailMarketing.campaign.editor.error.invalidSchedule de/en), verdrahtet im Draft-Save (campaigns/new.tsx). 6 neue Unit-Tests (Berlin vs. New York, Sommer/Winter, Offset, invalid).
Test-Nachzug (D18): ConsentService.server.test.ts neu (7 Tests: Opt-in-Upsert, Confirm-Idempotenz, Public-Status-Mapping, Unsubscribe-Idempotenz). VM-Tests existierten bereits (email-marketing.vm.test.ts deckt presend-checklist/campaign-detail/campaign-list/segment), personalization ist in campaignSendPlan.test.ts abgedeckt — frühere „fehlt"-Meldung war zu pessimistisch. e2e-Smoke (D19): tests/e2e/email-marketing-smoke.spec.ts neu gebaut (Login → Overview → Kampagnen-Liste, skippt sauber ohne Credentials/Entitlement). Hinweis: Die im Plane-Kommentar vom 2026-07-15 genannten Restarbeiten-Artefakte lagen nur auf einem lokalen, ungepushten Branch — alles hier wurde frisch neu erstellt.
Proof: node scripts/vitest-cli-compat.mjs run campaignSchedule.test.ts (6) grün · ConsentService.server.test.ts (7) grün · pnpm --filter @hivegrid/web typecheck exit 0 · pnpm run verify:i18n exit 0 · playwright --list sammelt den Smoke · eslint grün. Commits: b79e960bf (tz-Fix), f4d019b80 (Consent-Tests), f16a7e290 (Smoke).
Staging-Live-Check (2026-07-17, staging-app.hivegrid.de/demo-pro-crm): Overview, Kampagnen-Liste (Empty-State), Sendedomain (Empty-State + Domain-Eingabe) und Segmente (Filter-JSON + Snapshot-Checkbox) rendern live. Befund dabei: Die Overview-Kacheln „Gesendet"/„Zugestellt" zeigten bei Wert 0 gar nichts an — StatsCard rendert {value ? …}, numerische 0 ist falsy. Gefixt per String-Übergabe im Interim-Screen (kein Eingriff in ~/ui). Nit notiert (nicht gefixt, Breadcrumb-Thema für Design-Nachzug): Breadcrumb zeigt auf /campaigns „Dashboard" und auf /segments „E-Mail-Marketing" statt des Screen-Titels.
Stand: 6/7 DoD voll + 1 partiell ≈ ~86 % done. Design-nachzug: Rich-Text-Editor + Vorschau (David D-KAMP). Extern: Lead/Projekt-Segment-Dimension (R-P7/R-P8-Folge). Offen als AGENTS-Pflicht-DoD-Nachzug (nie in Ticket-DoD erfasst): Interim-Visual-Baseline (D21, braucht laufenden Stack), Hot-Swap-Drill-Beleg (D20).
Dev-Nachzug (nach Davids D-KAMP/D-P14-Delta)
- Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
- REQUIREMENTS/ROADMAP nachgezogen
- Plane-Ticket
AK-P14baktualisiert