Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/R-P6.md
T
2026-07-08 16:15:37 +02:00

92 lines
9.5 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 |
## 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)
- `_bmad-output/specs/M01-crm-kern.md` (⚠ teils pre-pivot — ENTITY-MODEL hat Vorrang)
## 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).
## Dev-Nachzug (nach Davids `D-CRM`-Delta)
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
- [ ] Plane-Ticket `R-P6` aktualisiert