Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/R-P6.md
T

16 KiB

R-P6 · P6 CRM-Kern

Typ Dev (Code)
Owner Raffael
Phase P6 — CRM-Kern
Cycle/Fenster W2 — Plattform & CRM · fällig 2026-06-24 · Gate W2 (Noah-Demo #1)
Status geplant

🎨 design-nachzug: offen (seit 2026-07-08) — Interim-UI aus ~/ui steht (alle 7 CRM-Screens auf ~/ui, AD-28); finale Subframe-Optik aus D-CRM ausstehend.

Abhängigkeiten & Parallelität

  • Blocked by: R-P5 (Apps-Engine), AK-P4b (Files/Tasks + EntityLink), R-REFIT (ER-Modell-Re-Fit — ✅ erledigt 16.06.)
  • Blocks: R-P7 (Lead-Inbox), AK-P14a (Email/BCC), AK-P15a (Telefonie/Auto-Lead)
  • Läuft parallel zu: AK-P19 (Plattform-Admin, eigener Host admin.hivegrid.de) — maximal isoliert, kein Schema-Konflikt (CRM-Domäne vs. Admin/Permissions). Eigene prisma/schema/*.prisma je Modul (AD-21).

Was wir bauen

Den CRM-Kern: Kontakte, Firmen/Organisationen und Leads als typisierte First-Class-Entitäten (kein Entity-Builder, AD-2) — mit Custom-Feldern, farbigen Tags, append-only Activity-Stream und Live-Duplikat-Schutz. Das ist das Fundament der Kern-Kette (Lead → Projekt, AD-20). Kontakt ist Oberbegriff: Kontakttyp (Privatperson/Organisation), Kontaktstatus (Kontakt/Kunde/Bestandskunde), Kontaktart (Haupt-/Sekundärkontakt = Rolle einer Relation).

Benötigte Screens (Backend bedient — Design liefert D-CRM)

Screen [Route] Kern-Inhalt
Kontakt-Liste [/contacts] Tabelle + Filter (Verantwortlicher/Tags UND-ODER/Firma/Datum) + Bulk (Tag/Zuweisen/Archiv/CSV)
Organisationen-Liste [/contacts/companies] Name, Branche/Org-Merkmal, Kontakt-Anzahl, letzte Activity
Kontakt-Detail [/contacts/:id] Inline-Edit, verknüpfte Orgs + Rolle, Tags, Panels (Projekte/Dateien/Tasks), Custom-Felder, Activity-Stream, Quick-Actions
Organisation-Detail [/contacts/companies/:id] Analog + Kontakt-Verknüpfungen mit Primär-Markierung
Custom-Felder [/admin/custom-fields] · Tag-Verwaltung [/admin/tags] · Duplikat-Tool [/admin/duplicates] Admin-Verwaltung + Side-by-Side-Merge

Definition of Done

  • Entitäten typisiert + RLS auf allem Tenant-bezogenen; Entity-Builder raus (AD-2)
  • Listen server-seitig: filter / sort / paginate / bulk / CSV
  • Detail: Inline-Edit + Activity-Stream (append-only Event-Sourcing) + Custom-Felder
  • Live-Duplikat-Check beim Anlegen
  • Lead → Projekt Extension-Point vorbereitet (AD-20; volle Konvertierung in P7/P8)
  • SHK-Branchen-Custom-Felder als Template geseedet (is_demo_data)
  • Konnektor tenantHasModule('crm') (Sidebar + Routes + Actions gated)
  • crm.*-Permission-Bundle (read_own/read_all/write/delete/admin) + serverseitiger Owner-Filter

Technische Bausteine

  • Entities (eigene prisma/schema/crm.prisma): Kontakt, KontaktRelation (self-ref Rolle haupt/sekundär), KontaktEmail/KontaktTelefon (1:N), Activity (polymorph subject_type/id, append-only), CustomFieldDefinition/CustomFieldValue, Tag/TagAssignment (polymorph). core.prisma/accounts.prisma nur für Relationen zu Tenant/User berühren (AD-21).
  • Activity = Event-Sourcing-Zentrale (Cross-Cutting); actor_kind user/system/automation/ki_agent.
  • Adressen über Adresse-Tabelle (Kontakt 1 Slot).
  • is_demo_data-Flag auf seedbaren Entitäten (Bulk-Lösch beim Echt-Start).

Quellen (granular)

  • ENTITY-MODEL.md → Domäne 5: Projekt-zentrischer CRM-Kern (Kontakt/KontaktRelation/Activity/CustomField/Tag) + Cross-Cutting-Tabelle
  • REQUIREMENTS.md → REQ-crm-* (Modul 1)
  • ROADMAP.md → Phase 6
  • designer-briefs/P06-crm-kern.md (Screens + UI-Elemente, Pivot-Vorrang-Hinweis)

Scope-Entscheidung Entity-Builder-Ablösung (2026-06-29)

Der Entity-Builder ist tiefer verankert als nur CRM (auch settings/entities, new-account-Tenant-Seed, Hocuspocus-Row-Collab). Aufteilung:

  • R-P6 (dieses Ticket, Variante A): CRM-scoped Ablösung — typisierte Kontakte bauen + modules/crm (CrmService/ProductCoreCrmEntities/crmContactSearch) + autogenerierte admin/crm/$entity-Routes raus + new-account-CRM-Seed auf typisiert umstellen.
  • R-P6B (Folge-Ticket, Plane #166, Variante B): generischer Entity-Builder-Vollausbau — settings/entities, Row-Collab, utils/db/entities, modules/rows, entityBuilder.prisma entfernen. blocked-by R-P6. Verbindlich (AD-2, 2026-06-29): die volle Ablösung ist Pflicht (kein „optional"); ab sofort KEINE neuen Entity-Builder-Konsumenten (PR-Block) — siehe AGENTS.md + R-P6B.md §Rückwirkungs-Audit.
  • E2: Backend + minimale Inline-Swap-UI, finale Optik via D-CRM. E3: SHK-Custom-Felder-Template später mit Geerkens (nur Mechanik + leeres Template). E4: ein PR am Ende. Activity wird genutzt (nicht neu gebaut).

Umsetzung (2026-06-29) — 8/8 DoD = 100 % done (selbst machbar)

Gebaut in 6 Slices auf feat/R-P6 (Branch von origin/main), Pre-Flight grün, jeder Slice lokal typecheck+lint+test+i18n grün:

  • Slice 1 prisma/schema/crm.prisma (28699ac4a): Kontakt, KontaktRelation, KontaktEmail, KontaktTelefon, Adresse, CustomFieldDefinition, CustomFieldValue, Tag, TagAssignment (AD-21: bare String-Scalars, soft-delete archivedAt, isDemoData, polymorphe entityType tragen lead/projekt/rechnung → Lead→Projekt-Extension-Point, DoD 5). RLS-Rollout-Artefakt prisma/rls/crm-isolation.sql (deferred/fail-closed/FORCE, analog task/file). prisma validate + db push (kein Migration-File, AD-21) + generate grün. Activity NICHT neu gebaut (nutzt activity.prisma + logActivity).
  • Slice 2 Services apps/web/app/utils/integrations/crm/* (b7bdb7b4e): CRUD + withTenantRLS, server-seitige Liste (filter/sort/paginate) mit Owner-Scope (DoD 8), Live-Duplikat-Check hard(email/telefon)/soft(name) (DoD 4), Bulk, Custom-Fields, Tags, Audit+Activity-Wiring. SHK-Seed-Mechanik + bewusst leeres Template (E3).
  • Slice 3 View-Models packages/view-models/src/crm/* (a73aaf948): pure, i18n-Keys, VMState; 15 Fixture-Tests. (+ href-Konsistenz-Fix a695b2c2d.)
  • Slice 4 Routes app.$tenant/contacts.* + minimale Inline-UI + i18n (2e89b5898): Liste (server-seitig filter/sort/paginate/bulk/CSV, DoD 2), Detail (Inline-Edit + Activity-Stream + Custom-Felder, DoD 3), /contacts/new mit Live-Dup-Check, Admin custom-fields/tags/duplicates (crm.admin-gated). Klartext Empty/Permission-Denied=404.
  • Slice 5a Permissions + Sidebar (78a000b9d): crm.*-Bundle in DefaultPermissions + permissions-seed (DoD 8), Sidebar /crm→/contacts + Permission-Gate (DoD 6/7), roleDisplay-Scope-i18n.
  • Slice 5b Entity-Builder-CRM-Pfad abgelöst + SHK-Seed verdrahtet (677b23e1e): autogenerierte/admin/dashboard CRM-Routes gelöscht, SeedService→seedShkCustomFieldTemplate (DoD 6), RowsApi-contact-Spezialfall nachgezogen (DoD 1).

Proof: Voller Test grün (3646 passed / 0 failed, 616 Test-Files); pnpm typecheck + pnpm lint + pnpm verify:i18n (parity 7488 keys, 0 forbidden) exit 0; 9 CRM-Tabellen in DB; decision-report-Check grün. PR #13 (git.tool-ctrl.de/.../pulls/13) → CI grün, alle 11 Jobs. CI-Footgun gefixt: 9 neue tenantId-Modelle mussten in packages/cli TENANT_SCOPED_MODELS registriert werden (lokaler pnpm test deckt nur Core ab, CI fährt zusätzlich test:packages).

Dokumentierte Default-Entscheidungen (Lücken, kein Scope-Konflikt):

  1. Module-Key = registrierter crm-basic (Ticket sagt 'crm'; ein ungeseedeter 'crm'-Key → tenantHasModule=false → Modul unsichtbar).
  2. ID/Naming: cuid() + camelCase ohne @@map (Codebase-Konvention; ENTITY-MODEL „UUID/snake_case" ist konzeptionell).
  3. EmailMarketing-Kopplung (wichtig): modules/crm/CrmService (Entity-Builder-contact-Reader getContact/getContactsInRowIds) wird von EmailMarketingService (AK-P14, ausserhalb R-P6-Scope) konsumiert. Vollständiges Löschen würde EmailMarketing brechen (AGENTS.md „Abhängige nicht brechen"); eine Migration wäre vorgezogene Fremdarbeit (verboten). → CRM-Entity-Builder-Pfad abgelöst, CrmService als markiertes Legacy behalten; vollständige Entfernung erst bei EmailMarketing→Kontakt-Migration (Folge-Ticket).
  4. Admin-Routes unter /contacts/admin/* (tenant-scoped, crm.admin-gated) statt Plattform-Admin-Host.
  5. UI: minimale Inline-Swap-UI (kein Subframe) — finale Optik via Davids D-CRM (Designer-first).
  6. Boilerplate-crm-decision-report (CRM-als-Plugin-Kandidat) an AD-2/AD-20-Pivot nachgezogen (R-P6 = der vom Report vorgesehene removal-Slice).

💡 Vorschläge (ausserhalb Scope, OK abwarten): (a) Folge-Ticket EmailMarketing→typisiertes Kontakt-Modell migrieren, dann modules/crm ganz entfernen + verwaiste CrmService-Exports (getSummary/getUsersInCrm…) löschen. (b) SHK-Custom-Felder-Template mit Geerkens füllen (E3). (c) pre-existing route_inventory tenant-Overage (114>78, von main) separat sanieren.

Querbezug AK-P3 (dependency-aware, 2026-07-07 — Akeshan)

AK-P3 (DoD 6, Sprach-Settings) hat das im LOCKED ENTITY-MODEL.md (§Domäne 2, i18n-Felder) vorgesehene Feld Kontakt.language String? additiv in crm.prisma ergänzt (Branch akeshan/ak-p3-interim-ui; Owner-Freigabe für die crm.prisma-Berührung liegt vor, 2026-07-06). Nullable, kein Default-Backfill (null = Tenant-Default), kein UI-Editor in v1 — Outbound-Nutzung kommt erst mit v2 (REQ-i18n-outbound). Bestehende CRM-Services/VMs bleiben unberührt (Feld wird nicht selektiert/geschrieben).

Interim-UI-Nachzug (AD-28, 2026-07-08 — Akeshan)

Die ursprüngliche R-P6-Umsetzung (Raffael) lieferte den Backend-Kern + eine minimale Inline-Swap-UI (handgeschriebenes Tailwind, kein ~/ui). Das erfüllte die AD-28-Golden-Rule noch nicht. Nachgezogen (Branch feat/AK-crm-lead-interim-ui, ab origin/main):

  • Alle 7 CRM-Screens als AD-28-Interim-Screens aus ~/ui (VM als Prop, kein hand-Tailwind), in apps/web/app/components/screens/crm/:
    • KontaktListPage (Liste + Firmen-Variante), KontaktDetailPage (Kontakt + Org-Detail, Master-Template A3), KontaktNewPage (Live-Duplikat-Banner), CustomFieldAdminPage, TagAdminPage, DuplicateToolPage.
    • Alte components/crm/KontaktListView.tsx + KontaktDetailView.tsx entfernt; Admin-/New-Routen von Inline-JSX auf Screen-Komponenten umgestellt (Loader baut VM, Route ownt Navigation/POST).
  • Proof: Commits 871993fd2 (Liste), 9f1baeb9e (Detail), 3735b0628 (New+Admin); pnpm --filter @hivegrid/web typecheck + verify:i18n grün; 21 Screen-Unit-Tests grün (data-ui-id-Muster wie HR). Kein Schema-Change → keine Merge-Migration.
  • %-Stand Interim-UI: Screens + VM-Anbindung + Unit-Tests (D18) = selbst machbar erledigt.
  • Finale Subframe-Optik bleibt getrackter Nachzug (design-nachzug), nicht Done-blockierend.

Interim-UI Test-Tail nachgezogen (AD-28, 2026-07-17 — Akeshan, Audit-Restarbeit)

Das Audit R-P6/R-P6B/R-P6C (2026-07-17) fand: R-P6 stand auf Done, aber die von AD-28 (Interim-Done) + AGENTS.md Block D geforderten Pflicht-Tests D19/D20/D21 fehlten (waren nur im Nachzug-Fliesstext oben als offen vermerkt, nie als DoD-Punkt erfasst). Nachgezogen auf Branch feat/r-p6-interim-test-tail, PR #151:

  • D19 e2e-Smoke tests/e2e/crm-interim-smoke.spec.ts: Login -> /contacts -> "Kontakt anlegen" -> Create-Form + Live-Duplikat-Check-Control sichtbar. Skip-guarded auf crm-basic-Entitlement, Muster wie dashboard/email-marketing-interim-smoke.
  • D20 Hot-Swap-Drill (M017): createCrmInterimFixturePage() in @hivegrid/ui-mock (deterministische typisierte KontaktListVM, VM-as-Prop) in verify:ui-hot-swap verdrahtet; pnpm run test:hot-swap gruen.
  • D21 Interim-Visual-Baseline (M016): CRM in verify:ui-mock-visual registriert, Baseline packages/ui-mock/visual-baseline/r-p6-crm-interim.{html,mock.ts,snapshot.json} generiert (AD-28 interim, Re-Baseline beim D-CRM-Nachzug). pnpm run verify:ui-visual 124 passed.
  • Proof: verify:ui-visual (124 passed) · verify:ui-hot-swap + test:hot-swap gruen · ui-mock-Suiten 49 passed · pnpm typecheck exit 0 · verify:i18n exit 0 (12491 keys, de/en parity, mock.r-p6.crm.* in beiden Locales) · Playwright kompiliert/entdeckt die CRM-Spec.
  • %-Stand: 12/12 (8 fachliche DoD + D18-D21) = 100 % AD-28-Interim-Done (vorher ~75 % gegen die volle AD-28-Messlatte, D19/D20/D21 offen). Live-Playwright-Lauf gegen den lokalen Stack (E2E-Env + crm-basic-Tenant) bleibt manueller Schritt wie bei den Peer-Interim-Smokes (CI fuehrt Playwright nicht aus). Hinweis Windows-Memory galt fuer den Original-Dev; hier (macOS) liefen die Drills lokal gruen.

Dev-Nachzug (nach Davids D-CRM-Delta)

  • Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
  • REQUIREMENTS/ROADMAP nachgezogen
  • Plane-Ticket R-P6 aktualisiert
  • <XPage>-Interna gegen Subframe-Delta tauschen (VM/Loader/Route unangetastet), Visual-Baseline neu ziehen

Fremd-Änderung an crm.prisma (2026-07-30, aus R-P8a / PR #286 — Akeshan)

Was: WF-P8 S02 (Projekt-Detailansicht) zeigt Firmen- und Ansprechpartner-Stammdaten. Die gehören zum Kontakt, nicht zum Projekt — dieselbe Firma hängt an vielen Projekten, und eine Kopie je Projekt würde die Wahrheit gabeln. Daher additiv in crm.prisma:

  • Kontakt: website, ustIdNr, handelsregister, kundennummer, kundeSeit, branche, mitarbeiterzahl (Firmenfelder) sowie position, erreichbarkeit (Ansprechpartner-Felder). Alle nullable, keine Semantik-Änderung an bestehenden Spalten.
  • KontaktTelefon: neues typ (haupt/durchwahl/mobil/fax, Default haupt) plus Enum KontaktTelefonTyp. S02 fragt nach „Durchwahl“ und „Mobil“; das ist eine Art von Nummer, kein Paar weiterer Skalare an Kontakt — ein Kontakt kann mehrere davon haben.

Wer schreibt sie: derzeit niemand. S02 rendert sie read-only und verlinkt zum Pflegen in die CRM-Detailscreens. Die Editoren gehören zu P6.

Konsequenz für R-P6: Die CRM-Screens kennen diese Felder noch nicht. Wenn D-CRM nachgezogen wird, sollten Firmen-Stammdaten und Position/Erreichbarkeit dort editierbar werden, sonst bleiben sie dauerhaft leer. KontaktTelefon.typ hat einen Default, bestehende Zeilen und der bestehende Schreibpfad bleiben also gültig; ein Typ-Selektor in der Telefonnummern-Pflege ist der Nachzug.

Migration: liegt im WF-P8-Branch-Migrationsfile 20260728120000_wf_p8_subframe_baseline (AD-21: eine Migration pro Phase, beim Merge). Gegen eine leere DB replaybar nachgewiesen. Policy-Vertrag 376 → 377 (die neue Tabelle ist ProjektAdressDetail in projekt.prisma, nicht CRM). An Raffael gemeldet.

Nachtrag 2026-07-30 (zweiter Durchgang WF-P8, ebenfalls user-beauftragt): zwei weitere Eingriffe in crm.prisma, beide additiv und in derselben Branch-Migration.

  1. Kontakt.notizen (Text, nullable) — die stehenden Absprachen mit einem Kontakt. Davids S02 zeigt sie auf Firmen- und Ansprechpartner-Karte, dort read-only; nicht die Activity-Timeline, die hält fest was passiert ist, das Feld was gilt.
  2. CustomFieldDatentyp um fünf Werte erweitert: prozent, datum_zeit, person_team, adresse, link (ALTER TYPE … ADD VALUE, PostgreSQL 12+ im Migrations-Transaktionsrahmen zulässig, weil in derselben Transaktion keiner davon gespeichert wird). Davids S05-Feldtyp-Picker listet 17 Typen; das Enum hatte 12. Für keinen der 17 Typen existiert heute ein eigener Renderer oder Validator — jeder Wert ist ein String im Textfeld.

Nachzug in P6 (Raffael), außerhalb dieses Durchgangs: updateKontakt trägt keine der Stufe-B-Spalten und auch notizen nicht, das heißt Website, USt-IdNr., Handelsregister, Kundennummer, Kunde-seit, Branche, Mitarbeiterzahl, Position, Erreichbarkeit und Notizen sind aktuell nur über Seed/DB pflegbar. Ebenso offen: ein Typ-Selektor für KontaktTelefon.typ und — falls gewünscht — eine zweite Adress-FK am Kontakt für die „Rechnungsadresse", die Davids Firmenkarte zeigt (bewusst nicht angelegt: eine Spalte, die kein Editor füllt). An Raffael gemeldet.