91 lines
12 KiB
Markdown
91 lines
12 KiB
Markdown
# 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ührt `crm.prisma` nur für die `related_kontakt/projekt_id`-Relation und schreibt in den `Activity`-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 → `Activity` am 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_data` auf 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.prisma` nur für `related_kontakt/projekt_id`-Relation berühren (AD-21).
|
||
- **Activity-Write**: BCC-Logging + Inbound erzeugen `Activity` (polymorph `subject_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_data` auf 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-view`
|
||
- `ROADMAP.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): neu `TenantSendingDomain` (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`/`relatedProjektId` als bare Scalars — FK erst R-P6). RLS: 3 neue Modelle in `TENANT_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 in `handlers.ts` + Registrierung `index.ts`, Payload-Literal in `queue/payloads.ts`): 5-Min-Cron, DKIM/SPF/DMARC-Lookup (injizierbarer Resolver), Status `pending→verifying→verified|failed`, 7-Tage-Klartext-Key, `notify` bei 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` (`anonymizeTrackingIp` sha256/trunc, `safeRedirectTarget` Open-Redirect-Schutz, `recordEmailOpen`/`recordEmailClick`) + öffentliche Routes `e.o.$outboundEmailId` (1×1-GIF) / `e.c.$outboundEmailId` (302-Redirect). `ipHash` additiv 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:** Modul `email-marketing` existiert bereits inkl. Shell `app.$tenant/email-marketing.tsx` (Gate `requireTenantProductAccess(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/email` ist Davids UI-Entscheidung (Dev-Nachzug).
|
||
- **S8 (revidiert)** — Konnektor/Sidebar **existiert bereits** über `featureKeys.emailMarketing` ("email-marketing"); **kein** Eingriff in `@hivegrid/entitlements` nötig (Ticket-`tenantHasModule('email')` = das vorhandene `email-marketing`-Feature). Offen: tenant-seitige Permissions `email.domain.view`/`.manage` in 4 Registries (`DefaultPermissions.ts`, `permissions-seed.server.ts` Array+Rollen-Map, `roleDisplay.ts` scope→`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) + Route `app.$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 gated `email-marketing`-Modul.
|
||
- **S8** Permissions `email.domain.view/.manage` in 4 Registries (DefaultPermissions, permissions-seed Array+Rollen-Map, roleDisplay scope `emailDomain`, i18n en/de) + Domain-Screen-i18n (en/de). Konnektor = vorhandenes Feature `email-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)
|
||
- [x] 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**
|
||
- [x] Email-Tracking + Open/Click (IP anon) + Bounce → Suppression — ✅ (S3+S4; Delivery-Status via Send-Pfad = AK-P14b)
|
||
- [x] SMTP-Provider-Abstraktion (Mailjet, AD-6) — ✅ (S5)
|
||
- [x] Konnektor `tenantHasModule` (Sidebar/Routes/Actions gated) — ✅ (S8, Feature `email-marketing` + email.domain-Permissions)
|
||
- [x] RLS auf allen neuen Tenant-Tabellen; `is_demo_data` auf 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-P14a` aktualisiert
|