Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/AK-P14a.md
T

17 KiB
Raw Blame History

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 Plane: Done · 7/7 Ticket-DoD = 100 % (Code-Audit 2026-07-17 bestätigt) · offen als AGENTS-Pflicht-Nachzug: Interim-Visual-Baseline (D21) · design-nachzug: finale Subframe-Optik (D-P14/D-KAMP)

🎨 design-nachzug: offen (seit 2026-07-09) — Interim-UI aus ~/ui steht; finale Subframe-Optik aus D-P14/D-KAMP ausstehend.

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.

UX-Nachzug (2026-07-25): R-UX2 übernimmt den freigegebenen Setup-, Kampagnen-, Segment-, Versand- und Reporting-Nachzug. AK-P14a bleibt das technische Sende-/Tracking-Fundament und wird nicht historisch umgedeutet.

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

Stand 2026-07-17: alle 7 Punkte per Code-Audit gegen main verifiziert (Proof-Pfade in der Audit-Notiz unten). Checkliste an den realen Stand angeglichen.

  • 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 · Milestones: (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)

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)

  • 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); Mailjet-Inbound → Email + Kontakt/1-offenes-Projekt-Match + Activity(email_sent) ✅
  • Tenant-Inbound → Lead/Activity — Mailjet-Inbound → Email; bei Kontakt-Match Activity(email_received), sonst InboxLead + Lead-Activity ✅
  • 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, Feature email-marketing + email.domain-Permissions)
  • RLS auf allen neuen Tenant-Tabellen; is_demo_data auf seedbaren Sendern/Templates — ✅ (S1, RLS deferred-cutover-Artefakt wie hr)

2026-07-09 — Interim-UI + Suppression-Verwaltung (AD-28)

Interim-Screens aus ~/ui nachgezogen: Sende-Domain-Route nutzt jetzt SendingDomainPage mit VM als Prop und Submit-Callbacks; Sender-Screen zeigt Sender/Webhook-Status plus Suppression-Liste und manuelle Suppression-Aktion. Public Opt-in/Unsubscribe nutzen denselben Interim-Result-Screen. Subframe geprüft: kein P14/D-KAMP-Screen vorhanden, daher AD-28-Interim statt finaler Subframe-Optik.

Proof: pnpm typecheck grün; pnpm lint grün; JSON-Parse en/de grün; pnpm --filter @hivegrid/view-models test -- --runInBand grün; gezielte Web-Tests emailMarketing + unsubscribe.$token + unsubscribeToken grün. Breites pnpm test bleibt auf Windows rot durch bestehende/unabhängige Guards (URLSearchParams-Undici, Symlink-EPERM, Decision-Report-Drift), nicht durch P14.

Stand: 5/7 DoD voll + 2 partiell ≈ ~71 % done. Selbst-machbar offen: e2e-Smoke/Visual-Baseline gegen laufenden Stack. Extern blockiert: BCC/Inbound→Activity (R-P6/R-P7), finale Subframe-UI (Davids D-P14/D-KAMP-Delta).

2026-07-09 — Blocker-Recheck

R-P6/R-P7 erneut geprüft: Kontakt-, Lead- und Activity-Code stehen inzwischen im Repo. Damit ist BCC/Inbound→Activity nicht mehr extern durch die Kern-Kette blockiert, sondern ein selbst machbarer Nachzug in AK-P14a. Finale Subframe-Optik bleibt weiter design-nachzug über D-P14/D-KAMP.

Stand: 5/7 DoD voll + 2 partiell ≈ ~71 % done. Selbst-machbar offen: BCC-Logging-Mail→Activity, Tenant-Inbound→Lead/Activity, e2e-Smoke/Visual-Baseline gegen laufenden Stack. Extern blockiert: finale Subframe-UI (Davids D-P14/D-KAMP-Delta).

2026-07-09 — Mailjet Tenant-Inbound für BCC + Lead-Inbox

