184 lines
16 KiB
Markdown
184 lines
16 KiB
Markdown
# 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
|
|
- [ ] `<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.**
|