Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/R-P7.md
T

155 lines
15 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** | 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/`.