Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/designer-briefs/P07-lead-inbox.md
T
2026-07-08 16:15:37 +02:00

53 lines
7.4 KiB
Markdown

# Designer-Brief · P7 — Lead-Inbox
**Phase:** 7/21 · **Modul:** M02 · **Owner-Dev:** Raffael (R-P7) · **Designer:** David (D-CRM, Lead-Cluster im selben Paket wie P6 → Noah-Demo #1)
**Quellen:** `ROADMAP.md` §Phase 7 (+ Pivot-Note) · `ENTITY-MODEL.md` Domäne 5 (Lead → Projekt) + Kern-Ketten-Diagramm · `SCREEN-MAP.md` §2 (CRM-Cluster) · `REQUIREMENTS.md` (REQ-lead-*) · `_bmad-output/specs/M02-lead-inbox.md`
**Subframe:** Pflicht je Route. Archetypen aus D0 (A2 Liste, A3 Detail, A5 Modal, A6 Settings, KPI-Kit).
> 🔴 **Pivot-Vorrang (AD-20):** Für die Lead-Welt gilt das **`ENTITY-MODEL.md`**, nicht die teils noch pre-Pivot-SCREEN-MAP. Konkret: **Das Lead-Promotion-Modal (4-Optionen-Modal) entfällt** — es wird **Lead → Projekt**. Ein Lead trägt den Datenpunkt **`weiterverarbeitung_freigabe` (ja/nein/unklar)**; bei „ja" entsteht ein `Projekt` (kein Contact-Promotion mehr), und relevante Lead-Daten werden ins Projekt vererbt (`konvertiert_projekt_id`). Der **Kontakt wird separat verknüpft** (`verknuepfter_kontakt_id` — neuer Kontakt oder bestehender), nicht in einem Promotion-Schritt verschmolzen. Status-Enum bleibt `new/qualified/converted/lost/spam`. Wo M02-Spec und SCREEN-MAP §2 noch von „promovieren zu Contact"/„4-Optionen-Modal" sprechen, ist das überholt.
## Was dieses Modul tut (Kurzfassung)
Eingehende Leads aus allen Quellen (Form-Submission, eingehende Email, AirCall-Inbound, manueller Eintrag, Custom-Quellen) landen in einem Triage-Arbeitsplatz, werden automatisch angelegt, gegen Spam/Anomalien geschützt und sind auswertbar. Lead ist die **Vorstufe** des `Projekt`-Kerns: bei Weiterverarbeitungsfreigabe wird der Lead zum Projekt (Lead → Projekt, Domäne 5), der Kontakt separat verknüpft. Das `lead.qualified`-Event ist Extension-Point für P8 (Auto-Projekt M049).
## Benötigte Screens
| Screen [Route] | Kern-Inhalt | Archetyp |
|---|---|---|
| **Lead-Inbox** [`/leads`] | Tabelle/Karten: Identität (Name, sonst Email/Telefon, sonst Quelle+Datum), **Quelle**, Status, Verantwortlicher, Eingegangen (relativ <7 T), letzte Activity, 80-Zeichen-Message-Vorschau · Marker „Mögliches Duplikat" / „Spam-Verdacht" / „Auto-promoviert" · Filter (Status [Default new+qualified], Quelle, Verantwortlicher inkl. „Nicht zugewiesen", Eingegangen-Range, Tags, Lead-Custom-Felder) · Toggle „Spam ausblenden" (Default ein) + „Konvertierte einblenden" (Default aus) · Quick-Actions inline: Zuweisen, Status, **Zu Projekt machen** (bei Freigabe), Spam · Bulk · Real-time-Refresh | A2 + Triage-Akzente |
| **Lead-Detail** [`/leads/:id`] | Stammdaten inline-editierbar · Quellen-Detail (Form-Name/Submission-ID/Submitter-IP bzw. Email-Header bzw. Anruf-Aufzeichnungs-Link) · **Weiterverarbeitungsfreigabe-Feld (ja/nein/unklar)** · Spam-Score mit Klartext-Begründung · **Match-Hinweise** (existierende Kontakte gleiche Email/Telefon, Soft-Match Name+Adresse) mit Direkt-Übergängen · Re-Submission-Verlauf · Status-Wechsler (new/qualified/converted/lost/spam) · DSGVO-Auto-Lösch-Hinweis mit Datum · Triage-Quick-Actions (Annehmen, Antworten, Anrufen, Notiz, Task, Termin) · Sub-Sektionen Übersicht/Konversation/Activity-Stream/Custom-Felder | A3 |
| **Lead → Projekt** [bei Freigabe, kein Modal-Zwang] | Bei `weiterverarbeitung_freigabe=ja`: Projekt aus Lead anlegen · Daten-Vererbungs-Vorschau (welche Lead-Felder ins Projekt fließen) · Ziel-Pipeline + Start-Status wählen · **Kontakt separat verknüpfen** (neuer Kontakt ODER bestehenden zuordnen, Auto-Email/Telefon-Match-Hinweis) · Mängel-Banner bei fehlenden Pflichtdaten (z.B. Name) | A5 — Kern-Moment der Kette! (ersetzt das alte 4-Optionen-Promotion-Modal) |
| Lead-Statistiken [`/leads/statistics`] | KPI-Kacheln (Eingegangen, Konversion Lead→Projekt, Konversion Lead→Won, Reaktionszeit, Spam-Quote, Open-Leads >24h) · Aufschlüsselung nach Quelle/Verantwortlichem/Tag/Wochentag/Status · Trend-Charts mit Vorperioden-Vergleich · Date-Range-Selektor + Vergleichs-Toggle · Drill-Down → vorgefilterte Inbox · permission-aware (Verantwortlichen-Aufschlüsselung nur mit `leads.read_all`) | A2 + KPI-Kit |
| Quellen-Verwaltung [`/admin/lead-sources`] | Quellen-Liste: Name, Typ (System/Custom), 30-Tage-Lead-Count, Status · Custom-Quelle anlegen (Name, Display-Label, optional Default-Verantwortlicher/Default-Tags) · Edit/Archivieren · **Webhook-URL mit Token** (für Fremd-Website-Leads) | A2 / A6 |
| Anti-Spam-Settings [`/admin/lead-anti-spam`] | Hard-Limit pro Quelle/Stunde + pro IP/Stunde · Anomalie-Detection (10x-Spike → Auto-Pause) · Auto-Mark-as-Spam-Heuristiken als Toggles (IP-Blocklist, Disposable-Domain, Honeypot, <3s-Submit) · Quarantäne-Modus vs. Vollständig-Spam-Modus · `lost`-Auto-Lösch-Frist konfigurierbar (0=nie) | A6 |
| Manueller Lead-Eintrag [`/leads/new`] | Vor-/Nachname, Email, Telefon, Message, Quelle (Default manual), Verantwortlicher (Default Self), Tags · Inline-Match-Check beim Tippen | A4 |
*(Lead-Promotion-Modal aus SCREEN-MAP §2 entfällt — ersetzt durch „Lead → Projekt". Kontakt-/Firmen-Listen, Custom-Felder-, Tag-, Duplikat-Admin → P6.)*
## Geplante Features (muss abgedeckt sein)
- [ ] Lead-Inbox als Arbeitsplatz: Status-Filter, Triage-Quick-Actions, Bulk-Operationen, Real-time-Refresh
- [ ] **Lead → Projekt bei Weiterverarbeitungsfreigabe** (kein Contact-Promotion-Modal); Vererbung relevanter Lead-Daten ins Projekt; Kontakt separat verknüpft
- [ ] Multi-Quellen-Auto-Anlage (Form/Email/AirCall-Inbound/manuell/Custom) mit `lead.created`-/`lead.qualified`-Events (Automation + P8-Extension-Point)
- [ ] Status-Workflow (new|qualified|converted|lost|spam) mit definierten Übergängen; DSGVO-Auto-Lösch-Cron (spam 30 T, lost konfigurierbar)
- [ ] Anti-Spam: Rate-Limiting/Anomalie-Detection, Quarantäne-Modus, Tenant-Admin-Notification bei Auto-Pause
- [ ] Statistiken-Page mit KPI-Kacheln, Quellen-Aufschlüsselung, Trends — permission-aware
- [ ] `leads.*`-Permission-Bundle (read_own/read_all/write/delete/admin) mit Owner-Check; nicht-eigene Leads bei `read_own` unsichtbar (404, nicht 403)
## Benötigte UI-Elemente (Liste, KEIN Layout — Anordnung = Davids freie Hand)
Triage-Daten-Tabelle/Karten-Umschalter (sortierbar, cursor-paginiert 50/Page), Filter-Bar (Multi-Select Status/Quelle/Verantwortlicher, Date-Range, Tags, Custom-Feld-Filter), Toggle-Chips (Spam ausblenden / Konvertierte einblenden), Hinweis-Marker (Duplikat/Spam/Auto-promoviert), Inline-Quick-Action-Picker (Zuweisen/Status), Bulk-Action-Toolbar mit Klartext-Bestätigungen, Detail-Panel mit Inline-Edit, Weiterverarbeitungsfreigabe-Auswahl (ja/nein/unklar), Spam-Score-Anzeige mit Begründung, Match-Hinweis-Liste mit Sprung-Links, Re-Submission-Verlauf, DSGVO-Lösch-Countdown-Hinweis, Status-Wechsler, „Lead → Projekt"-Flow (Daten-Vererbungs-Vorschau + Pipeline-/Status-Wahl + separater Kontakt-Verknüpfungs-Picker mit Match), KPI-Kacheln, Bar-/Line-Charts mit Vorperioden-Delta, Drill-Down-Verlinkung, Webhook-URL-Feld mit Copy + Token, Anti-Spam-Toggle-Zeilen, Empty-/Loading-/Fehler-/Permission-Denied-States (Klartext + Lösungs-Knopf).
## Davids Delta (David füllt aus)
- [ ] Überschriebene/geänderte Spec-Punkte:
- [ ] Neue UI/UX-Entscheidungen:
- [ ] Subframe-Screen-Link(s):
- [ ] Offene Fragen an Dev:
## Dev-Nachzug (wir nach Davids Delta)
- [ ] Spec/ENTITY-MODEL an Davids Entscheidungen angepasst:
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen:
- [ ] Plane-Ticket (R-P7) aktualisiert: