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

121 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.
- [x] Sende-Domain pro Mandant: DKIM/SPF/DMARC-Records mit Copy, **5-Min-Auto-Probe**, Status-Ampel, Klartext-Fehler nach 7 Tagen
- [x] **BCC-Logging-Brücke**: Toggle + Anzeige der BCC-Adresse; in nativen Clients geschriebene Mails → `Activity` am Kontakt (kein OAuth)
- [x] **Tenant-Inbound-Adresse**: eingehende Mails → Lead/Activity
- [x] **Email-Tracking** + Delivery-Status + Open/Click (IP anonymisiert) + Bounce-Handling → Suppression-Eintrag
- [x] SMTP-Provider-Abstraktion (Mailjet, AD-6) ohne US-Kern-Abhängigkeit
- [x] Konnektor `tenantHasModule('email')` (Sidebar + Routes + Actions gated)
- [x] 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)
- [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)
- [x] BCC-Logging-Brücke — Toggle + BCC-Adresse-UI ✅ (S6); Mailjet-Inbound → `Email` + Kontakt/1-offenes-Projekt-Match + `Activity(email_sent)` ✅
- [x] Tenant-Inbound → Lead/Activity — Mailjet-Inbound → `Email`; bei Kontakt-Match `Activity(email_received)`, sonst `InboxLead` + Lead-Activity ✅
- [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)
### 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