17 KiB
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-Cloudist aktuell ein reines Spec-/Docs-Repo (_bmad,_bmad-output,docs,prismaleer). Es existiert noch keinpackages/ui-hivegrid, keinapps/*, 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, EnumLeadStatus.Lead:email @@unique(GLOBAL, nicht pro Tenant), keintenantId(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 (typeString,actorId?,payload Json).
formWidget.prisma—Form,FormSubmission(Quelle „Formular" für Leads;ipHash,statusreceived/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(Bundleleads.*+ 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
- Tenant-scoped HiveGrid-Lead-Modell — Der Boilerplate-
Leadist operator-scoped mit globalem@@unique([email]). HiveGrid braucht ein neues Modell (tenantIdpflicht, FK aufTenantmitonDelete: Cascade,assigned_to_user_id, Status-Enumnew/qualified/converted/lost/spam,source,message,metadataJSON für Quellen-Detail). Geplanter Ort:prisma/schema/app.prisma(HiveGrid-Platzhalter). FK→User inuser-fk-map.tseintragen (CI-Pflicht). Indizes laut Spec:(tenant_id, status, created_at desc),(tenant_id, assigned_to_user_id, status), Trigram aufemail/phone/last_name. - Lead-Status-State-Machine (HiveGrid-Semantik) — Übergangs-Matrix aus Spec Block F (inkl.
converted-Lock, Re-Engagementlost↔qualified, False-Positivespam→qualified, Begründungs-Pflicht beilost). Boilerplate-State-Machine (new→…→customer/churned) ist semantisch anders → neu. - Permissions-aware Owner-Check-Filter (
read_ownvsread_all) — Server-side-Filter, der nicht-eigene Leads in Listen/Statistik/Bulk ausblendet (AV #5). RBAC-Tabellen +verifyUserHasPermissionvorhanden, aber der scope-bewusste Query-Filter + Bundleleads.*-Seed sind neu. - 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).
- 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).
- 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.
- 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).
- 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]". - 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.
- 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. - 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.
- 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-hivegridexistiert noch nicht; Boilerplatepackages/ui/ui-app/ui-subframesind Fundament/Vorlage. - Gespeicherte Ansichten (max. 5 Filter-Kombinationen pro User, Spec 2.3.8) + user-spezifische Spalten-Konfiguration — neu (Entity-Builder
EntityViewals konzeptionelle Vorlage, aber Lead ist eigenes Modell). - Inbound-Quellen-Adapter (Meta/Google/Funnel) —
packages/marketing-outboundist 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):
- Querschnitt aktivieren:
packages/db/src/outbox.ts,audit-hash.ts+AuditEvent,notifications,permissions+verifyUserHasPermission,realtime,shared-storeRate-Limiter,exports/CSV. Diese stehen für alle 5 Milestones bereit. hashIp()auscaptureLead.server.tsundisHoneypotTriggeredausform-widgetdirekt 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.