Files
HiveGrid-Wireframes/hivegrid-cloud/docs/boilerplate-mapping/M01-crm-kern.md
T

21 KiB
Raw Blame History

Boilerplate-Abgleich: M01 — CRM-Kern

Faktischer Abgleich der HiveGrid-Anforderungen (Modul 1) gegen die Boilerplate (/Users/raffaelsheikh/Documents/GitHub/boilerplate). Read-only verifiziert mit eigenen Greps/Reads, nicht nur Inventur. Alle Pfade absolut.

Kopf

Feld Wert
Modul-ID M01
Name CRM-Kern (Kontakte + Firmen + Leads)
Milestones M042 (Kontakt-Stammdaten), M043 (Firma-Stammdaten + Hierarchie), M044 (Tags + Custom-Felder + Datenherkunft), M045 (Aktivitäts-Stream), M046 (Listen + Segmente + DSGVO-Felder)
Pflichtenheft-Block Block 2, Abschnitte 1.1–1.13 (_bmad-output/pflichtenheft/blocks/block2.md)
Detail-Spec _bmad-output/specs/M01-crm-kern.md
Reuse-Level medium

Reuse-Verdict in einem Satz

Das Daten-Modell des Moduls (Contact/Company/Lead als dedizierte, first-class Prisma-Modelle mit Mehrfach-Email/-Telefon, M:N-Relation, Activity-Sourcing-Tabelle, Custom-Field-Definitionen, Tags) existiert in der Boilerplate nicht — es gibt nur (a) eine generische No-Code-Engine (entityBuilder), auf der die Boilerplate ihr eigenes, architektonisch unvereinbares CRM (company/contact/opportunity als Entity+Row) betreibt, und (b) einen operator-scoped Marketing-Lead (kein Tenant-CRM-Lead). Der gesamte Querschnitt (Audit, Permissions/Tenant-Scope, Notifications, i18n, Feature-Flags, View-Models, Search, Export/DSGVO, App-Shell, Form-Capture) ist hingegen reif vorhanden und direkt nutzbar. Daher: solides Fundament + viele Vorlagen, aber die CRM-Kern-Tabellen und die domänen-spezifische Logik sind neu zu bauen.


Wichtige Architektur-Vorbemerkung (entscheidet das gesamte Mapping)

Die Boilerplate enthält zwei CRM-Konzepte, die beide NICHT zur HiveGrid-Spec passen:

  1. Boilerplate-„CRM" über den Entity-Builder (apps/web/app/modules/crm/): company, contact, opportunity, submission sind keine eigenen Prisma-Modelle, sondern werden zur Laufzeit als entityBuilder.Entity-Definitionen geseedet (apps/web/app/modules/crm/services/ProductCoreCrmEntities.server.ts, productCoreCrmEntityNames = ["company","contact","opportunity"]). Ein Kontakt ist ein Row mit RowValue-Einträgen (firstName, lastName, email, jobTitle, marketingSubscriber). Verifiziert in CrmService.ts (RowValueHelper.getText({..., name: "email"})). → Inkompatibel mit der HiveGrid-Spec, die explizit dedizierte, typisierte Tabellen mit Constraints, Indizes (tenant_id, archived_at, last_activity_at), pg_trgm-Fuzzy-Index, ContactCompanyRelation (M:N mit Rolle/Primary), separate ContactEmail/ContactPhone-Tabellen und eine zentrale Activity-Event-Sourcing-Tabelle fordert.

  2. Marketing-Lead (prisma/schema/marketingLeads.prisma:14): bewusst NICHT tenant-scoped (operator-/sales-of-record, @@unique([email]), First-Touch-UTM, convertedToTenantId). Das ist der „Wer-wird-HiveGrid-Kunde"-Funnel, nicht der tenant-interne CRM-Lead aus M01/M02 (der ist tenant-scoped, hat Status new|qualified|converted|lost|spam und konvertiert zu einem Contact, nicht zu einem Tenant).

Konsequenz: Die HiveGrid-CRM-Modelle gehören neu nach prisma/schema/app.prisma (der vorgesehene leere Platzhalter, prisma/schema/app.prisma). Die Entity-Builder-Variante wird NICHT übernommen (allenfalls als konzeptionelle Vorlage für Custom-Felder-UI). Das Boilerplate-CRM-Modul (apps/web/app/modules/crm, routes/app.$tenant/crm, routes/admin/crm) sollte für HiveGrid entfernt/ersetzt werden, da es die andere Architektur transportiert.

