26 KiB
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:
- Vier zentrale Spec-Modelle fehlen komplett:
Unsubscribe,EmailSuppressionList,RecipientSegment,EmailTemplate. Verifiziert per Grep über alle*.prisma: kein Treffer. Unsubscribe lebt heute nur alsOutboundEmail.unsubscribedAt-Flag bzw.EmailSequenceRun.status='unsubscribed'— keine tenant-weite, CRM-Lösch-persistente Sperrliste (Spec Block H/G + 10.5.5). - 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 aufOutboundEmail. Für M10 muss Tracking/Unsubscribe aufCampaign/OutboundEmailumverdrahtet bzw. neu gebaut werden (die HMAC-Token-Mechanik + Pixel-Route sind aber 1:1-Vorlagen). - 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). - DSGVO-Opt-In-Dokumentation fehlt: kein
marketing_opt_in_at/_source/_reference/_text_snapshot(Spec Block H 10.7). Heute nur ein CRM-BooleanmarketingSubscriber(Custom-Field viaCrmService). - 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). - Keine M9-Sending-Domain-Verknüpfung:
EmailSenderhältapiKey/fromEmail/providerdirekt, kein FK aufTenantSendingDomain(existiert in M9 noch nicht). DKIM-Verifikations-Gate vor Versand fehlt. - 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 spezifizierteRecipientSegmentmit verschachteltem AND/OR-JSONB-Filter-Tree + Static-Snapshot + Auto-Exclusion-Aufschlüsselung ist neu. - Layer-Disziplin: Bestehender Code folgt dem ToolCTRL-Muster (Service direkt aus Route,
db.serverin Modul-Code), NICHT der HiveGrid-DoD (View-Model-Layerpackages/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?, Relationrecipients 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 aufRow),email,fromSenderId,isPreview?,error?,sentAt?/deliveredAt?/bouncedAt?/spamComplainedAt?/unsubscribedAt?, Relationsopens/clicks. Fehlt: recipient_email-Snapshot-Semantik (vorhanden alsemail), 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?, Relationscampaigns/outboundEmails. Fehlt: sending_domain_id (M9-FK), is_default, archived_at, created_at. HältapiKeydirekt am Sender (→ DKIM/Domain-Gate fehlt).
Verwandt, aber paralleles operator-seitiges System (emailSequences.prisma / marketingLeads.prisma):
EmailSequence,EmailSequenceRun,EmailSequenceStepDelivery—emailSequences.prisma— Drip-Funnel mittriggerEvent,stepsJson(linear), Run-State, Step-Delivery mit sentAt/openedAt/clickedAt/bouncedAt/providerMessageId. Wichtig: Die öffentlichen Tracking-/Unsubscribe-Routen hängen an DIESEN Modellen, nicht anOutboundEmail. Status-Enum kenntunsubscribed(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):
Unsubscribe(Spec Block H) — Pro Contact+Tenant dauerhaft, scope-Enum (all_marketing/specific/global), unsubscribed_via, email_address-Snapshot, reason. Heute nur FlagOutboundEmail.unsubscribedAt.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.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).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+ CronWHERE 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):
- Bestehende
email.prisma-Modelle in eine HiveGrid-Migration übernehmen und härten:Campaign.status→Spec-Enum,tenantIdNOT-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). - Vier fehlende Modelle neu anlegen:
Unsubscribe,EmailSuppressionList,RecipientSegment,EmailTemplate(Spec Block A). Opt-In-Felder am Contact ergänzen. - Provider-Schicht:
MailProvider-Interface auspackages/mail1: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.