Files
HiveGrid-Wireframes/hivegrid-cloud/docs/boilerplate-mapping/M02-lead-inbox.md
T

113 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.
# Boilerplate-Abgleich: M02 — Lead-Inbox / Lead-Management
| Feld | Wert |
| --- | --- |
| Modul-ID | M02 (Modul 2) |
| Name | Lead-Inbox / Lead-Management |
| Milestones | M047 (Inbox + Quellen-Adapter), M048 (Routing pro Quelle), M049 (Auto-Verkaufsfall), M050 (Spam/Duplikat + DSGVO-Auto-Lösch), M051 (Status-Pipeline + Listen/Detail-UI + Statistik + Permissions) |
| Pflichtenheft-Block | Block 2, Modul 2 (Abschnitte 2.1–2.13) |
| **Reuse-Level** | **medium** |
## Kurz-Verdikt
Die Boilerplate enthält ein **vollständiges Marketing-/Funnel-Lead-System** (`Lead`/`LeadEvent`/`TenantAcquisition`/`MarketingIntegration` + Admin-Inbox-UI + Capture/Convert-Services + Outbound-Adapter). Das ist als **Vorlage / Muster** hochwertig, aber das Daten-Modell ist **bewusst operator-/marketing-scoped (NICHT tenant-scoped)** und mit `@@unique([email])` global eindeutig — das ist **inkompatibel** mit dem tenant-isolierten CRM-Lead-Inbox aus M02. Der HiveGrid-Lead muss daher ein **eigenes, tenant-scoped Modell** sein (gehört fachlich ohnehin zu Modul 1/CRM-Kern, das das `Lead`-Datenmodell besitzt). Solider, breiter Querschnitt (Form-Widget inkl. Honeypot, Outbox, Audit, Rate-Limiter, Export, Realtime, Apps-Engine-Schema) ist 1:1 nutzbar. Die eigentliche Inbox-Domänen-Logik (tenant-scoped Listen/Filter/Triage/Routing/Statistik) ist neu zu bauen, aber mit starken Vorlagen.
> Hinweis: `HiveGrid-Cloud` ist aktuell ein reines Spec-/Docs-Repo (`_bmad`, `_bmad-output`, `docs`, `prisma` leer). Es existiert noch **kein** `packages/ui-hivegrid`, kein `apps/*`, kein HiveGrid-Lead-Modell. Alle Boilerplate-Pfade unten beziehen sich auf `/Users/raffaelsheikh/Documents/GitHub/boilerplate`.
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
| --- | --- | --- |
| `prisma/schema/marketingLeads.prisma` (`Lead`, `LeadEvent`) | Lead-Datenmodell + Event-Timeline-Pattern (Status-Enum, Attribution, `lastIpHash` SHA-256, Indizes auf `(status, createdAt desc)` / `(source, createdAt desc)`) | **als-vorlage** — Felder/Indizes-Muster übernehmen, aber tenant-scoped neu modellieren (siehe Lücken) |
| `apps/web/app/utils/leads/leads.db.server.ts` | DB-Helper für Inbox: `listLeads` (Filter status/source/search + Pagination), `listLeadsForExport` (Cap 50k), `getLead`, `updateLeadStatus`, `appendNote`, CSV-Export-Row-Typ | **als-vorlage** — Loader/Action-Plumbing-Muster ist direkt adaptierbar; Queries um `tenantId`-Scope + Permission-Filter (read_own/read_all) erweitern |
| `apps/web/app/routes/admin/marketing-leads/index.tsx` | Inbox-Listen-Route: Status-Badges als Filter-Shortcuts, Such-Box, Pagination, CSV-Export mit Audit-Event, `groupBy`-Status-Counts | **als-vorlage** — Strukturmuster für Loader→VM→UI; HiveGrid braucht Tenant-Route (`/{tenant}/leads`), Multi-Select-Filter, Bulk-Actions, View-Model-Adapter, i18n-Keys, Subframe-UI |
| `apps/web/app/routes/admin/marketing-leads/$id.tsx` | Lead-Detail: Status-State-Machine-Buttons (forward/back), Inline-Notes-Editor, LeadEvent-Activity-Timeline, Konversions-Flow | **als-vorlage** — Triage-Detail-Muster; HiveGrid-Übergänge (new/qualified/converted/lost/spam) + Promotion-Modal (Modul 1) abweichend |
| `apps/web/app/utils/leads/captureLead.server.ts` | Idempotenter Lead-Upsert: Trim/Blank-Fill-Semantik, `hashIp()` (SHA-256, kein Raw-IP), First-Touch-Merge, Event-Append | **als-vorlage** — Auto-Anlage-Pfad (Form/Mail/Phone/Manuell). `hashIp` 1:1; Upsert-Logik tenant-scoped + Kontakt-Match-Probe ergänzen |
| `apps/web/app/utils/leads/convertLead.server.ts` | Atomare Konversion in `$transaction` (5 Effekte: Update + Event + Acquisition + Outbox), Idempotenz via `dispatchKey`, Up-front-Check | **als-vorlage** — Promotion Lead→Kontakt (Modul 1) folgt demselben Transaktions-/Idempotenz-Muster; Ziel ist Contact statt Tenant |
| `packages/form-widget/src/honeypot.ts` (`isHoneypotTriggered`, `HONEYPOT_FIELD_KEY`) | Honeypot-Spam-Erkennung (stilles 204) | **1:1** — direkt für Anti-Spam-Heuristik „Honeypot gefüllt" (Spec 2.8.4) |
| `packages/form-widget/src/schema.ts` / `origin.ts` / `routing.ts` | Form-Definition-Zod-Schema, Origin-Allowlist, Submission-Routing (`generic`/`crm-contact`/`entity-row`) + Field-Mapping | **anpassen** — Quelle Form→Lead (2.2.1); Routing-Target um „Lead-Inbox" + Field-Mapping pro Routing-Regel (M048/M049) erweitern |
| `prisma/schema/formWidget.prisma` (`Form`, `FormSubmission`) | Eingebettetes Formular + Submission-Inbox (`payload` JSON, `ipHash`, `status` received/processed/failed/spam, `config` Anti-Spam) | **anpassen** — Form-Submission ist Hauptquelle für Leads; `status=spam` koppelt an Spam-Heuristik. Form-Builder selbst = Modul 5 (M121-M125) |
| `packages/shared-store/src/helpers/rate-limit-fixed.ts` + `rate-limit-sliding.ts` | `createFixedWindowRateLimiter` / `createSlidingWindowRateLimiter` (Redis/Memory) | **1:1** — Hard-Limit pro Quelle/h (Default 100) und pro IP/h (Default 20) aus Spec 2.8.1/2.8.2 |
| `apps/worker/src/jobs/audit-retention.ts` | Täglicher Cron mit injizierten Seams (`tenantLister`/`eventDeleter`/`auditWriter`), Retention-Schwelle, meta-auditiertes Löschen | **als-vorlage** — DSGVO-Auto-Lösch-Job (Spam→30 Tage, Lost→90 Tage konfigurierbar, Spec 2.7); selbes Cron-+Seam-+Meta-Audit-Muster |
| `apps/worker/src/jobs/dsgvo-grace-cron.ts` + `outbox-done-retention-cron.ts` | Weitere Retention-/Grace-Cron-Muster | **als-vorlage** — Referenz für Auto-Lösch-Implementierung + Anonymisierungs-Trail (Spec 2.7.4) |
| `apps/web/app/utils/leads/leadsCsv.ts` (`serializeLeadsCsv`, `leadsCsvFilename`) + `packages/exports` | CSV-Serialisierung + Streaming-Export-Framework (CSV/JSON/XLSX/PDF, Plan-Row-Caps, Spreadsheet-Injection-Schutz) | **1:1 / anpassen** — Export gefilterter Auswahl + Statistik-Export (Spec 2.3.5/2.9.6, Permission `leads.admin`) |
| `packages/marketing-outbound` (`adapterRegistry`, `resolveAdapter`, slack/discord/mailchimp/hubspot/brevo/webhook) | Outbound-Adapter-Registry, dispatched via Outbox-Events | **als-vorlage** — Muster für Apps-Engine-Quellen-Adapter (2.2.5) und Routing-Notifications; HiveGrid braucht **inbound** Lead-Adapter (Meta/Google/Funnel), nicht outbound |
| `packages/realtime/src/{client,events,server,guards}.ts` | Realtime-Pub/Sub (WebSocket) | **1:1** — Live-Aktualisierung neuer Leads in der Inbox (Spec 2.3.7 / M047 „Real-Time-Updates via packages/realtime") |
| `packages/db/src/outbox.ts` (`publishOutboxEvent`, `OUTBOX_EVENT_TYPE_PATTERN`) | Transaktionales Outbox-Pattern (`<domain>.<entity>.<verb>`, `dispatchKey @unique`) | **1:1** — `lead.created`-Event als Automation-Trigger (Spec Block I / Modul 17), Routing-Aktionen, Side-Effects |
| `packages/db/src/audit-hash.ts` + `prisma/schema/core.prisma` (`AuditEvent`) | Tamper-evidente Audit-Hash-Kette, `dataSensitivity`/`regulatoryScope[]` | **1:1** — Audit-Trail für Status-/Verantwortlichen-Wechsel, Bulk-Action, Hard-Delete (AV #6, Spec 2.11.5) |
| `prisma/schema/appsEngine.prisma` (`App`, `DataConnection`, `AppSyncRun`, `AppSyncItem`) | Integrations-/Sync-Engine mit verschlüsselten Credentials + rollback-fähigen Sync-Runs | **als-vorlage** — Quellen-Adapter aus externen Marketing-Tools (Spec 2.2.5, M047 „Quellen-Adapter via Apps-Engine M008"). Modelle vorhanden, aber kein Service-/UI-Layer in `apps/web/app/modules` gefunden |
| `prisma/schema/permissions.prisma` (`Role`, `Permission`, `RolePermission`, `UserRole`, `Group`, `GroupUser`) + `apps/web/app/utils/helpers/.server/PermissionsService` (`verifyUserHasPermission`) | RBAC-Fundament + Permission-Check-Helper | **1:1 / anpassen** — Permission-Bundle `leads.*` (read_own/read_all/write/delete/admin) als Daten seeden; `verifyUserHasPermission`-Muster für Route-Gates. Owner-Check-Filter (read_own) selbst zu bauen |
| `prisma/schema/notifications.prisma` + `packages/db` notifications-Modul | `NotificationDelivery`/`UserNotificationPreference`/`DeviceToken` (In-App/Email/Push) | **1:1** — Tenant-Admin-Alerts bei Anomalie/Auto-Pause/Hard-Limit (Spec 2.8.3, Block K) via `notify()` (M011) |
| `packages/db/src/dsgvo/{user-fk-map.ts, pseudonymize.ts}` | DSGVO-FK-Karte (CI-erzwungen) + Pseudonymisierungs-Helfer | **1:1** — Pflicht-Eintrag für jeden neuen User-FK am HiveGrid-Lead; Anonymisierung vor Hard-Delete (Spec 2.7.4) |
| `prisma/schema/imports.prisma` + `packages/imports` | Import-Job + Dry-Run/Dedupe-Framework | **als-vorlage** — nur für Phase 2 (CSV/JSON-Lead-Import, Spec 2.12.1) — in Phase 1 explizit Out-of-Scope |
---
## Vorhandene Daten-Modelle
Konkret in `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/`:
- **`marketingLeads.prisma`** — `Lead`, `LeadEvent`, `TenantAcquisition`, `MarketingIntegration`, Enum `LeadStatus`.
- `Lead`: `email @@unique` (GLOBAL, nicht pro Tenant), **kein `tenantId`** (operator-scoped per Design-Kommentar), `status LeadStatus @default(new)`, First-Touch-UTM-Attribution, `score`, `notes Json?`, `convertedToTenantId?`, `lastIpHash` (SHA-256), Indizes `@@index([status, createdAt(sort:Desc)])`, `@@index([source, createdAt(sort:Desc)])`.
- Enum `LeadStatus`: `new | contacted | qualified | trial | customer | churned | disqualified` — **funnel-/SaaS-Akquise-Semantik**, NICHT die HiveGrid-CRM-Semantik (`new | qualified | converted | lost | spam`).
- `LeadEvent`: append-only Timeline (`type` String, `actorId?`, `payload Json`).
- **`formWidget.prisma`** — `Form`, `FormSubmission` (Quelle „Formular" für Leads; `ipHash`, `status` received/processed/failed/spam, Anti-Spam-`config`).
- **`appsEngine.prisma`** — `App`, `DataConnection`, `AppSyncRun`, `AppSyncRunLog`, `AppSyncItem` (externe Quellen-Adapter, Spec 2.2.5).
- **`permissions.prisma`** — `Role`, `Permission`, `RolePermission`, `UserRole`, `Group`, `GroupUser` (Bundle `leads.*` + Group für Round-Robin).
- **`notifications.prisma`** — `NotificationDelivery`, `UserNotificationPreference`, `DeviceToken` (Admin-Alerts).
- **`core.prisma`** — `AuditEvent` (Audit-Trail), `IdempotencyKey`.
- **`outbox.prisma`** — `OutboxEvent` (`lead.created`-Trigger, Side-Effects).
- **`accounts.prisma`** — `Tenant`, `User`, `TenantUser` (Tenant-Scope-Anker + Verantwortlicher-FK).
**Nicht vorhanden (kritisch):** Es gibt **kein tenant-scoped CRM-`Contact`/`Company`-Modell** in der Boilerplate. Das `crm`-Modul (`apps/web/app/modules/crm/`) enthält nur `services` (z.B. `CrmService.ts`, `crmContactSearch.server.ts`) — eine Integrations-Schicht zu EXTERNEN CRMs (ConvertKit etc.), kein eigener Contact-Datastore. Das Form-Widget-Routing-Target `crm-contact` upsertet entsprechend über diese externe Service-Schicht. Promotion Lead→Kontakt (Spec Block D/2.5) zielt auf das HiveGrid-eigene Contact-Modell aus **Modul 1 (M042-M046)** — das ebenfalls neu gebaut wird.
---
## Lücken / komplett neu zu bauen
1. **Tenant-scoped HiveGrid-Lead-Modell** — Der Boilerplate-`Lead` ist operator-scoped mit globalem `@@unique([email])`. HiveGrid braucht ein neues Modell (`tenantId` pflicht, FK auf `Tenant` mit `onDelete: Cascade`, `assigned_to_user_id`, Status-Enum `new/qualified/converted/lost/spam`, `source`, `message`, `metadata` JSON für Quellen-Detail). Geplanter Ort: `prisma/schema/app.prisma` (HiveGrid-Platzhalter). FK→User in `user-fk-map.ts` eintragen (CI-Pflicht). Indizes laut Spec: `(tenant_id, status, created_at desc)`, `(tenant_id, assigned_to_user_id, status)`, Trigram auf `email`/`phone`/`last_name`.
2. **Lead-Status-State-Machine (HiveGrid-Semantik)** — Übergangs-Matrix aus Spec Block F (inkl. `converted`-Lock, Re-Engagement `lost↔qualified`, False-Positive `spam→qualified`, Begründungs-Pflicht bei `lost`). Boilerplate-State-Machine (`new→…→customer/churned`) ist semantisch anders → neu.
3. **Permissions-aware Owner-Check-Filter (`read_own` vs `read_all`)** — Server-side-Filter, der nicht-eigene Leads in Listen/Statistik/Bulk ausblendet (AV #5). RBAC-Tabellen + `verifyUserHasPermission` vorhanden, aber der scope-bewusste Query-Filter + Bundle `leads.*`-Seed sind neu.
4. **Multi-Select-Filter + Bulk-Actions + gemischte-Rechte-Pre-Check** — Boilerplate-Inbox hat nur Single-Status-Filter + Such-Box, keine Bulk-Auswahl. Neu: Multi-Select (Status/Quelle/Verantwortlicher inkl. „Nicht zugewiesen"/Tags/Custom-Felder), Date-Range, Toggles „Spam ausblenden"/„Konvertierte einblenden", Bulk-Assign/Status/Tag/Spam/Hard-Delete/Export, Pre-Check mit Klartext-Übersprungen (Spec 2.10.1).
5. **Lead-Routing pro Quelle (M048)** — Routing-Regel-DSL mit Bedingungs-Kombinatoren, Reihenfolge-Auswertung (erste Treffer-Regel), Round-Robin-State pro Gruppe, Status/Verantwortlicher/Tags-Default. Komplett neu (Apps-Engine + Outbox als Fundament).
6. **Auto-Verkaufsfall-Anlage (M049)** — Routing-Action, die aus Lead automatisch Verkaufsfall in Ziel-Pipeline anlegt mit Field-Mapping. Abhängig von Sales-Pipeline (M059/M060) — neu.
7. **Anomalie-Detection + Auto-Pause pro Quelle (M050)** — 10x-Rate-Spike-Erkennung → Quelle pausieren + Notification. Rate-Limiter (fixed/sliding) als Baustein vorhanden, aber Anomalie-Heuristik + Quellen-Pause-State + Klartext-Notification neu (M010 Apps-Engine-Webhook-Schutz als Re-Use-Referenz).
8. **DSGVO-Auto-Lösch-Job mit Lead-Semantik** — Cron-Muster (`audit-retention.ts`) als Vorlage, aber Lead-spezifisch: Spam→30 Tage, Lost→90 Tage (tenant-konfigurierbar, 0=nie), anonymisierter Activity-Trail + Audit-Eintrag, Klartext-Hinweis „wird gelöscht am [Datum]".
9. **Lead-Statistik-Seite (M051 / Spec Block H)** — KPI-Kacheln (Konversionsraten, Reaktionszeit, Spam-Quote, offene Leads), Aufschlüsselungen (Quelle/Verantwortlicher/Tag/Wochentag), Trend-Charts, Vorperioden-Vergleich, Drill-Down. Aggregat via Materialized-View/Cron-Tabelle. Komplett neu — Boilerplate hat kein Lead-Statistik-Dashboard.
10. **Quellen-Verwaltung-UI** (`/admin/lead-sources`) + **Anti-Spam-Settings-UI** (`/admin/lead-anti-spam`) — Custom-Quellen (Name/Default-Verantwortlicher/Default-Tags), Hard-Limits-Toggles, Heuristik-Schalter. Neu.
11. **Kontakt-Match-Probe + Duplikat-/Soft-Match-Marker** — Inline-Match-Check beim Tippen (Spec 2.2.4), Marker „Mögliches Duplikat"/„Spam-Verdacht"/„Auto-promoviert" (2.3.2). Abhängig vom HiveGrid-Contact-Modell (Modul 1) — neu.
12. **App-Shell-Anbindung (HiveGrid)** — Sidebar-Eintrag „Lead-Inbox" in Gruppe ARBEITEN (INTEGRATION-CONTRACTS §1), Tenant-Routen `/{tenant}/leads*`, Breadcrumb, Mobile-Tab-Bar, View-Model-Konvention (M013), Subframe-Adapter (M015), i18n-Keys (M003). `packages/ui-hivegrid` existiert noch nicht; Boilerplate `packages/ui`/`ui-app`/`ui-subframe` sind Fundament/Vorlage.
13. **Gespeicherte Ansichten** (max. 5 Filter-Kombinationen pro User, Spec 2.3.8) + user-spezifische Spalten-Konfiguration — neu (Entity-Builder `EntityView` als konzeptionelle Vorlage, aber Lead ist eigenes Modell).
14. **Inbound-Quellen-Adapter (Meta/Google/Funnel)** — `packages/marketing-outbound` ist OUTBOUND. Für 2.2.5 braucht es INBOUND-Adapter über Apps-Engine — Registry-Muster übertragbar, Implementierungen neu.
---
## Empfohlenes Vorgehen
**Phase 0 — Fundament 1:1 übernehmen (kein neuer Code, nur verdrahten):**
1. Querschnitt aktivieren: `packages/db/src/outbox.ts`, `audit-hash.ts` + `AuditEvent`, `notifications`, `permissions` + `verifyUserHasPermission`, `realtime`, `shared-store` Rate-Limiter, `exports`/CSV. Diese stehen für alle 5 Milestones bereit.
2. `hashIp()` aus `captureLead.server.ts` und `isHoneypotTriggered` aus `form-widget` direkt einziehen.
**Phase 1 — Eigenes tenant-scoped Lead-Modell (M047):**
3. HiveGrid-`Lead`-Modell in `prisma/schema/app.prisma` neu definieren (NICHT den marketing-`Lead` wiederverwenden) — `marketingLeads.prisma` als Feld-/Index-Vorlage nehmen, tenant-scopen, Status-Enum auf HiveGrid-Semantik. `user-fk-map.ts` ergänzen.
4. DB-Helper nach Muster `leads.db.server.ts` bauen, aber mit `withTenantScope()` + Owner-Check (M004).
5. Quellen-Auto-Anlage (Form/Mail/Phone/Manuell) nach Muster `captureLead.server.ts` + Apps-Engine-Schema; `lead.created`-Outbox-Event publizieren; Realtime-Push.
**Phase 2 — Listen/Detail/Triage-UI + Permissions (M051-Teil):**
6. Inbox-Route nach Muster `admin/marketing-leads/index.tsx`, aber Tenant-Route + Multi-Select-Filter + Bulk-Actions + View-Model-Adapter + Subframe + i18n.
7. Detail-/Triage-Route nach Muster `$id.tsx`; HiveGrid-State-Machine + Promotion-Modal (Modul 1) + Activity-Stream (M045).
8. Permission-Bundle `leads.*` seeden + scope-bewusste Filter.
**Phase 3 — Routing + Auto-Verkaufsfall (M048, M049):**
9. Routing-Regel-DSL + Round-Robin (neu, Outbox/Apps-Engine als Basis); Auto-Verkaufsfall als Routing-Action (nach Sales-Pipeline M059/M060).
**Phase 4 — Spam/DSGVO (M050):**
10. Rate-Limiter (fixed/sliding) für Hard-Limits; Anomalie-Detector (neu, M010-Webhook-Schutz als Re-Use); Auto-Lösch-Cron nach Muster `audit-retention.ts`/`dsgvo-grace-cron.ts` mit Lead-Semantik + Anonymisierung.
**Phase 5 — Statistik + Admin-UIs (M051-Rest):**
11. Statistik-Page (komplett neu) + Quellen-Verwaltung + Anti-Spam-Settings-UI.
**Faustregel:** Querschnitt (Outbox/Audit/Notif/Permissions/Realtime/Rate-Limit/Export/Honeypot) = 1:1. Daten-Modell + Status-Logik + Listen/Statistik/Routing/Spam-Domäne = neu, aber mit den genannten Boilerplate-Dateien als konkrete Code-Vorlage. **Nicht** den marketing-`Lead` mitbenutzen — Scope-Inkompatibilität.