Hinweis: Das HiveGrid-Cloud-Repo selbst enthält aktuell noch keinen Code (apps//packages/ fehlen, nur prisma/ + docs/ + Specs vorhanden). Die Boilerplate ist die zu übernehmende Basis (gem. AGENTS.md „Die Boilerplate IST deine Codebase").


Übernehmbar aus Boilerplate

Boilerplate-Pfad Was Wie nutzbar
packages/foundation/src/permissions.ts withTenantScope(), withPermission(), withOwnerCheck(), requirePermission() — Tenant-Isolation + Permission-/Owner-Gate; 404-statt-403 (CatalogError(notFound)) 1:1 — deckt Block I komplett (crm.read_own/read_all/write/delete/admin, Owner-Check, 404-Versteckung)
packages/foundation/src/audit.ts auditEvent(), withAuditMiddleware() + AuditEvent-Hash-Kette (packages/db/src/audit-hash.ts, prisma/schema/core.prisma:55) 1:1 — Audit-Default (AV #6) für jede Schreib-Aktion
packages/foundation/src/notifications.ts + prisma/schema/notifications.prisma notify(), bundleNotifications(), Preference-Check, In-App/Email/Push 1:1 — Notification-Wiring (Verantwortlichen-Wechsel, Lead-Zuweisung)
packages/foundation/src/errors.ts CatalogError, foundationErrors (forbidden/notFound/conflict), toPinoLogObject als-vorlage — HiveGrid-Error-Catalog (M002) auf diesem Muster; Klartext-Texte (Block C/D/F/G/H „Klartext-Hinweise") als i18n-Keys ergänzen
packages/foundation/src/idempotency.ts withIdempotency() (Lead-Promotion-Transaktion, Bulk-Actions) 1:1
packages/view-models/src/index.ts VMState<T>, VMStatus, ActionCallbacks<T>, RegistryGate, I18nLabel, SidebarRegistryItem, assertI18nLabel 1:1 — VM-/Action-Vertrag für alle Listen-/Detail-VMs (AGENTS.md C.18, INTEGRATION-CONTRACTS §11)
packages/feature-flags/src/* + prisma/schema/featureFlags.prisma Flag-Engine v2 (Targeting, Cache, React-Hooks) bzw. leichtgewichtig foundation/src/flags.ts 1:1 — Feature-Flag-fähig (M006, DoD)
packages/i18n/src/* + apps/web/public/locales/{de,en}/crm.json Locales, Intl-Formatter, ICU; CRM-Namespace crm existiert bereits (i18nNamespaces in packages/i18n/src/index.ts) anpassen — Keys neu für HiveGrid-CRM füllen; Namespace + Formatter-Infra 1:1
packages/db/src/client.server.ts, transactions.server.ts, outbox.ts getDbClient()/getReadDbClient()/getExtendedDbClient(), runDbTransaction(), publishOutboxEvent() 1:1 — DB-Grenze + Lead-Promotion-Transaktion + Side-Effects via Outbox
packages/db/src/dsgvo/user-fk-map.ts, dsgvo/pseudonymize.ts Zentrale User-FK-Karte (CI-Test erzwingt Vollständigkeit) + Pseudonymisierung anpassen — neue Contact/Lead-User-FKs (assigned_to_user_id, created_by_user_id) eintragen, sonst bricht CI
packages/exports/* + apps/worker/src/jobs/dsgvo-export.ts Streaming-Export CSV/JSON/XLSX/PDF, S3-Sink, DSGVO-Personal-Data-Export (JSON-Bundle, Signed-URL, Audit-Event) anpassen — Block D „DSGVO-Daten-Export (alle Daten als JSON)" + Block C „Export als CSV (gefilterte Auswahl)"; an HiveGrid-Contact-Schema anpassen
packages/imports/* + prisma/schema/imports.prisma Dependency-freies Parser-/Dry-Run-/Dedupe-Framework (CSV/JSON/XLSX), PII-Redaction; src/dedupe.ts (DuplicateKeyField, DuplicateDetectionRow) anpassen — lead_source = import, Dedupe-Logik als Basis für Block G (Duplikat-Erkennung); Dry-Run-Preview für Import-Wizard
packages/search/src/* (@toolctrl/search) + apps/web/app/modules/crm/services/crmContactSearch.server.ts Meilisearch-Client + SQL-Fallback (searchWithFallback, SEARCH_BACKEND=sql); Beispiel-Such-Implementierung über Kontakt-Felder als-vorlage — Block G (Listen-Suche + Auto-Complete + globale Suche M24/M056); HiveGrid-Implementierung muss auf neue Tabellen statt RowValue zeigen; Trigram/pg_trgm ist im Schema selbst zu ergänzen (nicht vorhanden)
packages/form-widget/src/routing.ts resolveSubmissionTarget/applyFieldMapping mit Ziel "crm-contact" (verifiziert) + prisma/schema/formWidget.prisma (Form, FormSubmission) anpassen — lead_source = form Eingang (Block A, M02); Routing-Ziel auf HiveGrid-Lead/Contact umbiegen
apps/web/app/components/layouts/sidebars/shadcn/* + apps/web/app/application/sidebar/{AppSidebar.tsx,SidebarItem.ts,SidebarGroupDto.ts} + ShadcnSidebarLayout.tsx, AppLayout.tsx Vollständige authentifizierte App-Shell, datengetriebene Sidebar mit Permission-/Feature-Gating, Tenant-Theme, Breadcrumbs, Command-Palette als-vorlage — HiveGrid fordert eigene packages/ui-hivegrid/src/app-shell/sidebar.config.ts (existiert noch nicht); Shell-Mechanik + Permission-Filter übernehmen, in HiveGrid-6-Gruppen-Schema (stammdaten, arbeiten) überführen
apps/web/app/components/ui/** (~707 .tsx, shadcn/Radix) Tabellen (TableNew, TablePagination, RowsLoadMoreCard, ColumnSelector, GridPagination), Forms/Inputs/Selectors/Editors, multi-select.tsx, Modals (ConfirmDialog), Empty-/Loading-States, command.tsx, badge.tsx als-vorlage — deckt nahezu alle UI-Element-Anforderungen aus Block C/D/E (Listen-Tabelle, Spalten-Selektor, Cursor-„Mehr laden", Filter, Bulk-Checkboxes, Inline-Edit, Tag-Editor via multi-select, Markdown-Editor). MEMORY-Regel: HiveGrid-Routen müssen via Subframe + packages/ui-hivegrid-Adapter laufen → diese Komponenten als Adapter-Backing
apps/web/app/components/ui/tables/ColumnSelector.tsx, GridPagination.tsx, RowsLoadMoreCard.tsx Spalten-Konfiguration + Cursor-Pagination („Mehr laden", 50/Page) als-vorlage — Block C Performance-Anforderung (10k+, server-side)
prisma/schema/marketingLeads.prisma (Lead, LeadEvent, LeadStatus) Lead-Timeline-Append-Log + Status-Enum + Conversion-FK-Pattern als-vorlage — NUR konzeptionell für M02 Tenant-Lead (Status-Maschine, Event-Timeline, Promotion-FKs). NICHT 1:1 (operator- vs. tenant-scoped, andere Status-Werte)
prisma/schema/queue.prisma (ExportJob mit expiresAt/hardDeletedAt) Retention/Grace-Pattern (Soft→Hard mit Frist) als-vorlage — DSGVO-Auto-Lösch von Spam-Leads (30 Tage), archived_at-Grace
apps/web/app/application/ui/uiRegistry.ts + docs/ui-inventory/* + scripts/verify-*boundaries*.mjs Stabile data-ui-id-Registry + maschinenlesbare Inventur + Layer-Grenz-Gates als-vorlage — UI-Governance/Hot-Swap (M016/M017, DoD-Tests)
packages/ui-mock/src/* Hot-Swap-Mock-Generator (deterministisches HTML + Hashes) 1:1 — Hot-Swap-Drill (DoD: Smoke-Test gegen ui-mock)
packages/entitlements/src/features.ts (crm-basic Feature-Key) Feature-Gate-Registry; crm-basic existiert bereits anpassen — CRM-Feature-Gating; Permission-Keys (crm.*) gehören laut INTEGRATION-CONTRACTS §10 nach packages/entitlements/src/permissions.ts (noch zu erstellen)

Vorhandene Daten-Modelle (konkret, mit Pfad)

Direkt CRM-deckend: KEINE. Verifiziert via grep "^model (Contact|Company|ContactCompany|ContactEmail|ContactPhone|Activity|CustomField|Tag)" über prisma/schema/*.prisma → 0 Treffer (einziger Tag-Treffer ist EntityTag der No-Code-Engine).

Relevante angrenzende / als Fundament nutzbare Modelle:

Modell Pfad Relevanz für M01
AuditEvent prisma/schema/core.prisma:55 Audit-Trail-Default (AV #6) — tamper-evident Hash-Kette, dataSensitivity/regulatoryScope für PII/GDPR
IdempotencyKey prisma/schema/core.prisma:84 Idempotente Lead-Promotion / Bulk-Actions
Log prisma/schema/core.prisma:36 Per-Row-Aktivitäts-Timeline der No-Code-Engine (rowId, action, details, commentId) — konzeptionelle Vorlage für die HiveGrid-Activity-Tabelle (Block E), NICHT übernehmbar (kein subject_type/actor_kind/summary_text, an Row gebunden)
Role, Permission, RolePermission, UserRole, Group, GroupUser prisma/schema/permissions.prisma RBAC-Fundament — Block I Permission-Bundles (crm.none→crm.admin) als Role+RolePermission abbildbar
User, Tenant, TenantUser prisma/schema/accounts.prisma assigned_to_user_id/created_by_user_id-FKs, Tenant-Scope-Anker, DSGVO-Flags
NotificationDelivery, UserNotificationPreference prisma/schema/notifications.prisma Notification-Wiring
FeatureFlag (+ Filter/Audit) prisma/schema/featureFlags.prisma Feature-Flag-fähig (DoD)
Lead, LeadEvent, LeadStatus prisma/schema/marketingLeads.prisma:14 NUR Vorlage für tenant-scoped CRM-Lead (M02); semantisch operator-scoped, NICHT 1:1
Form, FormSubmission prisma/schema/formWidget.prisma Lead-Capture-Eingang (lead_source=form)
ImportJob prisma/schema/imports.prisma Bulk-Import (lead_source=import)
ExportJob prisma/schema/queue.prisma DSGVO-Export-Job + Retention-Pattern
entityBuilder.* (Entity, Property, EntityView, Row, RowValue, RowComment, RowTag, EntityTag, RowTask, RowPermission, EntityRelationship) prisma/schema/entityBuilder.prisma Konkurrierendes Daten-Modell für Custom-Felder/Tags/Activity — als Vorlage für Block F/H, aber Architektur (polymorphe RowValue) wird für M01 NICHT übernommen (Spec fordert typisierte Tabellen)

Property-Typen (apps/web/app/application/enums/entities/PropertyType.ts): NUMBER, TEXT, DATE, MEDIA, SELECT, BOOLEAN, MULTI_SELECT, MULTI_TEXT, RANGE_NUMBER, RANGE_DATE, FORMULA. → deckt die Spec-Custom-Field-Typen text|number|date|select|multiselect|boolean ab; fehlend als eigene Typen: url, email (Spec Block F) — in der Boilerplate über TEXT + subtype/PropertyAttribute-Validierung gelöst; HiveGrid muss url/email als field_type neu vorsehen.


Lücken / komplett neu zu bauen

Daten-Layer (alles neu, nach prisma/schema/app.prisma):

  • Contact (alle Felder: salutation, title, first/last_name, address_*, birthdate, notes, language, assigned_to_user_id, lead_source-Enum, is_endkunde, archived_at) — fehlt
  • Company (legal_form, vat_id, tax_number, industry, website, address_*, …) + optionale Mutter-Tochter-Hierarchie (M043) — fehlt
  • ContactCompanyRelation (M:N, role, is_primary, since/until_date) — fehlt
  • ContactEmail / ContactPhone (value, label-Enum, is_primary) — fehlt
  • Tenant-scoped Lead (mit Status new|qualified|converted|lost|spam, converted_to_contact_id, converted_to_deal_id) — fehlt (Marketing-Lead ist anders)
  • Activity (zentrale Event-Sourcing-Tabelle: actor_kind, activity_type-Enum ~25 Werte, subject_type/subject_id, related_entity_refs[], metadata, summary_text) — fehlt (kein generisches subject-polymorphes Activity-Modell in der Boilerplate; Log ist row-gebunden)
  • CustomFieldDefinition + CustomFieldValue (applicable_to contact/company/lead, field_type inkl. url/email, options[], JSONB-Wert) — fehlt als dedizierte Tabellen
  • Tag (8 Farben-Constraint, applicable_to[]) + EntityTag-Äquivalent für CRM-Entities — fehlt (No-Code-EntityTag/RowTag ist row-gebunden, nicht übernehmbar)
  • Spezifische Indizes: (tenant_id, archived_at, last_activity_at), pg_trgm-Trigram-Index auf Namen, FTS-Index — alle neu (Spec Block C/G)
  • Branchen-Template-Seeding (SHK-Custom-Fields + Tag-Defaults) als Konfig-Datei (AV #3, A.3) — neu

Domänen-Logik / Services (neu):

  • Lead-Promotions-Transaktion mit Auto-Email-Match (4 Optionen a–d) — neu
  • Duplikat-Erkennung (Hard: Email/Phone; Soft: Name+Firma / Name+PLZ) + Inline-Live-Check + Bulk-Merge-Tool mit Field-by-Field-Auswahl + Verknüpfungs-Umhängen — neu (Dedupe-Primitiven aus packages/imports/src/dedupe.ts als Basis, aber CRM-Merge-Logik neu)
  • logActivity()-Service (@hivegrid/activity, INTEGRATION-CONTRACTS §5) + Activity-Stream-VM (Tag-Bucket-Gruppierung, Filter, Permission-aware, Firma=Aggregat der Kontakt-Activities) — neu
  • Tag-Merge / Auto-Cleanup, Custom-Field-Verwaltung (Drag&Drop-Sortierung, Archive vs. Hard-Delete) — neu

Querschnitt-Verdrahtung (HiveGrid-Konventionen — Ziel-Pfade existieren in Boilerplate noch nicht):

  • packages/ui-hivegrid/src/app-shell/sidebar.config.ts — fehlt (kein packages/ui-hivegrid in der Boilerplate); Sidebar-Gruppen STAMMDATEN (Kontakte/Firmen/Tags/Custom-Felder) + ARBEITEN (Lead-Inbox)
  • packages/ui-hivegrid/src/adapters/ (Subframe-Adapter) + breadcrumbs/ + mobile/tab-bar.config.ts
    • customer-portal/portal-shell.config.ts — alle neu (DoD §13/§14)
  • packages/db/src/search/indexed-entities.ts — fehlt (Verzeichnis packages/db/src/search existiert nicht); Contact/Company/Lead als suchbare Entitäten registrieren (M056)
  • packages/entitlements/src/permissions.ts (crm.*-Keys) — fehlt als Datei
  • @hivegrid/*-Service-Fassaden (activity, audit, notifications) — Boilerplate nutzt @toolctrl/*; Umbenennung/Fassade ist HiveGrid-Aufgabe (kein PR-blockierender Unterschied)

UI (neu, aber stark gestützt):

  • Subframe-Designs für jede Route (MEMORY: Subframe pflicht) — neu, Boilerplate-ui-subframe ist leerer Platzhalter
  • Inline-Edit-Felder, Markdown-Notiz-Editor, Tag-Editor (ad-hoc anlegbar), Promotions-Modal, Side-by-Side-Merge-UI, Custom-Field-Renderer pro Typ — als Komposition aus vorhandenen shadcn-Primitiven, aber CRM-spezifisch neu

Empfohlenes Vorgehen (Reihenfolge)

Phase 0 — Boilerplate-Bereinigung (vor M042):

  1. Boilerplate-CRM (Entity-Builder-basiert) zur Seite legen/entfernen, damit die andere Architektur nicht in HiveGrid einsickert: apps/web/app/modules/crm/, apps/web/app/routes/app.$tenant/crm/, apps/web/app/routes/admin/crm/ (und der No-Code-crm-Seed in ProductCoreCrmEntities.server.ts). Den crm-i18n-Namespace und die crm-basic-Feature-Gate-Infrastruktur behalten.
  2. HiveGrid-Querschnitt-Pakete anlegen, die noch fehlen: packages/ui-hivegrid/ (sidebar.config, adapters, breadcrumbs, mobile, customer-portal), packages/db/src/search/indexed-entities.ts, packages/entitlements/src/permissions.ts. (Diese sind modul-übergreifend — ggf. eigenes Fundament-Milestone, aber M01 ist der erste Konsument.)

Phase 1 — Daten-Fundament (M042 → M043): 3. CRM-Modelle in prisma/schema/app.prisma neu: Contact, ContactEmail, ContactPhone, dann Company, ContactCompanyRelation (M:N). Forward-Only-Migration mit Inverse-SQL-Kommentar (DoD). pg_trgm-Extension + Trigram-/FTS-Indizes + (tenant_id, archived_at, last_activity_at)-Index. 4. Sofort übernehmen: withTenantScope()+withPermission()+withOwnerCheck() (packages/foundation/src/permissions.ts) für jeden Loader/Action; auditEvent/Middleware für Schreib-Aktionen; neue User-FKs in packages/db/src/dsgvo/user-fk-map.ts (sonst CI-Bruch); VM-Builder gegen VMState/ActionCallbacks (packages/view-models). 5. UI per Subframe → ui-hivegrid-Adapter, gestützt auf shadcn-Primitiven (apps/web/app/components/ui/**). Sidebar-Einträge STAMMDATEN registrieren (INTEGRATION-CONTRACTS §1/§2).

Phase 2 — Querschnitt-Features (M044 → M045): 6. Tags (Tag+CRM-Tag-Join, 8-Farben-Constraint) und Custom-Felder (CustomFieldDefinition+CustomFieldValue) neu — PropertyType-Enum + Entity-Builder-Custom-Field-UI (apps/web/app/components/entities/properties/*) als Vorlage, url/email-Typen ergänzen. SHK-Defaults als Seed-Konfig (A.3). 7. Activity-Tabelle + logActivity() neu (zentrales Event-Sourcing, INTEGRATION-CONTRACTS §5); Log-Modell + hasActivity-Konzept der Engine als Vorlage. Activity-Stream-VM mit Tag-Buckets/Filtern/Permission-Gate; Firma=Aggregat.

Phase 3 — Listen, Suche, DSGVO (M046): 8. Listen-VM mit server-side Filter (Permission-aware-Default, AV #5), Cursor-Pagination (RowsLoadMoreCard/GridPagination als Vorlage), Spalten-Selektor (ColumnSelector), Bulk-Actions. Such-Anbindung via @toolctrl/search (searchWithFallback, SQL-Fallback) auf die neuen Tabellen; Registrierung in indexed-entities.ts. 9. Duplikat-Erkennung: packages/imports/src/dedupe.ts-Primitiven als Basis; Inline-Live-Check + Bulk-Merge-Tool (/admin/duplicates/) neu. 10. DSGVO: packages/exports + apps/worker/src/jobs/dsgvo-export.ts an Contact-Schema anpassen (Per-Contact-JSON-Export, Audit-Event); CSV-Export der gefilterten Listen-Auswahl.

Durchgängig: i18n-Keys (Namespace crm), Feature-Flag-Gate (M006), Smoke-Tests + Hot-Swap-Drill (ui-mock) + Visual-Regression (DoD D.18–21), Klartext-States (DoD E.22–25).


Anti-Erfindungs-Vorbehalte

  • Es gibt keine dedizierten CRM-Prisma-Modelle in der Boilerplate (verifiziert per Grep).
  • Das Boilerplate-CRM ist Entity-Builder-basiert (Entity+Row+RowValue), nicht tabellen-typisiert — verifiziert in CrmService.ts und ProductCoreCrmEntities.server.ts.
  • packages/ui-hivegrid, packages/db/src/search, packages/entitlements/src/permissions.ts existieren in der Boilerplate nicht (verifiziert per ls/find).
  • @toolctrl/ui-subframe ist leer (Platzhalter) — kein gebauter Subframe-Adapter-Layer.
  • Der Boilerplate-Lead ist operator-/marketing-scoped (@@unique([email]), kein tenantId, Status new|contacted|qualified|trial|customer|churned|disqualified) — nicht der HiveGrid-Tenant-CRM-Lead.
  • url/email sind keine eigenen PropertyType-Werte (nur via TEXT+subtype gelöst).