148 lines
26 KiB
Markdown
148 lines
26 KiB
Markdown
# 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.
|