Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
1 parent
5e99e14772
commit
7f88026f79
5955 files changed
+1177325
-188362
No files matched your search
@@ -6,7 +6,9 @@
|
||||
| **Owner** | Akeshan |
|
||||
| **Phase** | P14 — Email & Marketing |
|
||||
| **Cycle/Fenster** | W3 — Kern-Kette & Kommunikation (Demo 2) · fällig 2026-06-28 · Gate W3 |
|
||||
| **Status** | geplant |
|
||||
| **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)
|
||||
@@ -14,6 +16,10 @@
|
||||
- **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).
|
||||
|
||||
@@ -24,13 +30,14 @@ Das **v1-Fundament der Email-Welt** (Postfach-Sync ist v2 → P23): pro Mandant
|
||||
| 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
|
||||
> 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).
|
||||
@@ -43,9 +50,8 @@ Das **v1-Fundament der Email-Welt** (Postfach-Sync ist v2 → P23): pro Mandant
|
||||
## 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)
|
||||
- `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)
|
||||
- `_bmad-output/specs/M09-email-inbox.md` (nur Sende-Domain/Inbound/BCC — Rest v2)
|
||||
|
||||
## Umsetzung (Akeshan)
|
||||
|
||||
@@ -75,16 +81,40 @@ Der CI-Docker-Smoke (`migrate deploy` gegen leere DB + Seed) schlug fehl (`P2022
|
||||
|
||||
### 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] 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)
|
||||
|
||||
**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).
|
||||
### 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/PHASE-SOURCES nachgezogen
|
||||
- [ ] REQUIREMENTS/ROADMAP nachgezogen
|
||||
- [ ] Plane-Ticket `AK-P14a` aktualisiert
|
||||
Reference in new issue
Block a user