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

149 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 `main` an 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`)*
- [x] **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)*
- [x] **Versand-Engine** (BullMQ, Rate-Limit, Throttling, geplanter timezone-aware Versand) — *tz-Auflösung 2026-07-17 nachgezogen (`campaignSchedule.ts`, Audit-Befund)*
- [x] **Double-Opt-In** (aus Form-Submissions) + **Suppression-Check vor jedem Versand** + **One-Click-Unsubscribe** + List-Unsubscribe-Header
- [x] **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*
- [x] **Reporting** (Open/Click/Bounce/Abmeldung in %, Klick-Map, Pro-Empfänger) + **A/B-Varianten** — *VMs + A/B-Schema/-Versand ✅; finale Optik = design-nachzug*
- [x] 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 · 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): 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).
### 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-P14b` aktualisiert