# 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 - [x] Entitäten typisiert + **RLS** auf allem Tenant-bezogenen; Entity-Builder raus (AD-2) - [x] Listen server-seitig: filter / sort / paginate / bulk / CSV - [x] Detail: Inline-Edit + **Activity-Stream** (append-only Event-Sourcing) + Custom-Felder - [x] **Live-Duplikat-Check** beim Anlegen - [x] **Lead → Projekt** Extension-Point vorbereitet (AD-20; volle Konvertierung in P7/P8) - [x] SHK-Branchen-Custom-Felder als Template geseedet (`is_demo_data`) - [x] Konnektor `tenantHasModule('crm')` (Sidebar + Routes + Actions gated) - [x] `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: - [x] **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. - [x] **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. - [x] **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 - [ ] ``-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.**