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

17 KiB
Raw Blame History

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.