# 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.