Files
HiveGrid-Wireframes/hivegrid-cloud/docs/boilerplate-mapping/M10-email-marketing.md
T

148 lines
26 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.
# Boilerplate-Abgleich: M10 — Email-Marketing
| Feld | Wert |
| --- | --- |
| **Modul-ID** | M10 (Modul 10) |
| **Name** | Email-Marketing |
| **Milestones** | M100 (Kampagnen-Editor / Block-Style + Personalisierung + Vorschau + Test-Mail), M101 (Empfänger-Segmente / CRM-Filter), M102 (Versand-Engine + DKIM/SPF + Daily-Cap + Frequenz-Schutz + Pflicht-Footer), M103 (A/B-Tests Phase 2 + Reporting/Stats), M104 (Unsubscribe + Bounce-Handling + Suppression) |
| **Pflichtenheft-Block** | Block 5, Modul 10 (`_bmad-output/pflichtenheft/blocks/block5.md` §10.1–10.12) |
| **Detail-Spec** | `_bmad-output/specs/M10-email-marketing.md` |
| **Reuse-Level** | **medium** |
## Reuse-Verdikt (Kurzfassung)
M10 ist das **best-vorbereitete Kommunikations-Modul** der Boilerplate. Es existiert ein **vollständiger Email-Marketing-Vertikalschnitt** im Web-App (`apps/web/app/modules/emailMarketing/**`) mit Tenant- UND Admin-Scope, hinter Feature-Flag `email-marketing` (`packages/entitlements`): Kampagnen-CRUD, Sender-Verwaltung, Outbound-Email-Liste, Summary-Dashboard, Test-Mail/Preview, Personalisierungs-Token-Replace, Versand über MailerSend mit Open/Click-Tracking-Settings. Die Datenmodelle `Campaign`, `OutboundEmail`, `OutboundEmailOpen`, `OutboundEmailClick`, `EmailSender` (`prisma/schema/email.prisma`) decken den Kern der Spec-Block-A-Entitäten **teilweise 1:1** ab.
**Aber** — und das drückt das Verdikt von `high` auf `medium`:
1. **Vier zentrale Spec-Modelle fehlen komplett:** `Unsubscribe`, `EmailSuppressionList`, `RecipientSegment`, `EmailTemplate`. Verifiziert per Grep über alle `*.prisma`: kein Treffer. Unsubscribe lebt heute nur als `OutboundEmail.unsubscribedAt`-Flag bzw. `EmailSequenceRun.status='unsubscribed'` — **keine tenant-weite, CRM-Lösch-persistente Sperrliste** (Spec Block H/G + 10.5.5).
2. **Zwei parallele, NICHT verbundene Email-Systeme:** (a) Tenant-`Campaign`/`OutboundEmail` (Broadcast) und (b) operator-seitige Drip-Funnel (`EmailSequence`/`EmailSequenceRun`/`EmailSequenceStepDelivery`, `packages/email-sequences`). **Die öffentlichen Tracking-/Unsubscribe-Routen (`/unsubscribe/$token`, `/email/track-open`, `/email/track-click`) operieren ausschließlich auf dem SEQUENCE-System, NICHT auf `OutboundEmail`.** Für M10 muss Tracking/Unsubscribe auf `Campaign`/`OutboundEmail` umverdrahtet bzw. neu gebaut werden (die HMAC-Token-Mechanik + Pixel-Route sind aber 1:1-Vorlagen).
3. **Anti-Spam-/Versand-Robustheit fehlt fast vollständig:** kein Daily-Cap pro Plan, kein Frequenz-Cap/Empfänger/Woche, kein Spam-Score-Check, kein Throttling pro Tenant/Empfänger-Domain, **kein geplanter Versand**, **kein BullMQ-Versand-Worker für Kampagnen** (Versand läuft heute synchron in-process via `mapWithConcurrency`, Konkurrenz 5 — Spec K + E verlangen Queue + Cron + Throttle).
4. **DSGVO-Opt-In-Dokumentation fehlt:** kein `marketing_opt_in_at/_source/_reference/_text_snapshot` (Spec Block H 10.7). Heute nur ein CRM-Boolean `marketingSubscriber` (Custom-Field via `CrmService`).
5. **Provider:** Boilerplate nutzt **MailerSend** (`packages/mail`) — Spec/LP-13 verlangt EU-SMTP (Scaleway TEM/Brevo EU/Mailjet EU). Provider-Adapter-Pattern existiert (`MailProvider`-Interface), aber MailerSend ist kein EU-Anbieter → Adapter-Austausch nötig (offener Spec-Punkt).
6. **Keine M9-Sending-Domain-Verknüpfung:** `EmailSender` hält `apiKey`/`fromEmail`/`provider` direkt, **kein FK auf `TenantSendingDomain`** (existiert in M9 noch nicht). DKIM-Verifikations-Gate vor Versand fehlt.
7. **Kein Segment/Filter-Tree:** Empfänger werden heute über `EntityViewsApi` (CRM-Entity-Views) als Quelle gezogen — solide Wiederverwendung als Basis für M101, aber das spezifizierte `RecipientSegment` mit verschachteltem AND/OR-JSONB-Filter-Tree + Static-Snapshot + Auto-Exclusion-Aufschlüsselung ist neu.
8. **Layer-Disziplin:** Bestehender Code folgt dem ToolCTRL-Muster (Service direkt aus Route, `db.server` in Modul-Code), NICHT der HiveGrid-DoD (View-Model-Layer `packages/view-models`, `packages/ui-hivegrid`, Subframe-Adapter, kein Prisma in UI). → **Übernahme erfordert Re-Layering** in die HiveGrid-Struktur.
Fazit: Solide Fachbasis (Campaign-Send + Tracking-Datenmodell + MailerSend-Adapter + UI-Bausteine + i18n) spart erheblich Arbeit, aber die DSGVO-/Anti-Spam-/Segment-/Suppression-/Scheduling-Hälfte ist Neubau. Daher `medium`.
---
## Übernehmbar aus Boilerplate
> Boilerplate-Wurzel (NUR LESEN): `/Users/raffaelsheikh/Documents/GitHub/boilerplate`
| Boilerplate-Pfad | Was | Wie nutzbar |
| --- | --- | --- |
| `prisma/schema/email.prisma` (`Campaign`, `OutboundEmail`, `OutboundEmailOpen`, `OutboundEmailClick`, `EmailSender`) | Kern-Datenmodell: Kampagne (name/subject/html/text/status/track/sentAt), Outbound-Email pro Empfänger (email, sentAt/deliveredAt/bouncedAt/spamComplainedAt/unsubscribedAt, FK auf `Row` als Kontakt), Open/Click-Tracking-Tabellen, Sender | **anpassen** — Felder fehlen massiv gegenüber Spec Block A (preheader, recipient_segment_id, recipient_list_snapshot, scheduled_at, *_count-Aggregate, tracking_token/unsubscribe_token unique, bounce_type, personalization_payload, delivery_status-Enum, Indizes). `tenantId` ist `String?` (operator-nullable) → für RLS auf NOT-NULL-Tenant-Scope härten |
| `apps/web/app/modules/emailMarketing/services/EmailMarketingService.ts` | `getSummary` (Open/Click-Rate-Aggregation), `createCampaignDraft`, `sendCampaign` (mapWithConcurrency), `sendCampaignTest` (max 5), `sendPreview`/`sendContactPreview`, `replaceVariables` (`{{firstName}}`/`{{lastName}}`/`{{email}}`/`{{job_title}}`/`{{company_name}}`) | **als-vorlage** — Logik-Gerüst für Versand + Personalisierung übernehmbar; muss aber in `app/domain/**`-Layer + BullMQ-Worker (Spec E) statt synchron, Token-Format auf `{{first_name}}` (Spec C) angleichen, Custom-Field-Token `{{custom.x}}` ergänzen, Auto-Exclusion + Footer-Injection + Cap-Checks fehlen |
| `apps/web/app/modules/emailMarketing/services/EmailMarketingSenderService.server.ts` | `sendBroadcast()` Provider-Switch → `sendMailerSendBroadcast` (MailerSend-Send mit `settings.trackClicks/trackOpens`, replyTo, tags) | **als-vorlage** — Send-Adapter-Pattern; Provider muss auf EU-SMTP (LP-13) gewechselt/ergänzt werden; DKIM-/Domain-Gate fehlt |
| `apps/web/app/modules/emailMarketing/db/campaigns.db.server.ts` | `getAllCampaigns`/`getCampaign` (mit recipients+opens+clicks+contactRow-Include), `createCampaign` (nested recipients), `updateCampaign` (recipient-replace), `deleteCampaign`, `groupCampaigns` (by status) | **anpassen** — tenant-scoped Queries direkt verwendbar als Basis; auf `withTenantScope()` (M004) + neue Felder/Snapshot anheben |
| `apps/web/app/modules/emailMarketing/db/outboundEmails.db.server.ts` | `getAllOutboundEmails` (paginiert), `createOutboundEmail(Test)`, `updateOutboundEmail` (sentAt/deliveredAt/bouncedAt/spamComplainedAt/unsubscribedAt), `openedOutboundEmail`/`clickedOutboundEmail`, `unsubscribeCampaignRecipient`, `countOutboundEmails` | **anpassen** — Pro-Empfänger-Liste + Status-Updates (Spec F „Pro-Empfänger-Anzeige") fast vollständig; Bounce-Klassifikation (hard/soft), Suppression-Add, Activity-Wiring fehlen |
| `apps/web/app/modules/emailMarketing/db/emailSender.ts` + `services/EmailMarketingSenderService.server.ts` + `components/EmailSenderForm.tsx` + `routes/Senders_*.ts` + `components/senders/Senders{List,New,Edit}Route.tsx` | Sender-Verwaltung End-to-End (CRUD + Form + List/Edit/New) | **als-vorlage** — Sender-UI/-Flow direkt nachnutzbar; Validierung „from_email-Domain muss zu Sending-Domain passen" + M9-`sending_domain_id`-FK + DKIM-Status-Anzeige + is_default + archived_at ergänzen |
| `apps/web/app/modules/emailMarketing/components/campaigns/CampaignsNewRoute.tsx` + `CampaignsEditRoute.tsx` + `CampaignsListRoute.tsx` + `campaignDefaults.ts` | Kampagnen-Editor (Name/Sender/Empfänger-View/Subject/HTML-Body via `InputContent` WYSIWYG+Markdown), Test-Mail-Button, Default-HTML-Body, Liste | **als-vorlage** — Editor-Grundgerüst; der spezifizierte 6-Schritt-Wizard (Basis→Inhalt→Empfänger→Test→Zeitpunkt→Bestätigung mit Pflicht-Checks), Mobile/Desktop-Vorschau, Spam-Score, Auto-Exclusion-Anzeige fehlen. Re-Layering nach `ui-hivegrid`/Subframe-Adapter nötig |
| `apps/web/app/modules/emailMarketing/components/OutboundEmailsTable.tsx` + `outboundEmails/OutboundEmailsListRoute.tsx` + `EmailMarketingSummaryRoute.tsx` + `routes/EmailMarketing_Summary.ts` | Outbound-Tabelle (Status/Opens/Clicks/Kontakt), Summary-Dashboard (avg Open/Click-Rate, sent/delivered) | **als-vorlage** — deckt Spec F „Stats-Aggregation" + „Pro-Empfänger-Liste" teilweise; CTR, Bounce-Raten, Unsubscribe-Rate, Complaint-Rate, Click-Map, Filter nach Status ergänzen |
| `apps/web/app/routes/app.$tenant/email-marketing.tsx` + `email-marketing/{index,activity,senders,campaigns/*}.tsx` | Tenant-Route-Tree mit `SidebarIconsLayout` (Overview/Campaigns/Activity/Senders), `requireTenantProductAccess(featureKeys.emailMarketing)` | **als-vorlage** — Route-Struktur + Feature-Flag-Gate + Sub-Nav; an HiveGrid-Route-Pattern (`/{tenant}/email-marketing/...`, INTEGRATION-CONTRACTS §3) + `sidebar.config.ts`-Eintrag (Gruppe „Kommunikation") + Permission `email_marketing.*` (M004) angleichen |
| `apps/web/app/routes/unsubscribe.$token.tsx` + `app/utils/email/unsubscribeToken.server.ts` + `packages/email-sequences/src/unsubscribe-token.ts` (`signUnsubscribeToken`/`verifyUnsubscribeToken`/`buildUnsubscribeUrl`) | Öffentliche Unsubscribe-Route (GET+POST, kein Login, Token=Auth, idempotent) + HMAC-SHA256-Token-Mechanik (`MARKETING_TOKEN_SECRET`, timing-safe) | **als-vorlage** — exakte Blaupause für Spec Block H Unsubscribe-Page; **aber** Token zeigt heute auf `EmailSequenceRun`, muss auf `OutboundEmail.unsubscribe_token`/`Unsubscribe`-Modell + `EmailSuppressionList`-Add + Grund/Feedback-Formular + Activity-Eintrag umgebaut werden. List-Unsubscribe-One-Click-Flow (RFC-8058) ist bereits berücksichtigt |
| `apps/web/app/routes/email/track-open.$deliveryId[.gif].tsx` + `track-click.$deliveryId.tsx` | 1×1-GIF-Pixel-Route (Cache-Control no-store, idempotenter First-Open via `updateMany`), Click-Redirect-Route | **als-vorlage** — Pixel-/Redirect-Mechanik 1:1; Ziel-Modell von `EmailSequenceStepDelivery` auf `OutboundEmail`/`OutboundEmailOpen`/`OutboundEmailClick` umverdrahten; `link_url`/`link_label`/`reader_ip`(anonymisiert)/`reader_user_agent`/`is_first_open` ergänzen (Spec Block F) |
| `apps/api/src/webhooks/mailersend-signature.ts` (`verifyMailerSendWebhookSignature`) | Inbound-Webhook-HMAC-Verify (timing-safe, Timestamp-Toleranz, Header-Kandidaten) | **1:1** für Bounce-/Complaint-Webhook-Empfänger (Spec Block G `/api/v1/webhooks/email/bounce`); Provider-Wechsel ggf. anderer Verify |
| `apps/api/src/email-sequences/provider-webhook-route.ts` (`postMailerSendEmailSequenceWebhookRequest`, `parseMailerSendSequenceWebhookPayload`, `MAILERSEND_BOUNCE_EVENT_TYPES`) | Vollständiger Bounce-Webhook-Handler: Signatur→Parse Event-Type (bounced/hard/soft/rejected/spam_complaint)→`providerMessageId`-Lookup→`markDeliveryBounced` | **als-vorlage** — exaktes Pattern für Spec Block G Bounce-Verarbeitung; Ziel-Update muss auf `OutboundEmail` + Hard/Soft-Klassifikation + Suppression-Auto-Add + Soft-to-Hard-Conversion + Complaint→Auto-Unsubscribe + Activity gehen |
| `packages/mail/src/{index,types,mailersend,queue}.ts` (`MailProvider`-Interface, `SendMailInput` mit `listUnsubscribe`, `precedenceBulk`, `settings.trackOpens/Clicks`, `priorityOverride`, `sendAt`, `idempotencyKey`, `tenantId`, `tags`; `createQueuedMailProvider` = BullMQ-Versand mit Prioritäts-Resolver) | Provider-Abstraktion + Queue-Provider. `SendMailInput` deckt List-Unsubscribe-Header, Bulk-Precedence, Tracking-Settings, geplanten Versand (`sendAt`), Idempotenz, Tenant-Priorität bereits ab | **anpassen** — `MailProvider`-Interface 1:1 als LP-11-Adapter-Schicht; **EU-Provider-Adapter (LP-13) neu implementieren** (heute nur `mailersend` + `queue`); `QueuedMailProvider` ist Basis für den Spec-E-Versand-Worker mit Drossel |
| `packages/email-templates/src/{render,theme}.ts` + `components/{Layout,primitives}.tsx` + `sequences/*.tsx` | React-Email-Render (`renderEmail`→`{html,text}`, `htmlToPlainText` mit Anchor-URL-Erhaltung), Layout/Primitives, Sequenz-Templates (welcome/trial-reminder/re-activation/generic-step) | **als-vorlage** — Render-Pipeline + `htmlToPlainText` 1:1; SHK-Branchen-Templates („Wartungs-Erinnerung", „Newsletter Q4", „Service-Aktion", Spec Block I / 10.1.4) sind neu zu erstellen; das spezifizierte `EmailTemplate`-DB-Modell fehlt komplett |
| `packages/mail/src/templates-react/_layout/{Footer,BaseLayout,Button}.tsx` (`assertSafeUrl`, `InvalidActionUrlError`) | Mail-Footer-Layout + URL-Safety-Guard für Action-Links | **als-vorlage** — Basis für Pflicht-Footer (Spec G/10.7.5: Impressum-Adresse + Unsubscribe-Link auto-injiziert + Tracking-Pixel-Hinweis); Footer-Pflicht-Inhalt + Auto-Injection-Logik fehlen |
| `apps/web/app/utils/api/.server/EntityViewsApi` + `CrmService` (`getContactsInRowIds`, `getContact`, `marketingSubscriber`-Boolean, ContactDto firstName/lastName/email/jobTitle/company) | CRM-Entity-Views als Empfänger-Quelle (gefilterte Kontakt-Listen mit pageSize, Row-IDs) + Kontakt-Auflösung + Marketing-Subscriber-Flag | **als-vorlage** — Brücke CRM↔Marketing; Basis für M101-Segmente, aber das spezifizierte `RecipientSegment` (JSONB-Filter-Tree AND/OR, static/dynamic, Auto-Exclusion-Aufschlüsselung, 50-Sample-Vorschau) ist neu zu bauen |
| `packages/marketing-outbound/**` (Adapter-Registry slack/discord/mailchimp/hubspot/brevo/webhook, `resolveAdapter`, `adapterFetch` mit SSRF-Schutz/Timeout) + `apps/worker/src/jobs/marketing-outbound.ts` | Outbound-Integrations-Adapter + isolierter Dispatch-Worker (Outbox-getriggert, Idempotenz, per-Integration-Fehlerisolation) | **als-vorlage** für das LP-11-Adapter-Muster (SMTP-Provider als austauschbarer Adapter) + Worker-Job-Struktur. **Inhaltlich themenfremd** (CRM-Sync zu Drittanbietern, nicht Email-Versand) — nur Pattern/SSRF-Client nachnutzen |
| `packages/email-sequences/src/{engine,step-runner,conditions}.ts` + `apps/worker/src/jobs/email-sequence-{trigger,scheduler,runtime,prisma-store}.ts` | Drip-Sequence-Engine (start/advance Run, delayHours-Scheduling, Conditions-DSL, BullMQ-Step-Scheduler, Prisma-Store-Adapter, Idempotenz `@@unique([sequenceId,triggerEventId])`) | **als-vorlage** — relevant für Spec Block J Trigger-Mails über M17 + (Phase 2) Sequenzen; das injizierbare Store/Queue-Engine-Pattern (testbar) ist HiveGrid-DoD-kompatibel und als Architektur-Vorbild für den Kampagnen-Versand-Worker nutzbar |
| `packages/entitlements/src/features.ts` (`featureKeys.emailMarketing = "email-marketing"`) + `requireTenantProductAccess` | Produkt-/Feature-Gate für Email-Marketing | **anpassen** — Feature-Flag-fähig (DoD M006) vorhanden; um HiveGrid-Permissions `email_marketing.read/write/admin` (M004, Spec Block L) erweitern |
| `apps/web/public/locales/{de,en}/emailMarketing.json` | i18n-Keys für das gesamte Email-Marketing-UI (DE+EN) | **anpassen** — Basis-Wortschatz vorhanden; HiveGrid-i18n-Namespace + Klartext-Texte (Spec „Klartext-Hinweise"-Querschnitt, M002/M003) ergänzen |
| `apps/web/app/modules/emailMarketing/routes/emailMarketingAccess.server.ts` + `email-marketing-auth-boundary.test.ts` | Mutation-Access-Gate (`requireSuperUserOrAdmin` bei Tenant-Scope) + Auth-Boundary-Test | **anpassen** — auf HiveGrid-Permission-Bundles (`email_marketing.write`/`.admin`) umstellen; Test-Pattern für Permission-Denied→404 (DoD §25) nachnutzen |
---
## Vorhandene Daten-Modelle
> Pfad: `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/`
**Direkt M10-relevant (`email.prisma`):**
- `Campaign` — `email.prisma:72` — `tenantId?`, `emailSenderId`, `name`, `subject`, `htmlBody`, `textBody?`, `status` (default "draft", Freitext-String — nicht das Spec-Enum draft/scheduled/sending/sent/paused/failed/cancelled), `track`, `sentAt?`, Relation `recipients OutboundEmail[]`. **Fehlt:** preheader, template_id, recipient_segment_id, recipient_list_snapshot, scheduled_at, sending_started/finished_at, total_recipients, alle *_count-Aggregate, archived_at, created_by_user_id, Spec-Indizes.
- `OutboundEmail` — `email.prisma:88` — `tenantId?`, `campaignId?`, `contactRowId?` (FK auf `Row`), `email`, `fromSenderId`, `isPreview?`, `error?`, `sentAt?`/`deliveredAt?`/`bouncedAt?`/`spamComplainedAt?`/`unsubscribedAt?`, Relations `opens`/`clicks`. **Fehlt:** recipient_email-Snapshot-Semantik (vorhanden als `email`), recipient_first/last_name-Snapshot, personalization_payload (JSONB), delivery_status-Enum, provider_message_id, bounce_type/bounce_reason_text, tracking_token + unsubscribe_token (unique), Spec-Indizes.
- `OutboundEmailOpen` — `email.prisma:111` — `outboundEmailId`, `firstOpen`, `createdAt`. **Fehlt:** reader_ip (anonymisiert), reader_user_agent, tenantId, `opened_at`-Semantik (= createdAt).
- `OutboundEmailClick` — `email.prisma:119` — `outboundEmailId`, `link`, `createdAt`. **Fehlt:** link_label, reader_ip/user_agent, tenantId.
- `EmailSender` — `email.prisma:58` — `tenantId?`, `provider`, `stream`, `apiKey`, `fromEmail`, `fromName?`, `replyToEmail?`, Relations `campaigns`/`outboundEmails`. **Fehlt:** sending_domain_id (M9-FK), is_default, archived_at, created_at. Hält `apiKey` direkt am Sender (→ DKIM/Domain-Gate fehlt).
**Verwandt, aber paralleles operator-seitiges System (`emailSequences.prisma` / `marketingLeads.prisma`):**
- `EmailSequence`, `EmailSequenceRun`, `EmailSequenceStepDelivery` — `emailSequences.prisma` — Drip-Funnel mit `triggerEvent`, `stepsJson` (linear), Run-State, Step-Delivery mit sentAt/openedAt/clickedAt/bouncedAt/providerMessageId. **Wichtig:** Die öffentlichen Tracking-/Unsubscribe-Routen hängen an DIESEN Modellen, nicht an `OutboundEmail`. Status-Enum kennt `unsubscribed` (terminal).
- `Lead`, `LeadEvent`, `TenantAcquisition`, `MarketingIntegration` — `marketingLeads.prisma` — Marketing-Lead-Funnel (operator-org, nicht tenant-scoped) + Outbound-Integrations-Config. **Themenfremd für M10** (CRM-Lead-Akquise / Drittanbieter-Sync), nicht der Tenant-Newsletter-Versand.
**Inbound-Email (themenfremd, M9):** `Email`, `EmailRead`, `EmailCc`, `EmailAttachment`, `TenantInboundAddress` — `email.prisma:1–56`.
---
## Lücken / komplett neu zu bauen
**Datenmodelle (4 Spec-Modelle existieren NICHT — per Grep verifiziert):**
1. `Unsubscribe` (Spec Block H) — Pro Contact+Tenant dauerhaft, scope-Enum (all_marketing/specific/global), unsubscribed_via, email_address-Snapshot, reason. Heute nur Flag `OutboundEmail.unsubscribedAt`.
2. `EmailSuppressionList` (Spec Block G/H) — Tenant-weite Sperrliste (hard_bounce/complaint/manual/invalid_format), CRM-Lösch-persistent (10.5.5), `(tenant_id, email_address)` unique. **Existiert nicht.**
3. `RecipientSegment` (Spec Block A/D) — JSONB-Filter-Tree (verschachteltes AND/OR), entity_type, is_static_snapshot + static_recipient_ids[], archived_at. **Existiert nicht** (heute nur CRM-Entity-Views als Ad-hoc-Quelle).
4. `EmailTemplate` (Spec Block A/I) — Wiederverwendbare Vorlagen mit subject/preheader-Default, body_html/text, is_template_origin, archived_at. **Existiert nicht** (nur hardcodierte React-Sequenz-Templates).
**Opt-In-Dokumentation (Spec Block H 10.7):** `marketing_opt_in_at/_source/_reference/_text_snapshot` am Contact + Double-Opt-In-Flow (Bestätigungs-Mail + 7-Tage-Token). Heute nur CRM-Boolean `marketingSubscriber`. **Neu.**
**Versand-Engine-Robustheit (Spec Block E/K):**
- Geplanter Versand (`scheduled` + Cron `WHERE status=scheduled AND scheduled_at<=NOW()` jede Minute) — **fehlt**.
- BullMQ-Versand-Worker für Kampagnen mit Batch (1.000) + Retry (3× exp. Backoff) — **fehlt** (heute synchron `mapWithConcurrency(5)`).
- Throttling: 100 Mails/Min/Tenant, 30 Mails/Min/Empfänger-Domain — **fehlt**.
- Daily-Cap pro Plan (Cloud 10K / Cloud+ 50K / Trial 200, via SubscriptionFeature) + Auto-Pause + Resume 00:00 Tenant-Zeit — **fehlt**.
- Frequenz-Cap (max 5 Mails/Empfänger/Woche, tenant-konfigurierbar) + Auto-Exclusion-Reason — **fehlt**.
- Pause/Cancel-Lebenszyklus (paused re-aktivierbar, cancelled final) — **fehlt** (Status ist Freitext-String).
**Anti-Spam (Spec Block K):** Spam-Score-Check 0–10 (Großschrift/Ausrufezeichen/Phrasen/Bild-Text-Verhältnis) mit Block-Option ab >7 — **fehlt komplett**.
**Auto-Exclusion-Engine (Spec Block D):** beim Segment-Auflösen Ausschluss von Unsubscribe/Suppression/ohne-Email/archiviert/ohne-Opt-In + Aufschlüsselung „X aus Y ausgeschlossen (pro Grund)" — **fehlt**.
**Pflicht-Validierungen vor Versand (Spec Block C/L):** Sending-Domain-DKIM-grün-Gate (M9), Unsubscribe-Link-Auto-Injection, Impressum-Adress-Erkennung, Empfänger>0-nach-Exclusion, Daily-Cap-Check, Bestätigungs-Modal mit Pflicht-Check-Anzeige — **fehlt**.
**6-Schritt-Kampagnen-Wizard + Mobile/Desktop-Vorschau + Custom-Field-Token (`{{custom.x}}`)** — Editor existiert nur als einstufiges Formular; Wizard/Vorschau/Custom-Token **neu**.
**Bounce-Klassifikation + Auto-Folgeaktionen (Spec Block G):** Hard/Soft-Klassifikation (5.x.x/4.x.x), Soft-to-Hard nach 3 Versuchen, Hard→Suppression-Add + `Contact.email_invalid_at` + Activity, Complaint→Auto-Unsubscribe — Webhook-Empfang-Pattern existiert, **Domain-Folgeaktionen fehlen**.
**Stats-Vollausbau (Spec Block F):** CTR (Klick/Öffnung), Hard/Soft-Bounce-Raten, Unsubscribe-/Complaint-Raten, Click-Map (URL→Anzahl), Status-Filter, Aktivitäts-Detail pro Empfänger (Opens/Clicks chronologisch) — Summary/Tabelle existieren teilweise, Rest **neu**.
**Trigger-Mail-Action `send-marketing-email` (Spec Block J, M17):** Mini-Kampagne (1 Empfänger, sofort) aus Automation-Engine + Template/Sender/Empfänger-Resolution + Auto-Exclusion + System-Actor — **neu** (Sequence-Engine ist Vorbild).
**Querschnitt-Wiring (HiveGrid-DoD):** Activity-Stream-Typen (`marketing_email_sent/opened/clicked/bounced/unsubscribed/complained` via `logActivity`), Aggregat „Marketing-Engagement" am Contact, `notify()`-Integration, View-Model-Layer (`packages/view-models`), `ui-hivegrid`/Subframe-Adapter-Re-Layering, `sidebar.config.ts`-Eintrag (Gruppe „Kommunikation"), HiveGrid-Permissions (`email_marketing.*`), Search-Index — **alles neu zu verdrahten** (bestehender Code folgt ToolCTRL-, nicht HiveGrid-Layer-Konvention).
**EU-SMTP-Provider (LP-13):** MailerSend ist kein EU-Anbieter → Scaleway-TEM-/Brevo-EU-/Mailjet-EU-Adapter über das vorhandene `MailProvider`-Interface **neu implementieren** (offener Spec-Punkt).
**M9-Sending-Domain-Verknüpfung:** `EmailSender.sending_domain_id` FK auf `TenantSendingDomain` + DKIM-Status-Anzeige + Sender-Auto-Deaktivierung bei Domain-Widerruf — **fehlt** (M9 existiert noch nicht).
---
## Empfohlenes Vorgehen
**Phase 0 — Re-Layering-Entscheidung + Schema-Erweiterung (Fundament):**
1. Bestehende `email.prisma`-Modelle in eine HiveGrid-Migration übernehmen und **härten**: `Campaign.status`→Spec-Enum, `tenantId` NOT-NULL/RLS, Spec-Felder (preheader, scheduled_at, *_count, recipient_list_snapshot, archived_at, created_by_user_id, tracking_token/unsubscribe_token unique) + Indizes ergänzen. Forward-Only-Migration mit Inverse-SQL (DoD §28).
2. **Vier fehlende Modelle neu anlegen:** `Unsubscribe`, `EmailSuppressionList`, `RecipientSegment`, `EmailTemplate` (Spec Block A). Opt-In-Felder am Contact ergänzen.
3. Provider-Schicht: `MailProvider`-Interface aus `packages/mail` 1:1 übernehmen, EU-SMTP-Adapter (LP-13) als neuen Adapter daneben (Scaleway TEM evaluieren — offener Spec-Punkt vor Bau klären).
**Phase 1 — M100 Editor (höchster 1:1-Reuse):**
4. `EmailMarketingService` + `campaigns.db.server` + `EmailSenderForm`/Sender-Routes + i18n + Feature-Flag **als Vorlage** in HiveGrid-Layer (`app/domain` + `packages/view-models` + `ui-hivegrid`/Subframe-Adapter) re-layern. Permissions `email_marketing.*` + Sidebar-Eintrag „Kommunikation" verdrahten.
5. `replaceVariables` übernehmen, Token auf `{{first_name}}` + `{{custom.x}}` angleichen; `EmailTemplate`-CRUD + SHK-Branchen-Templates (aus `email-templates`-Render-Pipeline) neu.
6. 6-Schritt-Wizard + Mobile/Desktop-Vorschau + Test-Mail (vorhandenes `sendCampaignTest` als Basis) + Spam-Score-Check neu.
**Phase 2 — M101 Segmente:**
7. `RecipientSegment` mit JSONB-Filter-Tree neu bauen; `EntityViewsApi`/`CrmService` als CRM-Auflösungs-Brücke nachnutzen; Static/Dynamic + Auto-Exclusion-Engine + 50-Sample-Vorschau + Aufschlüsselung neu.
**Phase 3 — M102 Versand-Engine (Architektur-Kern):**
8. `QueuedMailProvider` + `email-sequences`-Engine-Pattern (injizierbarer Store/Queue) als Vorbild für einen **BullMQ-Kampagnen-Versand-Worker** mit Batch/Retry/Throttle (M007-Idempotenz). Cron für geplanten Versand. Daily-Cap (SubscriptionFeature) + Frequenz-Cap + Pause/Cancel-Lebenszyklus + Pflicht-Footer-Auto-Injection (`Footer.tsx`-Basis) + Pflicht-Validierungen + DKIM-Gate (M9) neu.
**Phase 4 — M104 Unsubscribe + Bounce (starke Vorlagen):**
9. Token-Mechanik (`unsubscribe-token.ts`) + Pixel-/Click-Routen + `unsubscribe.$token.tsx` + `mailersend-signature.ts` + `provider-webhook-route.ts` **als Vorlagen** auf `OutboundEmail`/`Unsubscribe`/`EmailSuppressionList` umverdrahten. Bounce-Klassifikation + Suppression-Auto-Add + Complaint→Auto-Unsubscribe + Activity-Wiring + Grund/Feedback-Formular neu.
**Phase 5 — M103 Reporting (+ A/B Phase 2):**
10. `getSummary`/`OutboundEmailsTable`/`EmailMarketingSummaryRoute` ausbauen: CTR, Bounce/Unsub/Complaint-Raten, Click-Map, Pro-Empfänger-Aktivitäts-Detail, Status-Filter. A/B-Tests sind Phase 2 (Spec 10.3/10.11.1).
**Querschnitt (durchgängig):** Activity-Stream (`logActivity` + Marketing-Engagement-Aggregat am Contact), `notify()`, Audit (auto M001), Klartext-Catalog (M002), View-Model-Unit-Tests + Smoke-Tests + Hot-Swap-Drill + Visual-Regression (DoD D).
**Trigger-Mails (Spec J):** koordiniert mit M17 — `send-marketing-email`-Action auf Mini-Kampagnen-Pfad (1 Empfänger, sofort) aufsetzen; Sequence-Engine als Architektur-Vorbild.