diff --git a/docs/INSIGHT-CRM.md b/docs/INSIGHT-CRM.md index 1c7ae36..e69d8d6 100644 --- a/docs/INSIGHT-CRM.md +++ b/docs/INSIGHT-CRM.md @@ -1519,4 +1519,134 @@ Button "Nach Outlook exportieren" im CRM-Kontakt (Person). --- +--- + +## 2026-03-12 | Plattform-Admin: Briefing fuer CRM-Backend-Experten + +### Kontext + +Der Architekt hat das Konzeptdokument v1.0 und das Claude Briefing aktualisiert. Es gibt umfangreiche neue Anforderungen fuer das CRM-Modul (Details: siehe Eintrag oben vom gleichen Datum). Dieses Briefing definiert die **Reihenfolge und Abhaengigkeiten** fuer die CRM-Backend-Entwicklung. + +### Aktueller Stand + +Das CRM-Backend (`packages/crm-service/`) hat bereits folgende Module produktiv: + +| Modul | Status | Endpoints | +|-------|--------|-----------| +| Contacts (Person + Company) | Laeuft | CRUD + Suche + Paginierung | +| Deals | Laeuft | CRUD + Pipeline-Zuordnung | +| Pipelines + Stages | Laeuft | CRUD + Stage-Management | +| Activities | Laeuft | CRUD (6 Typen) | +| Industries | Laeuft | CRUD | +| Companies (Standalone) | Laeuft | CRUD + Lexware-Sync | +| Trade Events (Messe-Timer) | Laeuft | CRUD + Active-Filter | +| CRM Settings | Laeuft | Modulverwaltung pro Tenant | + +Das Frontend fuer alle obigen Module ist ebenfalls deployed und funktional. + +### Phasenplan: Was wann zu tun ist + +#### Phase 1 — SOFORT starten (keine Abhaengigkeiten) + +Diese Aufgaben erweitern bestehende Module und koennen sofort umgesetzt werden: + +**1.1 Fehlende Felder im Prisma-Schema ergaenzen** +- Person: `linkedinUrl`, `birthday`, `source` (Enum), `status` (Enum) +- Company: `vatId`, `taxId`, `tradeRegisterNumber`, `registerCourt`, `companySize` (Enum), `deliveryAddress`, `dataEnrichedAt`, `dataEnrichedSource` +- Referenz: Abschnitt A.1 oben fuer vollstaendige Feldliste +- **Achtung:** Bestehende API-Responses und DTOs muessen die neuen Felder enthalten +- **Migration:** `prisma db push` auf dem Server nach Schema-Aenderung + +**1.2 Contact/Deal Owner (m:n Modell)** +- Neue Tabellen: `crm_contact_owners` und `crm_deal_owners` (contact_id/deal_id, user_id, role: OWNER|MEMBER|WATCHER) +- Bei Kontakt-Erstellung: erstellenden User automatisch als OWNER setzen +- Owner-Info in Detail-Responses mitliefern (User-ID + Rolle) +- Endpoints: `POST/DELETE /crm/contacts/:id/owners`, analog fuer Deals +- Referenz: Abschnitt A.3 + A.4 oben + +**1.3 Lost-Grund bei Deals** +- Neue Felder: `lostReason` (Enum: PRICE|TIMING|COMPETITOR|NO_NEED|OTHER) + `lostReasonText` (Freitext) +- Bei Stage-Wechsel zu Lost: lostReason Pflichtfeld +- Referenz: Abschnitt A.4 oben + +**1.4 Redis Pub/Sub Events** +- Events publishen bei: Contact created/updated, Deal stage_changed/won/lost, Activity due_soon +- Key-Prefix: `app:crm:events:*` +- Event-Format: `{ type: 'crm.deal.won', tenantId, entityId, userId, timestamp, payload }` +- Referenz: Abschnitt A.11 oben + +#### Phase 2 — DANACH (neue Features, keine CORE-Abhaengigkeit) + +Nach Abschluss von Phase 1 koennen diese Features **parallel** entwickelt werden: + +**2.1 Custom Fields System** +- DB: `crm_custom_field_defs` + `crm_custom_field_values` (Details in A.6) +- CRUD Endpoints fuer Field-Definitions: `GET/POST/PATCH/DELETE /crm/custom-fields` +- Wert-Speicherung bei Entity Create/Update +- Custom Fields in Entity-Detail-Responses mitliefern +- 8 Feldtypen: Text, Textarea, Zahl, Datum, Dropdown, Mehrfachauswahl, Checkbox, URL + +**2.2 Firmendaten-Anreicherung (Data Enrichment)** +- `POST /crm/companies/:id/enrich` Endpoint +- Paralleler Abruf: Unternehmensregister.de (kostenlos) + North Data API (API-Key pro Tenant) +- Ergebnis als Vorschlag zurueckgeben (Frontend zeigt Vergleich-Modal) +- Admin-Einstellung fuer North Data API-Key +- Referenz: Abschnitt A.2 oben + +**2.3 Kontakt-Import** +- CSV-Import mit Spalten-Mapping (Backend parst, gibt Vorschau zurueck) +- Excel-Import (.xlsx) — gleiche Logik +- vCard-Import (.vcf + ZIP) +- Duplikat-Erkennung via E-Mail +- Referenz: Abschnitt A.7 oben + +**2.4 Berechtigungsmodell** +- Sichtbarkeitsfilter in allen List-Queries: Eigene / Team / Alle +- Konfigurierbar pro Rolle via Tenant-Admin +- Referenz: Abschnitt A.8 oben + +**2.5 Forecast-Endpoint** +- `GET /crm/deals/forecast` — Aggregierter Dealwert pro Stage gewichtet mit Wahrscheinlichkeit +- Referenz: Abschnitt A.4 oben + +#### Phase 3 — SPAETER (abhaengig von CORE OAuth) + +> **BLOCKER:** Diese Features benoetigen die Microsoft 365 OAuth-Integration im Core-Service. +> Der Core-Entwickler arbeitet **parallel** an: OAuth-Flow, `user_integrations`-Tabelle, +> Azure App-Registrierung. Erst wenn das steht, kann Phase 3 beginnen. + +**3.1 E-Mail Tab** — `GET /crm/contacts/:id/emails` (Proxy zu MS Graph API, Redis 5 Min Cache) +**3.2 Kalender Tab** — `GET /crm/contacts/:id/calendar` (Graph API, Redis Cache) +**3.3 Aufgaben Sync** — Bidirektional mit Microsoft To Do (@Cron alle 5 Min, Redis-Lock pro User) +**3.4 Kontakte Export** — `POST /crm/contacts/:id/export-to-outlook` (Graph API) + +Details: Abschnitte B.1–B.4 oben + +#### Phase 4 — NICE-TO-HAVE + +**4.1 Visitenkarten-Scan** — Anthropic Vision API, Rate Limit 50/Tag/Tenant +**4.2 CRM Reporting** — 5 Dashboards + CSV-Export (Pipeline, Aktivitaeten, Kontaktwachstum, Win/Loss, Mitarbeiter-Performance) + +### Wichtige technische Hinweise + +1. **Schema-Abgleich noetig:** Das Ziel-Schema des Architekten (A.10) weicht vom aktuellen Prisma-Schema ab. Aktuell: flaches Contact/Company-Modell. Ziel: `crm_contacts` + `crm_persons` + `crm_companies` Split. **Entscheidung noetig:** Schrittweise migrieren oder Big-Bang-Umbau? + +2. **User-Referenzen:** Contact/Deal-Owner referenzieren `user_id` aus `platform_core`. Keine User-Daten kopieren — bei Bedarf per REST-Call an Core-Service (`GET /api/users/:id`) oder JWT-Payload nutzen. + +3. **Neue Rollen:** Das Berechtigungsmodell (A.8) definiert `team_lead` und `tenant_readonly` — diese Rollen existieren im Core noch NICHT. Abstimmung mit Core-Entwickler noetig. + +4. **Bestehende Frontend-Hooks:** Das Frontend hat bereits React Query Hooks fuer alle bestehenden Endpoints. Neue Endpoints/Felder muessen in `packages/frontend/src/crm/types.ts`, `api.ts` und `hooks.ts` ergaenzt werden — das uebernimmt der Frontend-Entwickler nach Rueckmeldung. + +### Kommunikationsweg + +Bitte fuer jede abgeschlossene Phase einen Eintrag hier in diese Datei schreiben: +- Welche Endpoints sind neu/geaendert? +- Welche Prisma-Migrationen wurden ausgefuehrt? +- Gibt es Breaking Changes an bestehenden APIs? +- Welche Frontend-Anpassungen sind noetig? + +Format: `## YYYY-MM-DD | CRM-Backend: [Betreff]` + +--- + *Bitte neue Eintraege unten anfuegen. Format: `## YYYY-MM-DD | Absender: Betreff`*