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 Hostadmin.hivegrid.de) — maximal isoliert, kein Schema-Konflikt (CRM-Domäne vs. Admin/Permissions). Eigeneprisma/schema/*.prismaje 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(polymorphsubject_type/id, append-only),CustomFieldDefinition/CustomFieldValue,Tag/TagAssignment(polymorph).core.prisma/accounts.prismanur für Relationen zu Tenant/User berühren (AD-21). - Activity = Event-Sourcing-Zentrale (Cross-Cutting);
actor_kinduser/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-TabelleREQUIREMENTS.md→REQ-crm-*(Modul 1)ROADMAP.md→ Phase 6designer-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) + autogenerierteadmin/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.prismaentfernen. 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-deletearchivedAt,isDemoData, polymorpheentityTypetragenlead/projekt/rechnung→ Lead→Projekt-Extension-Point, DoD 5). RLS-Rollout-Artefaktprisma/rls/crm-isolation.sql(deferred/fail-closed/FORCE, analog task/file).prisma validate+db push(kein Migration-File, AD-21) +generategrün. Activity NICHT neu gebaut (nutztactivity.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-Fixa695b2c2d.) - 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/newmit 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):
- Module-Key = registrierter
crm-basic(Ticket sagt'crm'; ein ungeseedeter'crm'-Key →tenantHasModule=false → Modul unsichtbar). - ID/Naming:
cuid()+ camelCase ohne@@map(Codebase-Konvention; ENTITY-MODEL „UUID/snake_case" ist konzeptionell). - EmailMarketing-Kopplung (wichtig):
modules/crm/CrmService(Entity-Builder-contact-ReadergetContact/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,CrmServiceals markiertes Legacy behalten; vollständige Entfernung erst bei EmailMarketing→Kontakt-Migration (Folge-Ticket). - Admin-Routes unter
/contacts/admin/*(tenant-scoped, crm.admin-gated) statt Plattform-Admin-Host. - UI: minimale Inline-Swap-UI (kein Subframe) — finale Optik via Davids
D-CRM(Designer-first). - 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), inapps/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.tsxentfernt; 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:i18ngrü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 aufcrm-basic-Entitlement, Muster wie dashboard/email-marketing-interim-smoke. - D20 Hot-Swap-Drill (M017):
createCrmInterimFixturePage()in@hivegrid/ui-mock(deterministische typisierteKontaktListVM, VM-as-Prop) inverify:ui-hot-swapverdrahtet;pnpm run test:hot-swapgruen. - D21 Interim-Visual-Baseline (M016): CRM in
verify:ui-mock-visualregistriert, Baselinepackages/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-visual124 passed. - Proof:
verify:ui-visual(124 passed) ·verify:ui-hot-swap+test:hot-swapgruen · ui-mock-Suiten 49 passed ·pnpm typecheckexit 0 ·verify:i18nexit 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-P6aktualisiert <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) sowieposition,erreichbarkeit(Ansprechpartner-Felder). Alle nullable, keine Semantik-Änderung an bestehenden Spalten.KontaktTelefon: neuestyp(haupt/durchwahl/mobil/fax, Defaulthaupt) plus EnumKontaktTelefonTyp. S02 fragt nach „Durchwahl“ und „Mobil“; das ist eine Art von Nummer, kein Paar weiterer Skalare anKontakt— 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.
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.CustomFieldDatentypum 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.