Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/AK-P14b.md
T
2026-07-08 16:15:37 +02:00

10 KiB
Raw Blame History

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).
  • 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 — ✅ (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