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

15 KiB
Raw Blame History

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

  • Triage-Liste server-seitig: filter / sort / cursor-paginate (50/Page) + Quick-Actions + Bulk + Realtime-Refresh (SSE)
  • Multi-Quellen-Auto-Anlage (Form/Email/AirCall/manuell/Custom) mit lead.created- + lead.qualified-Events
  • Lead → Projekt bei weiterverarbeitung_freigabe=ja (Daten-Vererbung konvertiert_projekt_id, Kontakt separat via verknuepfter_kontakt_id, kein Promotion-Modal, AD-20/E4)
  • Status-Workflow (new|qualified|converted|lost|spam) mit definierten Übergängen + DSGVO-Auto-Lösch-Cron (spam 30 T, lost konfigurierbar, 0 = nie)
  • Anti-Spam: Rate-Limiting/Anomalie-Detection (10×-Spike → Auto-Pause), Quarantäne-Modus, Tenant-Admin-Notification bei Auto-Pause
  • lead.qualified-Event als Extension-Point für P8 (Auto-Projekt M049)
  • Statistiken-Page (KPI-Kacheln, Quellen-Aufschlüsselung, Trends) — permission-aware
  • Konnektor tenantHasModule('leads') (Sidebar + Routes + Actions gated)
  • 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
  • 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.

  • Triage-Liste: serverseitig filter/sort/cursor + Status-Quick-/Bulk-Actions + SSE-Endpoint gebaut; finale Screen-Optik bleibt D-P7-Nachzug.
  • Multi-Quellen: dedizierte Adapter für Form/E-Mail/AirCall/Custom + manuell; lead.created und lead.qualified gehen über Workflow-Outbox.
  • Lead → Projekt: Conversion-Request + Abschluss-Contract completeLeadProjectConversion(projectId) setzt konvertiertProjektId und verknuepfterKontaktId; echte Projektanlage bleibt bewusst P8, keine P7-Schema-Vorwegnahme.
  • Status-Workflow: definierte Übergänge, terminale Status geschützt, Spam-30T und Lost-Retention-Konfig via autoDeleteAt, Worker-Cron gebaut.
  • Anti-Spam: Heuristik + Rate-Limits + IP-/Source-Limits + 10x-Spike-Auto-Pause + Tenant-Admin-Notification + Quarantäne/Spam-Modus.
  • lead.qualified: Workflow-Outbox-Event als P8-Extension-Point gebaut.
  • Statistiken-Page basisfähig und permission-aware.
  • Konnektor tenantHasModule('leads') mit Sidebar + Routes + Actions gated.
  • 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 %):

  • (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.
  • (Nachtrag) Breadcrumb /leads/:id (DoD B9): handle.breadcrumbKey = "leads.detail.title" nach calls.$id-Muster, i18n de+en.
  • (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.
  • (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.
  • (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/.