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

90 lines
9.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# R-P7 · P7 Lead-Inbox
| | |
|---|---|
| **Typ** | Dev (Code) |
| **Owner** | Raffael |
| **Phase** | P7 — Lead-Inbox |
| **Cycle/Fenster** | W2 — Plattform & CRM (Demo 1) · 2026-06-25 → 2026-06-26 · Gate W2 (Noah-Demo #1) |
| **Status** | geplant |
## Abhängigkeiten & Parallelität
- **Blocked by:** `R-P6` (CRM-Kern — Kontakt/Activity/Tag/CustomFields; Code fertig, Plane temporär On Hold), `R-REFIT` (ER-Modell-Re-Fit, Pivot AD-20 — ✅ erledigt 16.06.), `D-P7` (Screens fehlen; Backend-only-Slice erlaubt)
- **Blocks:** `R-P8a` (Auto-Projekt verbraucht `lead.qualified`), `AK-P16c` (Form → Lead), **Demo 1**
- **Sequenz (Raffaels Kern-Kette):** strikt sequenziell — `R-P6 → R-P7 → R-P8 → R-P9 → R-P11/P12/P13`. P7 ist Glied 2.
- **Läuft parallel zu:** Akeshans Module dieses Fensters (`AK-P14`/`AK-P15`/`AK-P16` Email/Telefonie/Forms — liefern später Lead-Quellen-Adapter). Schema-Trennung nach **AD-21**: jedes Modul eigene `prisma/schema/*.prisma`, `db push` lokal, Migration beim Merge.
## Was wir bauen
Den **Lead-Triage-Arbeitsplatz**: eingehende Leads aus allen Quellen (Form, eingehende E-Mail, AirCall-Inbound, manueller Eintrag, Custom-Quellen) landen automatisch angelegt in einer Inbox, werden gegen Spam/Anomalien geschützt, sind auswertbar und per Workflow weiterverarbeitbar. **Pivot-Vorrang (AD-20):** Lead ist die **Vorstufe des `Projekt`-Kerns** — bei `weiterverarbeitung_freigabe = ja` entsteht **Lead → Projekt** (kein Contact-Promotion, **kein 4-Optionen-Modal**). Relevante Lead-Daten werden ins Projekt vererbt (`konvertiert_projekt_id`); der **Kontakt wird separat verknüpft** (`verknuepfter_kontakt_id` — neuer oder bestehender). Das `lead.qualified`-Event ist Extension-Point für P8 (Auto-Projekt M049).
## Benötigte Screens (Backend bedient — Design liefert `D-CRM`, Lead-Cluster im selben Paket wie P6 → Demo #1)
| Screen [Route] | Kern-Inhalt |
|---|---|
| Lead-Inbox [`/leads`] | Triage-Tabelle/Karten + Filter (Status [Default new+qualified]/Quelle/Verantwortlicher inkl. „Nicht zugewiesen"/Eingegangen-Range/Tags/Lead-Custom-Felder) + Toggles (Spam ausblenden / Konvertierte einblenden) + Inline-Quick-Actions (Zuweisen/Status/**Zu Projekt machen**/Spam) + Bulk + Real-time-Refresh + Marker (Duplikat/Spam-Verdacht/Auto-promoviert) |
| Lead-Detail [`/leads/:id`] | Inline-Edit Stammdaten, Quellen-Detail, **Weiterverarbeitungsfreigabe (ja/nein/unklar)**, Spam-Score + Klartext-Begründung, Match-Hinweise (Email/Telefon/Soft-Match Name+Adresse), Re-Submission-Verlauf, Status-Wechsler, DSGVO-Lösch-Countdown, Triage-Quick-Actions, Sub-Sektionen (Konversation/Activity/Custom-Felder) |
| Lead → Projekt [bei Freigabe, **kein Modal-Zwang**] | Daten-Vererbungs-Vorschau, Ziel-Pipeline + Start-Status wählen, **Kontakt separat verknüpfen** (neu ODER bestehend, Match-Hinweis), Mängel-Banner bei fehlenden Pflichtdaten — **ersetzt das alte Promotion-Modal** |
| Lead-Statistiken [`/leads/statistics`] | KPI-Kacheln (Eingegangen, Konversion Lead→Projekt/Lead→Won, Reaktionszeit, Spam-Quote, Open >24h), Aufschlüsselung (Quelle/Verantwortlicher/Tag/Wochentag/Status), Trends — permission-aware (`leads.read_all`) |
| Quellen-Verwaltung [`/admin/lead-sources`] · Anti-Spam-Settings [`/admin/lead-anti-spam`] · Manueller Eintrag [`/leads/new`] | Custom-Quelle + Webhook-URL/Token; Rate-Limits/Anomalie/Quarantäne/Auto-Lösch-Frist; manuelle Anlage mit Inline-Match-Check |
## Definition of Done
- [x] Triage-Liste server-seitig: filter / sort / cursor-paginate (50/Page) + Quick-Actions + Bulk + Realtime-Refresh (SSE)
- [x] **Multi-Quellen-Auto-Anlage** (Form/Email/AirCall/manuell/Custom) mit `lead.created`- + `lead.qualified`-Events
- [x] **Lead → Projekt** bei `weiterverarbeitung_freigabe=ja` (Daten-Vererbung `konvertiert_projekt_id`, Kontakt separat via `verknuepfter_kontakt_id`, **kein Promotion-Modal**, AD-20/E4)
- [x] Status-Workflow (new|qualified|converted|lost|spam) mit definierten Übergängen + **DSGVO-Auto-Lösch-Cron** (spam 30 T, lost konfigurierbar, 0 = nie)
- [x] Anti-Spam: Rate-Limiting/Anomalie-Detection (10×-Spike → Auto-Pause), Quarantäne-Modus, Tenant-Admin-Notification bei Auto-Pause
- [x] `lead.qualified`-Event als Extension-Point für P8 (Auto-Projekt M049)
- [x] Statistiken-Page (KPI-Kacheln, Quellen-Aufschlüsselung, Trends) — permission-aware
- [x] Konnektor `tenantHasModule('leads')` (Sidebar + Routes + Actions gated)
- [x] `leads.*`-Permission-Bundle (read_own/read_all/write/delete/admin) + serverseitiger Owner-Filter (nicht-eigene Leads bei `read_own` → **404 statt 403**)
## Technische Bausteine
- **Entities** (eigene `prisma/schema/leads.prisma`): `Lead` (quelle, quelle_detail, status, **weiterverarbeitung_freigabe**, vorname/nachname/email/telefon, rohdaten JSONB, spam_score, `konvertiert_projekt_id`, `verknuepfter_kontakt_id`), `LeadSource` (System/Custom, Webhook-Token), Anti-Spam-Konfig. `crm.prisma` (Kontakt/Activity/Tag/CustomField) und später `projekt.prisma` nur über Relationen berühren (AD-21).
- **RLS** auf allem Tenant-bezogenen (AD-1); `[Soft-Delete]` auf Lead; DSGVO-Auto-Lösch-Cron.
- **Activity** (aus P6) als append-only Event-Quelle; `lead.created`/`lead.qualified` als Automation- + P8-Extension-Points.
- **Konnektor** `tenantHasModule('leads')` gated Sidebar/Routes/Actions.
- `is_demo_data`-Flag auf seedbaren Quellen/Demo-Leads (Bulk-Lösch beim Echt-Start).
- Lead → Projekt schreibt nur Vererbungs-Felder; **keine eigene Promotion-Entität** (AD-20).
## Quellen (granular)
- `ENTITY-MODEL.md` → **Domäne 5: Projekt-zentrischer CRM-Kern** (Lead-Zeile + Lead→Projekt) — 🔴 **Pivot-Vorrang (AD-20)**: kein Promotion-Modal, `weiterverarbeitung_freigabe`, `konvertiert_projekt_id`/`verknuepfter_kontakt_id`
- `REQUIREMENTS.md` → `REQ-lead-inbox-liste`, `REQ-lead-quellen-auto-anlage`, `REQ-lead-status-workflow`, `REQ-lead-anti-spam`, `REQ-lead-statistiken`, `REQ-lead-permissions`, `REQ-lead-projekt-konvertierung` (Phase 6/7)
- `ROADMAP.md` → Phase 7 (+ Pivot-Note) · `PHASE-SOURCES.md` → P7
- `designer-briefs/P07-lead-inbox.md` (Screens + UI-Elemente, Pivot-Vorrang-Hinweis)
- `_bmad-output/specs/M02-lead-inbox.md` (⚠ teils pre-pivot: „promovieren zu Contact"/4-Optionen-Modal überholt — ENTITY-MODEL hat Vorrang)
## Dev-Nachzug (nach Davids `D-CRM`-Delta)
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
- [x] Plane-Ticket `R-P7` aktualisiert
## Umsetzung (2026-07-01) — Backend-only ohne D-P7-Screens
Arbeitsstand auf `feat/R-P7-lead-inbox`: Ohne finale Subframe-/David-Screens wurde der technisch selbst machbare Kern vorgezogen, bewusst mit funktionaler Minimal-UI statt finaler Optik.
**Gebaut:**
- `prisma/schema/leads.prisma` mit `InboxLead`, `LeadSource`, `LeadAntiSpamConfig`; Name bewusst `InboxLead`, weil `marketingLeads.prisma` bereits ein operator-seitiges `Lead`/`LeadStatus` besitzt.
- RLS-Rollout-Artefakt `prisma/rls/leads-isolation.sql` + `TENANT_SCOPED_MODELS`-Nachzug.
- `leads.*` Permission-Bundle + explizite Default-Rollen, Feature-Gate `leads`, Blueprint/Sidebar/Route-Handles.
- Lead-Service mit tenant-scoped `withTenantRLS()`, `read_own` Owner-Filter, Cursor-Liste, Status/Bulk, manuelle Anlage, Quellen-Verwaltung, Statusmaschine, Workflow-Outbox-Events, Anti-Spam-Konfig, Rate-/Spike-Erkennung, Quarantäne/Spam-Markierung, Auto-Pause + Admin-Notification, Statistik-Aggregate.
- Ingestion-Adapter für Form, E-Mail, AirCall und Custom (`leadIngestionAdapters.server.ts`) plus manuelle Route.
- Minimal-Routes: `/leads`, `/leads/new`, `/leads/:id`, `/leads/statistics`, `/leads/events`, `/admin/lead-sources`, `/admin/lead-anti-spam`.
- Worker-Retention-Cron `lead-retention-sweep` für `autoDeleteAt` (spam 30 Tage; lost per Tenant-Konfig; 0 = nie).
- Pure View-Model `packages/view-models/src/leads/lead-list.vm.ts` + Unit-Test.
**DoD-Stand:** 9/9 = 100 % done auf R-P7-Code-/Contract-Ebene ohne finale D-P7-Screens.
- [x] Triage-Liste: serverseitig filter/sort/cursor + Status-Quick-/Bulk-Actions + SSE-Endpoint gebaut; finale Screen-Optik bleibt D-P7-Nachzug.
- [x] Multi-Quellen: dedizierte Adapter für Form/E-Mail/AirCall/Custom + manuell; `lead.created` und `lead.qualified` gehen über Workflow-Outbox.
- [x] Lead → Projekt: Conversion-Request + Abschluss-Contract `completeLeadProjectConversion(projectId)` setzt `konvertiertProjektId` und `verknuepfterKontaktId`; echte Projektanlage bleibt bewusst P8, keine P7-Schema-Vorwegnahme.
- [x] Status-Workflow: definierte Übergänge, terminale Status geschützt, Spam-30T und Lost-Retention-Konfig via `autoDeleteAt`, Worker-Cron gebaut.
- [x] Anti-Spam: Heuristik + Rate-Limits + IP-/Source-Limits + 10x-Spike-Auto-Pause + Tenant-Admin-Notification + Quarantäne/Spam-Modus.
- [x] `lead.qualified`: Workflow-Outbox-Event als P8-Extension-Point gebaut.
- [x] Statistiken-Page basisfähig und permission-aware.
- [x] Konnektor `tenantHasModule('leads')` mit Sidebar + Routes + Actions gated.
- [x] `leads.*` Permission-Bundle + Owner-Filter (`read_own` → nicht sichtbare Leads via 404).
**Proof aktuell:** `pnpm typecheck`, `pnpm lint`, `pnpm test` (545 Testdateien / 3509 Tests grün), `pnpm verify:i18n`, `pnpm verify:cross-cutting-models`, `pnpm exec prisma validate`, Worker-/Queue-Typecheck und gezielte Tests grün (`leadService`, `lead-retention-cron`, `lead-list.vm`, `queue producers`, Entitlements, Blueprint, Permission-Seed, Sidebar, indexed-entities). `pnpm exec prisma db push` lokal blockiert, weil die Dev-DB auf `localhost:6432` nicht erreichbar war (P1001).
**Plane:** Kommentar `14f9e801-b02a-42ac-acb4-d861cea49926` geschrieben und Ticket auf `Blocked / On Hold` gesetzt, weil finale D-P7-Screens und echte Projektanlage in P8 außerhalb des R-P7-Code-DoD liegen.
**Offen außerhalb R-P7-Code-DoD:** D-P7 Screens/Subframe-Delta und echte Projektanlage im P8-Projektmodell. P7 greift P8 nicht per eigener Projekttabelle vor.