mirror of
http://172.20.10.11:3000/gitadmin/INSIGHT-MVP.git
synced 2026-06-24 23:56:40 +02:00
docs: add CRM expert briefing with phased task plan to INSIGHT-CRM.md
Define 4-phase execution plan for CRM backend developer: - Phase 1 (now): Schema fields, Owner m:n, Lost reason, Redis events - Phase 2 (after): Custom Fields, Data Enrichment, Import, Permissions - Phase 3 (blocked by Core OAuth): Office 365 Email/Calendar/Tasks/Export - Phase 4 (nice-to-have): Vision API scan, Reporting dashboards Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Thomas Reitz
parent
69f032a3d8
commit
7d8847fafa
1 changed files with 130 additions and 0 deletions
|
|
@ -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`*
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue