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-29 · Gate W3 |
|
||||
| **Status** | geplant |
|
||||
| **Status** | Plane: Done · funktional + Interim-UI fertig (AD-28) · Stand 2026-07-17: 6/7 DoD voll + 1 partiell ≈ ~86 % (tz-Versand-Lücke aus Audit gefixt, e2e-Smoke neu) · design-nachzug: Rich-Text-Editor/Vorschau (D-KAMP) · extern: Lead/Projekt-Segment-Dim (R-P7/R-P8-Folge) · offen: Interim-Visual-Baseline (D21) |
|
||||
|
||||
**🎨 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:** `AK-P14a` (verifizierte Sende-Domain + Tracking-Infra + Suppression)
|
||||
@@ -14,6 +16,10 @@
|
||||
- **Läuft parallel zu:** Raffaels Kern-Kette. Eigene `prisma/schema/email.prisma` (gleicher Namespace wie AK-P14a, additive Tabellen — AD-21); Segmente lesen CRM-Kontakte read-only (R-P6). **Sync-Punkt:** R-P6 (Kontakt/Tag/Custom-Feld) muss stehen, damit Segment-Filter auflösen.
|
||||
- **Konflikt-Risiko:** keines auf Schema-Ebene; CRM nur lesend.
|
||||
|
||||
**UX-Nachzug (2026-07-25):** `R-UX2` übernimmt den freigegebenen Produkt-/UX-Nachzug für Setup,
|
||||
Segmente, Kampagnen-Wizard, Versand und Reporting. AK-P14b bleibt das technische Fundament; die
|
||||
typisierte Ablösung nach AD-2 und bestehende Versandverträge sind zu erhalten.
|
||||
|
||||
## Was wir bauen
|
||||
Das **vollständige DSGVO-konforme Email-Marketing** (bleibt VOLL inkl. A/B): ein mehrstufiger **Kampagnen-Builder** (Basis → Inhalt mit Rich-Text/HTML-Toggle + Personalisierungs-Tokens inkl. Custom-Felder + Pflicht-Footer-Auto-Injektion + Desktop-/Mobile-Vorschau → Empfänger → Test-Versand → Zeitpunkt → Bestätigung mit Klartext-Checkliste), **Segmente** mit verschachteltem AND/OR-Filter-Baum und Auto-Exclusion, **Double-Opt-In**, **One-Click-Unsubscribe** + List-Unsubscribe-Header, eine **BullMQ-Versand-Engine** mit Rate-Limiting/Throttling/geplantem (timezone-aware) Versand, **Reporting** (Open/Click/Bounce/Abmeldung, Klick-Map) und **A/B-Varianten**. Versand wird bei rotem Pflicht-Check (Domain/Unsubscribe/Impressum) **blockiert**.
|
||||
|
||||
@@ -27,13 +33,14 @@ Das **vollständige DSGVO-konforme Email-Marketing** (bleibt VOLL inkl. A/B): ei
|
||||
| 🌐 Unsubscribe-Page [`/unsubscribe/{token}`] | Bestätigungs-Button, optionale Grund-Auswahl, Erfolgs-Meldung, Tenant-Branding |
|
||||
|
||||
## Definition of Done
|
||||
- [ ] **Block-/Rich-Text-Editor** + Personalisierungs-Tokens (auch Custom-Felder) + Pflicht-Footer-Auto-Injektion + Desktop-/Mobile-Vorschau
|
||||
- [ ] **Segmente**: verschachtelter AND/OR-Filter-Baum, Live-Auflösung, Auto-Exclusion (Unsubscribe/Suppression/kein Opt-In/archiviert/keine Email), dynamisch vs. statischer Snapshot
|
||||
- [ ] **Versand-Engine** (BullMQ, Rate-Limit, Throttling, geplanter timezone-aware Versand)
|
||||
- [ ] **Double-Opt-In** (aus Form-Submissions) + **Suppression-Check vor jedem Versand** + **One-Click-Unsubscribe** + List-Unsubscribe-Header
|
||||
- [ ] **Pflicht-Checkliste** vor Versand (Domain verifiziert / Unsubscribe / Impressum / Subject / >0 Empfänger / Daily-Cap) — Block + Fix-Link bei rotem Check
|
||||
- [ ] **Reporting** (Open/Click/Bounce/Abmeldung in %, Klick-Map, Pro-Empfänger) + **A/B-Varianten**
|
||||
- [ ] Konnektor `tenantHasModule('email')`; RLS auf allen Tenant-Tabellen; `is_demo_data` auf Demo-Kampagnen/-Segmenten/-Templates
|
||||
> Stand 2026-07-17: Checkliste per Code-Audit gegen `main` an den realen Stand angeglichen (Proofs in der Audit-Notiz unten). Die Versand-Engine war zuvor fälschlich als voll abgehakt gemeldet — der timezone-aware Versand fehlte real und wurde jetzt gefixt.
|
||||
- [ ] **Block-/Rich-Text-Editor** + Personalisierungs-Tokens (auch Custom-Felder) + Pflicht-Footer-Auto-Injektion + Desktop-/Mobile-Vorschau — *teilweise: Token-/Footer-Logik ✅ (pure, getestet), AD-28-Interim-Editor steht; Rich-Text-Toggle + Desktop-/Mobile-Vorschau = design-nachzug (David `D-KAMP`)*
|
||||
- [x] **Segmente**: verschachtelter AND/OR-Filter-Baum, Live-Auflösung, Auto-Exclusion (Unsubscribe/Suppression/kein Opt-In/archiviert/keine Email), dynamisch vs. statischer Snapshot — *Kontakt-Dimensionen ✅; Lead/Projekt-Dimension extern (R-P7/R-P8-Folge)*
|
||||
- [x] **Versand-Engine** (BullMQ, Rate-Limit, Throttling, geplanter timezone-aware Versand) — *tz-Auflösung 2026-07-17 nachgezogen (`campaignSchedule.ts`, Audit-Befund)*
|
||||
- [x] **Double-Opt-In** (aus Form-Submissions) + **Suppression-Check vor jedem Versand** + **One-Click-Unsubscribe** + List-Unsubscribe-Header
|
||||
- [x] **Pflicht-Checkliste** vor Versand (Domain verifiziert / Unsubscribe / Impressum / Subject / >0 Empfänger / Daily-Cap) — Block + Fix-Link bei rotem Check — *Logik + harter Server-Gate ✅; finale Optik = design-nachzug*
|
||||
- [x] **Reporting** (Open/Click/Bounce/Abmeldung in %, Klick-Map, Pro-Empfänger) + **A/B-Varianten** — *VMs + A/B-Schema/-Versand ✅; finale Optik = design-nachzug*
|
||||
- [x] Konnektor `tenantHasModule('email')`; RLS auf allen Tenant-Tabellen; `is_demo_data` auf Demo-Kampagnen/-Segmenten/-Templates
|
||||
|
||||
## Technische Bausteine
|
||||
- **Entities** (eigene `prisma/schema/email.prisma`): `Campaign` (subject, template_id, sender_id, recipient_segment_id, status, delivered/opened/clicked_count), `OutboundEmail` (campaign_id, recipient_kontakt_id, tracking_token, unsubscribe_token, delivery_status), `OutboundEmailOpen`/`Click`, `RecipientSegment` (entity_type, filter_definition JSONB, is_static_snapshot), `Unsubscribe` (kontakt_id, scope, reason). `crm.prisma` nur lesend (Kontakt/Tag/CustomFieldValue).
|
||||
@@ -45,9 +52,8 @@ Das **vollständige DSGVO-konforme Email-Marketing** (bleibt VOLL inkl. A/B): ei
|
||||
## Quellen (granular)
|
||||
- `ENTITY-MODEL.md` → **Domäne 8: Kommunikation** (Campaign, OutboundEmail +Open/Click, RecipientSegment, Unsubscribe)
|
||||
- `REQUIREMENTS.md` → `REQ-marketing-datenmodell`, `REQ-marketing-double-optin`, `REQ-marketing-versand`
|
||||
- `ROADMAP.md` → Phase 14 · `PHASE-SOURCES.md` → Phase 14 (M100-editor, M101-segmente, M102-versand-engine, M103-ab-tests-reporting, M104-unsubscribe-bounces — Marketing bleibt VOLL inkl. A/B)
|
||||
- `ROADMAP.md` → Phase 14 · Milestones: (M100-editor, M101-segmente, M102-versand-engine, M103-ab-tests-reporting, M104-unsubscribe-bounces — Marketing bleibt VOLL inkl. A/B)
|
||||
- `designer-briefs/P14-email-marketing.md` (Kampagnen-Editor BESPOKE, Segmente, Unsubscribe-Page)
|
||||
- `_bmad-output/specs/M10-email-marketing.md`
|
||||
|
||||
## Umsetzung (Akeshan)
|
||||
|
||||
@@ -109,7 +115,34 @@ Unsubscribe-Page-Branding (Davids `D-KAMP`/`D-P14`-Delta), Lead/Projekt-Segmentd
|
||||
(braucht Stack+Seed) + Visual-Regression (braucht finale UI), Form-Widget→Opt-In-Auto-Trigger. Selbst-machbar
|
||||
offen: Form-Widget-Trigger verdrahten (klein). **Nicht** anfassen: Alt-Pfad-Migration (R-P14C, Raffael).
|
||||
|
||||
### 2026-07-09 — Interim-UI + Campaign-Routen (AD-28)
|
||||
Interim-Screens aus `~/ui` nachgezogen: Kampagnenliste (`/email-marketing/campaigns`), Draft-Editor (`/campaigns/new`), Kampagnen-Detail/Reporting mit Pre-Send-Checkliste und Send-Action (`/campaigns/:id`), Templates-Liste, Segmente-Screen als `SegmentsPage`, Public Opt-in/Unsubscribe-Result-Screen. Backend ergänzt: Draft-Erstellung auf typisiertem `Campaign`, Detail-Aggregation über `CampaignDetailVM`, Checklisten-Anzeige, Send-Action auf `dispatchCampaign`, Suppression-Verwaltung aus AK-P14a. 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.
|
||||
|
||||
### 2026-07-09 — Campaign-Route-Fix + Form-Submission Double-Opt-in
|
||||
Nachzug auf dem Interim-Stand: Parent-Route `/email-marketing/campaigns` ist jetzt reine Layout-Route mit `Outlet`; die Liste liegt unter `campaigns/index.tsx`, damit `/campaigns/new` und `/campaigns/:id` wirklich rendern. Draft-Save validiert Sender und Segment tenant-scoped vor `Campaign.create` und zeigt einen Klartext-Fehler bei ungültiger Auswahl.
|
||||
|
||||
Form-Widget-Post-Submit-Actions um `start_double_opt_in` erweitert: Builder-Auswahl, Save-Parser, Prisma-Enum, Worker-Runner, `FormActionLog`, Consent-Upsert und bestehende `mail.transactional.send`-Outbox. Der Runner resolved Kontakt per `kontaktId` oder E-Mail/Telefon aus dem Field-Mapping, schreibt `KontaktMarketingConsent(single)` mit Opt-in-Token und queued die Bestätigungs-Mail auf `/optin/{token}`. Die Marketing-Token-HMAC-Logik liegt jetzt in `@hivegrid/foundation/marketing-token`, Web re-exportiert den bisherigen Server-Helper weiter.
|
||||
|
||||
**Proof:** `pnpm --filter @hivegrid/web typecheck` grün; `pnpm --filter @hivegrid/worker typecheck` grün; `pnpm lint` grün; `pnpm exec vitest run apps/worker/src/jobs/form-submission-actions.test.ts apps/worker/src/jobs/form-submission-route.test.ts 'apps/web/app/routes/app.$tenant/forms.$id.action.test.ts'` grün (23 Tests); `pnpm exec vitest run apps/web/app/utils/email/marketingToken.test.ts` grün (5 Tests). `pnpm --filter @hivegrid/foundation typecheck` bleibt rot durch bestehende Test-Typfehler in `outbound-http.test.ts`/`permissions.test.ts`, nicht durch `marketing-token.ts`.
|
||||
|
||||
**Stand: 6/7 DoD voll + 1 partiell ≈ ~86 % done.** Selbst-machbar offen: e2e-Smoke/Visual-Baseline gegen laufenden Stack. Extern blockiert: finale Subframe-Optik (Davids `D-P14`/`D-KAMP`-Delta) und Lead/Projekt-Segmentdimension, soweit Folge-Tickets sie produktisieren.
|
||||
|
||||
### 2026-07-17 — Stand-Audit + Restarbeiten (Branch `fix/ak-p14-audit-restwork`)
|
||||
Vollständiges Code-Audit gegen `main`. Kern bestätigt: Segmente (`segmentFilter.ts` + `SegmentService.server.ts`, 5-fach-Auto-Exclusion, Snapshot), Versand (`campaignSendPlan.ts` d'Hondt-A/B + Throttle, `CampaignSendService.server.ts` harter Checklisten-Gate + Suppression-Re-Check + List-Unsubscribe), DOI/Unsubscribe (`ConsentService.server.ts`, RFC-8058, Form-Action `start_double_opt_in`), Reporting-VMs, Gating/RLS/Migrationen (`20260703150000_ak_schema_parity_catchup` + `20260709213000_ak_p14_form_action_double_opt_in`).
|
||||
|
||||
**Audit-Befund + Fix:** Der „timezone-aware Versand" war nur nominell — `scheduledAt` wurde per `new Date()` in Server-Lokalzeit geparst, `campaign.timezone` gespeichert aber nie benutzt (`CampaignSendService.server.ts` nutzte `scheduledAt.getTime()` direkt). Gefixt: neues pures `apps/web/app/utils/integrations/email/campaignSchedule.ts` (`parseScheduledAt` via `date-fns-tz`/`fromZonedTime`, explizite Offsets bleiben, invalide Zone/Datum → Klartext-Fehler `emailMarketing.campaign.editor.error.invalidSchedule` de/en), verdrahtet im Draft-Save (`campaigns/new.tsx`). 6 neue Unit-Tests (Berlin vs. New York, Sommer/Winter, Offset, invalid).
|
||||
|
||||
**Test-Nachzug (D18):** `ConsentService.server.test.ts` neu (7 Tests: Opt-in-Upsert, Confirm-Idempotenz, Public-Status-Mapping, Unsubscribe-Idempotenz). VM-Tests existierten bereits (`email-marketing.vm.test.ts` deckt presend-checklist/campaign-detail/campaign-list/segment), personalization ist in `campaignSendPlan.test.ts` abgedeckt — frühere „fehlt"-Meldung war zu pessimistisch. **e2e-Smoke (D19):** `tests/e2e/email-marketing-smoke.spec.ts` neu gebaut (Login → Overview → Kampagnen-Liste, skippt sauber ohne Credentials/Entitlement). Hinweis: Die im Plane-Kommentar vom 2026-07-15 genannten Restarbeiten-Artefakte lagen nur auf einem lokalen, ungepushten Branch — alles hier wurde frisch neu erstellt.
|
||||
|
||||
**Proof:** `node scripts/vitest-cli-compat.mjs run campaignSchedule.test.ts` (6) grün · `ConsentService.server.test.ts` (7) grün · `pnpm --filter @hivegrid/web typecheck` exit 0 · `pnpm run verify:i18n` exit 0 · `playwright --list` sammelt den Smoke · eslint grün. Commits: `b79e960bf` (tz-Fix), `f4d019b80` (Consent-Tests), `f16a7e290` (Smoke).
|
||||
|
||||
**Staging-Live-Check (2026-07-17, `staging-app.hivegrid.de/demo-pro-crm`):** Overview, Kampagnen-Liste (Empty-State), Sendedomain (Empty-State + Domain-Eingabe) und Segmente (Filter-JSON + Snapshot-Checkbox) rendern live. Befund dabei: Die Overview-Kacheln „Gesendet"/„Zugestellt" zeigten bei Wert 0 gar nichts an — `StatsCard` rendert `{value ? …}`, numerische 0 ist falsy. Gefixt per String-Übergabe im Interim-Screen (kein Eingriff in `~/ui`). Nit notiert (nicht gefixt, Breadcrumb-Thema für Design-Nachzug): Breadcrumb zeigt auf `/campaigns` „Dashboard" und auf `/segments` „E-Mail-Marketing" statt des Screen-Titels.
|
||||
|
||||
**Stand: 6/7 DoD voll + 1 partiell ≈ ~86 % done.** Design-nachzug: Rich-Text-Editor + Vorschau (David `D-KAMP`). Extern: Lead/Projekt-Segment-Dimension (R-P7/R-P8-Folge). Offen als AGENTS-Pflicht-DoD-Nachzug (nie in Ticket-DoD erfasst): Interim-Visual-Baseline (D21, braucht laufenden Stack), Hot-Swap-Drill-Beleg (D20).
|
||||
|
||||
## 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-P14b` aktualisiert
|
||||
Reference in new issue
Block a user