155 lines
15 KiB
Markdown
155 lines
15 KiB
Markdown
# 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** | Done (Code + Interim-UI + Test-Tail; finale Optik = design-nachzug) |
|
||
|
||
**🎨 design-nachzug: offen** (seit 2026-07-08) — Interim-UI aus `~/ui` steht (alle 7 Lead-Screens auf `~/ui`, AD-28); finale Subframe-Optik aus `D-P7` ausstehend.
|
||
|
||
## 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)
|
||
- `designer-briefs/P07-lead-inbox.md` (Screens + UI-Elemente, Pivot-Vorrang-Hinweis)
|
||
|
||
## Dev-Nachzug (nach Davids `D-CRM`-Delta)
|
||
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
|
||
- [ ] REQUIREMENTS/ROADMAP 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.
|
||
|
||
## Interim-UI-Nachzug (AD-28, 2026-07-08 — Akeshan)
|
||
|
||
Die R-P7-Erstumsetzung lieferte Backend/Contracts + eine **funktionale Minimal-UI** (Inline-JSX,
|
||
kein `~/ui`) und hatte zwei echte UI-Lücken. Nachgezogen (Branch `feat/AK-crm-lead-interim-ui`):
|
||
|
||
- **4 fehlende View-Models** gebaut (`packages/view-models/src/leads/`): `lead-detail`,
|
||
`lead-statistics`, `lead-source-admin`, `lead-anti-spam` — pure Builder über die bestehenden
|
||
`leadService`-Shapes, **kein Backend-/Schema-Change**. Statistik rendert nur die vom Service
|
||
gelieferten Aggregate (total/open/converted/spam + by-source/by-status); die reicheren
|
||
Brief-Aufschlüsselungen (Reaktionszeit, pro-Verantwortlichem, Wochentag, Trend-Charts) sind
|
||
**nicht erfunden** → getrackter Nachzug.
|
||
- **Alle 7 Lead-Screens** als AD-28-Interim-Screens aus `~/ui` (`apps/web/app/components/screens/leads/`):
|
||
`LeadInboxPage` (Triage, Marker, Filter, Quick-/Bulk-Status, SSE-href), `LeadDetailPage`
|
||
(Inline-Edit + Status + **Lead→Projekt** kein Modal-Zwang + DSGVO-Frist), `LeadStatisticsPage`
|
||
(KPI-Kacheln), `LeadNewPage`, `LeadSourcesAdminPage`, `LeadAntiSpamAdminPage`. Die 2 Admin-Routen
|
||
(`/admin/lead-sources`, `/admin/lead-anti-spam`) existierten auf `main` bereits (Inline-JSX) und
|
||
wurden auf die Screens umgestellt.
|
||
- **Proof:** Commits `5114c13fa` (VMs), `60292758f` (Inbox/Detail/Statistik/New), `756332f18`
|
||
(Source/Anti-Spam-Admin); `pnpm --filter @hivegrid/web typecheck` + `verify:i18n` grün;
|
||
6 VM-Unit-Tests + 14 Screen-Unit-Tests grün. i18n-Keys de+en ergänzt.
|
||
- **%-Stand Interim-UI:** Screens + 4 VMs + Unit-Tests (D18) = **selbst machbar erledigt**. Offen
|
||
(CI-Territorium, Windows-blockiert): e2e-Smoke `tests/e2e/leads.spec.ts` (D19), `ui-mock`-Renderer
|
||
+ Interim-Visual-Baseline (D20/D21). Echte Projektanlage bleibt **P8**.
|
||
- **Finale Subframe-Optik** = getrackter Nachzug (`design-nachzug`), nicht Done-blockierend.
|
||
|
||
## Audit + Restarbeit (2026-07-17 — Akeshan, `/audit-ticket`)
|
||
|
||
**Befund:** Der Code-Kern (9/9 Doc-DoD) hielt der Prüfung stand — Service, Adapter, Statusmaschine,
|
||
Anti-Spam, Retention-Cron (RLS-gebunden via `withTenantRLS` pro Tenant, Post-Cutover-fest),
|
||
Permissions, Feature-Gate, Search-Index, Audit/Activity alle real belegt. Aber gegen die volle
|
||
AD-28-Interim-Messlatte fehlten **5 nie erfasste DoD-Punkte** (real ~64 % statt gemeldeter 100 %):
|
||
|
||
- [x] **(Nachtrag) Admin-Routen erreichbar** (DoD B6/B8): **Regression durch PR #62** (`5fe3a2c79`,
|
||
09.07., „remove legacy tenant route surfaces" via d0fb6ce83) — die Routen `/admin/lead-sources` +
|
||
`/admin/lead-anti-spam` und die `leads.admin`-Nav-Links waren kommentarlos gelöscht, die Screens
|
||
verwaist (Testmatrix US-LEAD-005 führte es als Gap/`DORMANT`, keine Produktentscheidung).
|
||
**Wiederhergestellt** gegen die heutigen Screens/VMs inkl. Nav-Links + Screen-Tests.
|
||
- [x] **(Nachtrag) Breadcrumb `/leads/:id`** (DoD B9): `handle.breadcrumbKey = "leads.detail.title"`
|
||
nach `calls.$id`-Muster, i18n de+en.
|
||
- [x] **(Nachtrag) D19 e2e-Smoke:** `tests/e2e/leads-interim-smoke.spec.ts` (Login → `/leads` →
|
||
manueller Eintrag; Locked/fehlende Permission skippen sauber). Der bestehende
|
||
`platform-leads.smoke` deckt nur die Operator-`AdminLead`-Domäne ab, nicht `InboxLead`.
|
||
- [x] **(Nachtrag) D20 Hot-Swap-Drill:** `createLeadInterimFixtureViewModel/-Page` in
|
||
`@hivegrid/ui-mock` (echter `buildLeadListVM`, Marker duplicate/spam/converted) + M017-Drill in
|
||
`scripts/verify-ui-hot-swap.ts`.
|
||
- [x] **(Nachtrag) D21 Interim-Visual-Baseline:** `r-p7-leads-interim.{mock.ts,html,snapshot.json}`
|
||
in `packages/ui-mock/visual-baseline/` + `verify-ui-mock-visual` (124 → 127 Checks), als
|
||
**interim** markiert — Re-Baseline beim D-P7-Nachzug.
|
||
|
||
**Weitere Korrekturen:** veralteter „RLS deferred"-Kommentar in `leads.prisma` (RLS ist seit
|
||
Cutover `20260713190000` scharf). **Undokumentierter Zuwachs aus PR #62:** `/leads/board`
|
||
(`LeadBoardPage` + `lead-board.vm`) existiert zusätzlich zu den 7 Ticket-Screens — hier nur
|
||
vermerkt, nicht Ticket-Scope.
|
||
|
||
**Proof:** Branch `feat/r-p7-interim-test-tail` (Commits `a1555bd20` Admin-Routen, `2af8f5778`
|
||
Breadcrumb, `915aa7a5e` Prisma-Kommentar, `a4a8ebd08` D19, `7b059d013` D20, `0d68c3151` D21;
|
||
setzt auf dem R-P6-Test-Tail-Harness aus PR #151 auf). Lokal grün: web/ui-mock typecheck,
|
||
`verify:i18n`, `verify:sidebar-routes`, `verify:cross-cutting-models`, `test:hot-swap`,
|
||
`verify-ui-mock-visual` (127 passed), ui-mock 51 Tests, Lead-Screen-Tests 23, `prisma validate`.
|
||
|
||
**%-Stand: 14/14 DoD = 100 %** (9 Doc-DoD + 5 nachgetragene) — Rest ist `design-nachzug` (D-P7).
|
||
Sichtbar lokal via `pnpm dev:local`: `/{tenant}/leads` (Inbox inkl. Admin-Links), `/{tenant}/admin/lead-sources`,
|
||
`/{tenant}/admin/lead-anti-spam`; Screens unter `apps/web/app/components/screens/leads/`.
|