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

26 KiB
Raw Blame History

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.