12 KiB
AK-P14a · P14 Sende-Domain-Verifikation + BCC-Brücke + Tracking
| Typ | Dev (Code) |
| Owner | Akeshan |
| Phase | P14 — Email & Marketing |
| Cycle/Fenster | W3 — Kern-Kette & Kommunikation (Demo 2) · fällig 2026-06-28 · Gate W3 |
| Status | geplant |
Abhängigkeiten & Parallelität
- Blocked by:
EXT-02(Mailjet Sende-Domain SPF/DKIM/DMARC + Warm-up),R-P6(CRM-Kern — Mails/Activity hängen am Kontakt) - Blocks:
AK-P14b(Marketing setzt verifizierte Domain + Tracking-Infra voraus) - Läuft parallel zu: Raffaels Kern-Kette (P7/P8 Lead/Projekt). Schema-isoliert über eigene
prisma/schema/email.prisma(AD-21); berührtcrm.prismanur für dierelated_kontakt/projekt_id-Relation und schreibt in denActivity-Stream (R-P6). Sync-Punkt: R-P6 (Activity am Kontakt) muss stehen, bevor BCC-Logging andocken kann. - Konflikt-Risiko: gering — additive Tabellen + polymorpher Activity-Write; keine Änderung am CRM-Schema.
Was wir bauen
Das v1-Fundament der Email-Welt (Postfach-Sync ist v2 → P23): pro Mandant eine eigene Sende-Domain mit DKIM/SPF/DMARC-Records, Copy-Buttons, 5-Min-Auto-Probe und Status-Ampel (pending/verifying/verified/failed) inkl. Klartext-Fehler nach 7 Tagen. Dazu die BCC-Logging-Brücke (crm@<tenant>… als BCC → in Gmail/Outlook geschriebene Mails erscheinen als Activity am Kontakt, kein OAuth), eine Tenant-Inbound-Adresse (eingehende Mails → Lead/Activity) und das Email-Tracking (Delivery-Status, Open/Click, Bounce-Handling mit Suppression-Eintrag). Versand läuft über Mailjet (AD-6, SMTP-Provider-Abstraktion ohne US-Kern-Abhängigkeit). Ohne verifizierte Domain kein Marketing-Versand (Gate für AK-P14b).
Benötigte Screens (Backend bedient — Design liefert D-KAMP + D-P14)
| Screen [Route] | Kern-Inhalt |
|---|---|
Sende-Domain [/settings/integrations/email] |
Domain-Eingabe, DNS-Record-Karten (DKIM/SPF/DMARC) mit Copy, Status-Ampel + 5-Min-Prüf-Indikator + 7-Tage-Klartext-Fehler, BCC-Logging-Toggle + angezeigte BCC-Adresse + Klartext „Mails erscheinen am Kontakt" |
Sender + Suppression [/email-marketing/senders] |
Sender (From-Name/-Email, Domain-DKIM-Status, Default-Marker) · Suppression-Liste (Adresse, Grund Bounce/Beschwerde/manuell) |
Definition of Done
- Sende-Domain pro Mandant: DKIM/SPF/DMARC-Records mit Copy, 5-Min-Auto-Probe, Status-Ampel, Klartext-Fehler nach 7 Tagen
- BCC-Logging-Brücke: Toggle + Anzeige der BCC-Adresse; in nativen Clients geschriebene Mails →
Activityam Kontakt (kein OAuth) - Tenant-Inbound-Adresse: eingehende Mails → Lead/Activity
- Email-Tracking + Delivery-Status + Open/Click (IP anonymisiert) + Bounce-Handling → Suppression-Eintrag
- SMTP-Provider-Abstraktion (Mailjet, AD-6) ohne US-Kern-Abhängigkeit
- Konnektor
tenantHasModule('email')(Sidebar + Routes + Actions gated) - RLS auf allen Tenant-Tabellen;
is_demo_dataauf seedbaren Sendern/Templates
Technische Bausteine
- Entities (eigene
prisma/schema/email.prisma):TenantSendingDomain(DKIM/SPF/DMARC-Records, verification_status — [verschlüsselt][Soft-Delete]),TenantInboundAddress(local_part, purpose lead_inbox/bcc_logging/reply_routing),Email(purpose, from_sender_id, delivery_status, related_kontakt/projekt_id),EmailSender/EmailTemplate(is_default),EmailSuppressionList(email_address unique, reason).crm.prismanur fürrelated_kontakt/projekt_id-Relation berühren (AD-21). - Activity-Write: BCC-Logging + Inbound erzeugen
Activity(polymorphsubject_type/id,actor_kind=system) im Stream aus R-P6. - RLS auf allen Tabellen außer keine; OAuth/Provider-Credentials über per-Tenant-DEK verschlüsselt (AD-8).
- Auto-Probe als BullMQ-Scheduled-Job (DNS-Lookup DKIM/SPF/DMARC), Status-Übergänge in Klartext.
- Inbound-/Bounce-Webhooks (Mailjet) → Signatur-Check → Lead/Activity bzw. Suppression.
- Konnektor
tenantHasModule('email');is_demo_dataauf Demo-Sendern/-Templates.
Quellen (granular)
ENTITY-MODEL.md→ Domäne 8: Kommunikation (TenantSendingDomain, TenantInboundAddress, Email, EmailSender/Template, EmailSuppressionList)REQUIREMENTS.md→REQ-email-datenmodell(v1-Teil: Sende-Domain + Inbound),REQ-marketing-versand(SMTP-Abstraktion Mailjet) · v2-Cut:REQ-email-sync-strategie/REQ-email-inbox-viewROADMAP.md→ Phase 14 ·PHASE-SOURCES.md→ Phase 14 (M099-email-tracking-bounces; Sende-Domain aus M096 herausgelöst, v1-Pflicht; BCC-Brücke neu)designer-briefs/P14-email-marketing.md(Sende-Domain-Card, BCC-Toggle, Suppression)_bmad-output/specs/M09-email-inbox.md(nur Sende-Domain/Inbound/BCC — Rest v2)
Umsetzung (Akeshan)
2026-06-29 — Backend-Fundament (S1–S5), ~45 % DoD
Branch feat/AK-P14a (noch nicht gepusht). Strategie laut Plan: Backend-Fundament jetzt, Kontakt-abhängige Verdrahtung + finale Subframe-UI zurückgestellt (R-P6/R-P7/David offen).
Gebaut + verifiziert (alle Typechecks grün, 35 neue Unit-Tests grün):
- S1 Schema (
prisma/schema/email.prisma, additiv,prisma db push-bereit, keine Migration): neuTenantSendingDomain(RLS, DKIM-Privatkey als per-Tenant-Envelope-Ciphertext AD-8, Soft-Delete,verificationStatus,firstProbeAt/lastProbedAt,mailjetDnsId),EmailSuppressionList(@@unique([tenantId,emailAddress]),reason),EmailTemplate(isDefault/isDemoData). Erweitert:TenantInboundAddress(purpose/localPart/fullAddress/enabled),EmailSender(isDefault/isDemoData/sendingDomainId),Email(purpose/deliveryStatus/relatedKontaktId/relatedProjektIdals bare Scalars — FK erst R-P6). RLS: 3 neue Modelle inTENANT_SCOPED_MODELS+prisma/rls/email-isolation.sql(deferred-cutover wie hr).prisma validate+ Registry-Test grün. - S2 DNS-Auto-Probe (
apps/worker/src/jobs/email-domain-probe-cron.ts+ Handler inhandlers.ts+ Registrierungindex.ts, Payload-Literal inqueue/payloads.ts): 5-Min-Cron, DKIM/SPF/DMARC-Lookup (injizierbarer Resolver), Statuspending→verifying→verified|failed, 7-Tage-Klartext-Key,notifybei verified/failed, Write auto-auditiert (M001). 9 Unit-Tests. - S3 Bounce/Complaint → Suppression:
packages/db/src/email-suppression.server.ts(idempotenter Upsert +isEmailSuppressed-Pre-Send-Guard) +apps/api/src/webhooks/mailjet-suppression.ts(reiner Signal-Parser, Tenant via Mailjet-Payload/CustomID), additiv in den bestehenden Mailjet-Webhook gehängt (optionaler Dep → keine Regression). 13 Unit-Tests. - S4 Tracking-Endpoints:
packages/db/src/email-tracking.server.ts(anonymizeTrackingIpsha256/trunc,safeRedirectTargetOpen-Redirect-Schutz,recordEmailOpen/recordEmailClick) + öffentliche Routese.o.$outboundEmailId(1×1-GIF) /e.c.$outboundEmailId(302-Redirect).ipHashadditiv auf Open/Click-Modellen. 8 Unit-Tests. - S5 Provider-Abstraktion:
packages/mail/src/mailjet-dns.ts(createMailjetDnsProvisioner: registerDomain/getRecords/check via Mailjet/v3/REST, Basic-Auth, injizierbarer fetch, AD-6, kein US-Kern). 5 Unit-Tests.
Teilweise (S6) / offen:
- S6 (angefangen) —
buildSendingDomainVM(packages/view-models/src/email/sending-domain.vm.ts, 5 Tests grün) ✅. Offen: Domain-Service (emailDomainService.server.ts, wiret S1+S5+withTenantRLS), reachable Route + Plain-UI + i18n + Smoke. Befund: Modulemail-marketingexistiert bereits inkl. Shellapp.$tenant/email-marketing.tsx(GaterequireTenantProductAccess(featureKeys.emailMarketing)) + Sidebar-Eintrag (AppSidebar.tsx,hasFeatureAccess("email-marketing")) +email-marketing/senders.tsx. → Sende-Domain kommt als gated Tab in dieses Modul; finale Route/settings/integrations/emailist Davids UI-Entscheidung (Dev-Nachzug). - S8 (revidiert) — Konnektor/Sidebar existiert bereits über
featureKeys.emailMarketing("email-marketing"); kein Eingriff in@hivegrid/entitlementsnötig (Ticket-tenantHasModule('email')= das vorhandeneemail-marketing-Feature). Offen: tenant-seitige Permissionsemail.domain.view/.managein 4 Registries (DefaultPermissions.ts,permissions-seed.server.tsArray+Rollen-Map,roleDisplay.tsscope→emailDomain, i18n scopes/actions inkl.manage) + i18n-Parität (4 Locales, roleDisplay-Test + verify:i18n als Gates). - S7 BCC-/Inbound→Activity-am-Kontakt + Lead-Anlage — blockiert R-P6 (
Kontakt) / R-P7 (tenant-Lead); Empfang/Persistenz machbar, Kontakt-Resolver-Write bleibt markierter Stub.
2026-06-29 (Update) — S6 + S8 umgesetzt
- S6
emailDomainService.server.ts(Context+Permission-Gate 404, getSendingDomainState, createSendingDomain via Mailjet-Provisioner S5, setBccLogging, pure normalizeDomainInput/bccAddressFor) + Routeapp.$tenant/email-marketing/sending-domain.tsx(Loader→VM, Actions create-domain/toggle-bcc) + Plain-UI (DNS-Karten+Copy, Status-Ampel, 7-Tage-Klartext, BCC-Toggle, Empty-State, data-ui-id) + Tab im Modul-Shell. Reachable über das gatedemail-marketing-Modul. - S8 Permissions
email.domain.view/.managein 4 Registries (DefaultPermissions, permissions-seed Array+Rollen-Map, roleDisplay scopeemailDomain, i18n en/de) + Domain-Screen-i18n (en/de). Konnektor = vorhandenes Featureemail-marketing(kein entitlements-Eingriff). roleDisplay-Test (7) + verify:i18n grün, web/db typecheck grün.
2026-06-29 (Merge) — main in Branch + Email-Phasen-Migration (AD-21)
main in feat/AK-P14a gemergt (R-P6 typisierte Kontakte, R-P6B/C, AD-2-Präzisierung). Einzige Konflikte im generierten Prisma-Client → via pnpm db:generate aus dem gemergten Schema neu erzeugt (enthält beide Seiten). Kein neuer Entity-Builder-Bezug (AD-2 + Raffaels R-P14C-Ownership eingehalten).
Der CI-Docker-Smoke (migrate deploy gegen leere DB + Seed) schlug fehl (P2022: TenantInboundAddress.createdAt does not exist) — die Email-Schema-Änderungen lagen per AD-21 nur als db push vor, ohne Migration. Migration 20260629120000_p14a_email_foundation erzeugt (AD-21 „beim Merge"): schema-zu-schema-Diff (merge-base vs. Branch), auf das Email-Delta getrimmt (3 Enums + 3 neue Tabellen + Spalten auf TenantInboundAddress/Email/EmailSender/OutboundEmail* + Indizes), Forward-only mit Inverse-SQL-Kommentar (DoD 28), RLS deferred (Artefakt prisma/rls/email-isolation.sql, Muster wie AK-P4a/hr). Verifiziert: migrate deploy auf frischer DB grün, Seed läuft komplett durch (rolesAndPermissions + entitlements success), prisma validate grün.
DoD-Stand (aktualisiert)
- Sende-Domain DKIM/SPF/DMARC + 5-Min-Probe + Ampel + 7-Tage-Klartext — Backend (S1+S2) + reachable Plain-UI (S6) ✅ (Subframe-Politur = Dev-Nachzug nach David)
- [~] BCC-Logging-Brücke — Toggle + BCC-Adresse-UI ✅ (S6); Mail→Activity-am-Kontakt blockiert R-P6
- [~] Tenant-Inbound → Lead/Activity — Schema ✅; Verdrahtung blockiert R-P6/R-P7
- Email-Tracking + Open/Click (IP anon) + Bounce → Suppression — ✅ (S3+S4; Delivery-Status via Send-Pfad = AK-P14b)
- SMTP-Provider-Abstraktion (Mailjet, AD-6) — ✅ (S5)
- Konnektor
tenantHasModule(Sidebar/Routes/Actions gated) — ✅ (S8, Featureemail-marketing+ email.domain-Permissions) - RLS auf allen neuen Tenant-Tabellen;
is_demo_dataauf seedbaren Sendern/Templates — ✅ (S1, RLS deferred-cutover-Artefakt wie hr)
Stand: 5/7 DoD voll + 2 partiell ≈ ~71 % done. Selbst-machbar offen (klein): Suppression-Listen-UI im Senders-Screen, e2e-Smoke (braucht laufende Stack+Seed). Extern blockiert: BCC/Inbound→Activity (S7, R-P6/R-P7), finale Subframe-UI (Davids D-P14/D-KAMP-Delta).
Dev-Nachzug (nach Davids D-KAMP/D-P14-Delta)
- Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
- REQUIREMENTS/PHASE-SOURCES nachgezogen
- Plane-Ticket
AK-P14aaktualisiert