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

9.5 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

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)
  • _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