Selbst machbarer Nachzug umgesetzt: neuer DB-Service ingestTenantInboundEmail resolved TenantInboundAddress für lead_inbox/bcc_logging, dedupliziert über Email.messageId, persistiert Email tenant-scoped und matched über KontaktEmail. Bei exakt einem offenen ProjektKontakt wird relatedProjektId gesetzt. bcc_logging schreibt Activity(email_sent) am Kontakt; lead_inbox schreibt bei Kontakt-Match Activity(email_received), sonst einen InboxLead plus Lead-Activity. Neue API-Route POST /v1/email/inbound-mailjet nutzt die bestehende Mailjet-Basic-Auth und den erweiterten Inbound-Payload-Parser; OpenAPI, CSRF- und Route-Access-Inventar sind nachgezogen.

Proof: pnpm exec vitest run packages/db/src/email-inbound.server.test.ts apps/api/src/app.test.ts apps/api/src/openapi.test.ts apps/api/src/route-access-inventory.test.ts apps/api/src/route-access-inventory-doc.test.ts apps/api/src/csrf-inventory.test.ts grün (150 Tests); pnpm --filter @hivegrid/api typecheck grün; pnpm --filter @hivegrid/db typecheck grün; pnpm lint grün.

Stand: 7/7 Ticket-DoD = 100 % done. Selbst-machbar global offen: e2e-Smoke/Visual-Baseline gegen laufenden Stack. Extern blockiert: finale Subframe-UI (Davids D-P14/D-KAMP-Delta). Plane-Status daher noch nicht auf Done gesetzt, bis Smoke/Visual bzw. PR-Gates geklärt sind.

2026-07-17 — Stand-Audit (Code vs. Plane vs. Doc) + Doc-Reconciliation

Vollständiges Code-Audit gegen main (Branch fix/ak-p14-audit-restwork): alle 7 Ticket-DoD-Punkte real erfüllt — Proofs: prisma/schema/email.prisma (TenantSendingDomain inkl. Soft-Delete/Envelope-Key), apps/worker/src/jobs/email-domain-probe-cron.ts (5-Min-Cron, 7-Tage-Klartext, notify() in handlers.ts), packages/db/src/email-inbound.server.ts (BCC→Activity(email_sent), Inbound→InboxLead+Lead-Activity, messageId-Dedupe, 1-offenes-Projekt-Match), packages/db/src/email-tracking.server.ts + Routen e.o./e.c.$outboundEmailId, packages/db/src/email-suppression.server.ts + Wiring apps/api/src/email-sequences/provider-webhook-route.ts, packages/mail/src/mailjet-dns.ts, Feature-Gate + email.domain.*-Permissions in allen 4 Registries, TENANT_SCOPED_MODELS + prisma/rls/email-isolation.sql + Migration 20260629120000_p14a_email_foundation.

Befunde/Korrekturen: (1) Der Doc-Header stand noch auf „geplant" und die DoD-Kästchen leer, obwohl Plane seit 2026-07-09/15 Done meldet — angeglichen. (2) Die im Plane-Kommentar vom 2026-07-15 referenzierten Restarbeiten-Artefakte lagen nur auf einem lokalen, nie gepushten Branch (feat/restarbeiten-initiative); die Doc-Reconciliation wurde hier frisch neu erstellt (nichts von dort übernommen). (3) Doku-Nit: apps/api/src/webhooks/mailjet-suppression.ts ist ein reiner Payload-Parser — der Suppression-Upsert läuft über den bestehenden Sequence-Webhook (funktional vollständig). (4) Modul-e2e-Smoke (tests/e2e/email-marketing-smoke.spec.ts) neu gebaut, deckt Overview→Kampagnen; ein Sende-Domain-spezifischer Smoke wäre Scope-Erweiterung (nicht gebaut). Offen als AGENTS-Pflicht-DoD-Nachzug (in Ticket-DoD nie erfasst): Interim-Visual-Baseline (D21, braucht laufenden Stack), Hot-Swap-Drill-Beleg (D20).

Stand: 7/7 Ticket-DoD = 100 % done. Extern: finale Subframe-Optik (design-nachzug, D-P14/D-KAMP).

Dev-Nachzug (nach Davids D-KAMP/D-P14-Delta)

  • Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
  • REQUIREMENTS/ROADMAP nachgezogen
  • Plane-Ticket AK-P14a aktualisiert