526 lines
23 KiB
Markdown
526 lines
23 KiB
Markdown
---
|
||
module: 2
|
||
title: Lead-Inbox / Lead-Management
|
||
phase: 1
|
||
status: detail-spec-draft
|
||
last_updated: 2026-05-08
|
||
session_source: brainstorming-session-2026-05-07-2206.md
|
||
related_lps: [LP-3, LP-4, LP-7, LP-9, LP-10]
|
||
spec_style: requirements-pur
|
||
---
|
||
|
||
# Modul 2 — Lead-Inbox / Lead-Management
|
||
|
||
> 🔴 **Pivot-Hinweis (Stand 16.06.2026) — diese Spec ist teilweise pre-pivot; verbindlich ist `.planning/ENTITY-MODEL.md` (AD-20, LOCKED).** Folgendes gilt projekt-zentrisch und ersetzt abweichende Stellen unten:
|
||
> - **Lead → Projekt** bei `weiterverarbeitung_freigabe=ja`. Wo unten „Promotion zu Contact" / „Promotions-Modal" / „Bulk-Promote" / „Lead → Deal/Contact" steht: Lead konvertiert zu einem **Projekt** (`konvertiert_projekt_id`); der **Kontakt wird separat verknüpft** (`verknuepfter_kontakt_id`). Es gibt **kein 4-Optionen-Modal** mehr.
|
||
> - **„Deal" existiert nicht als Entität** (ein `Projekt`-Kern; „Deal"/„Auftrag" = Pipeline-Typen). Statistik „Konversion Lead→Deal" = **Lead→Projekt (gewonnen-Status der Sales-Pipeline)**.
|
||
> - **Kontakt** ist Oberbegriff (Kontakttyp privatperson/organisation, Label „Organisation"). Custom-Felder am Lead pro Pipeline via `PipelineFieldConfig` schaltbar.
|
||
> - **KWP komplett v2**, PWA-only (AD-17), v1 DE-only.
|
||
|
||
> **Detail-Spec gemäß LP-9.** Inbox-Funktionalität für unqualifizierte Eingänge (Forms, Email, WhatsApp, Telefon, Manuell). Löst HubSpot-Lead-Komponente ab (LP-7). Lead-Entität selbst ist in Modul 1 spec'd; Modul 2 fokussiert auf Listen-Workflow, Triage, Statistiken, Auto-Konvertierung und Integration in Vertriebs-Cluster.
|
||
|
||
## Themenblöcke
|
||
|
||
```
|
||
A. Scope-Abgrenzung gegenüber Modul 1
|
||
B. Menü-Struktur und Routes
|
||
C. Listen-View (Inbox)
|
||
D. Detail-View (Triage + Promotion)
|
||
E. Quellen-Erkennung & Auto-Anlage
|
||
F. Lead-Status-Workflow
|
||
G. Bulk-Actions
|
||
H. Statistiken
|
||
I. Activity-Stream-Integration
|
||
J. Permissions-Anwendung
|
||
K. Klartext-Hinweise / -Fehler
|
||
L. Phase 2 / spätere Features
|
||
```
|
||
|
||
---
|
||
|
||
## Block A — Scope-Abgrenzung gegenüber Modul 1
|
||
|
||
**In Modul 1 (CRM-Kern) spec'd:**
|
||
- `Lead`-Datenmodell (Felder, Status-Enum, FKs)
|
||
- Lead-Detail-View Grundgerüst
|
||
- **Lead → Projekt-Konvertierung** (+ separate Kontakt-Verknüpfung) inkl. Match-Hinweise *(pre-pivot: „Promotion-Logik Lead → Contact + ggf. Company + ggf. Deal" — AD-20)*
|
||
|
||
**In Modul 2 (dieses Dokument) spec'd:**
|
||
- Inbox als Arbeitsplatz: Listen-Workflow, Filter, Bulk-Actions
|
||
- Triage-Funktionen (Annehmen, Zuweisen, Priorisieren, Spam-Markierung)
|
||
- Quellen-Erkennung und Auto-Anlage aus eingehenden Kanälen
|
||
- Status-Workflow inklusive DSGVO-Auto-Lösch
|
||
- Lead-Statistiken-Page
|
||
- Anti-Spam / Anomalie-Detection bei Lead-Storm (EC-1-Erweiterung)
|
||
- Permissions-Bundle `leads.*`
|
||
|
||
**Nicht in Modul 2:**
|
||
- Lead-Datenmodell selbst (Modul 1)
|
||
- Form-Submissions als Quelle (Modul 5 — Form-Builder; Modul 2 konsumiert nur das Resultat)
|
||
- Eingehende Mail-Auto-Matching (Modul 9)
|
||
- Lead-Score-KI (geparkt, Phase 2)
|
||
- CSV-Import (Anti-Liste / Phase 2 — geparkte Migration)
|
||
|
||
---
|
||
|
||
## Block B — Menü-Struktur und Routes
|
||
|
||
**Sidebar-Hauptpunkt:** *CRM* → Sub-Punkt *Leads* (Default-Anzeige der Inbox).
|
||
|
||
**Routen:**
|
||
|
||
```
|
||
/{tenant}/leads → Lead-Inbox (Listen-View)
|
||
/{tenant}/leads/new → Manueller Lead-Eintrag
|
||
/{tenant}/leads/:id → Lead-Detail (mit Promotion-Modal)
|
||
/{tenant}/leads/statistics → Lead-Statistiken
|
||
/{tenant}/admin/lead-sources → Quellen-Verwaltung (Custom-Quellen)
|
||
/{tenant}/admin/lead-anti-spam → Anti-Spam-/Rate-Limit-Settings (tenant-weit)
|
||
```
|
||
|
||
**Permission-Anforderungen:**
|
||
- `/leads`, `/leads/:id` → `leads.read_own` oder `leads.read_all`
|
||
- `/leads/new`, Schreib-Operationen → `leads.write`
|
||
- `/leads/statistics` → `leads.read_all` (eigene Vertriebler-Sicht über `read_own`-Filter)
|
||
- `/admin/lead-sources`, `/admin/lead-anti-spam` → `leads.admin` oder `tenant.admin`
|
||
|
||
---
|
||
|
||
## Block C — Listen-View (Inbox)
|
||
|
||
### Zu zeigende Daten pro Eintrag
|
||
|
||
- Lead-Identität (Name falls vorhanden, sonst Email/Telefon, sonst Quelle + Datum als Fallback)
|
||
- Quellen-Anzeige (Form-Name / Email-Adresse / Telefonnummer / Manueller Eintrag / Import / Referral)
|
||
- Status (`new | qualified | converted | lost | spam`)
|
||
- Verantwortlicher (User)
|
||
- Eingegangen-Datum (relativ < 7 Tage, sonst absolut)
|
||
- Letzte Aktivität / Status-Wechsel
|
||
- Kurz-Vorschau der Message (max. 80 Zeichen)
|
||
- Hinweis-Marker:
|
||
- „Mögliches Duplikat" (wenn Email-/Telefon-Match zu existing Contact)
|
||
- „Spam-Verdacht" (Anomalie-Detection-Treffer)
|
||
- „Auto-promoviert" (durch Automation)
|
||
|
||
### Benötigte UI-Elemente
|
||
|
||
- Tabellarische oder Karten-basierte Listen-Anzeige (Designer-Wahl, beide praktikabel)
|
||
- Such-Funktion (Volltext über Name/Email/Telefon/Message)
|
||
- Filter-Komponenten:
|
||
- Status (Multi-Select; Default: `new` + `qualified`)
|
||
- Quelle (Multi-Select)
|
||
- Verantwortlicher (Multi-Select; Sonderwert „Nicht zugewiesen")
|
||
- Eingegangen zwischen (Date-Range-Picker)
|
||
- Tags (über Modul 1 Tag-System)
|
||
- Custom-Felder (Lead-spezifische Custom-Felder aus Modul 1, Block F)
|
||
- Toggle „Spam ausblenden" (Default ein)
|
||
- Toggle „Konvertierte einblenden" (Default aus)
|
||
- Sortierung pro Spalte (Default: Eingegangen-Datum absteigend)
|
||
- Bulk-Auswahl (Checkboxes pro Zeile + Master-Checkbox)
|
||
- Pagination (Cursor-basiert, „Mehr laden", 50 pro Page)
|
||
- Spalten-Konfiguration (User-spezifisch persistiert)
|
||
- Quick-Action-Funktionen pro Zeile ohne Detail-Drilldown:
|
||
- Zuweisen (Inline-Picker)
|
||
- Status setzen (Inline-Picker)
|
||
- Zu Contact promovieren (öffnet Promotions-Modal)
|
||
- Spam markieren
|
||
|
||
### Operationen
|
||
|
||
- Filter anwenden / kombinieren / als „Gespeicherte Ansicht" speichern (User-spezifisch, Phase 1 minimal: max. 5 gespeicherte Ansichten)
|
||
- Quick-Actions pro Zeile (siehe oben)
|
||
- Klick auf Zeile → Detail-View
|
||
- Bulk-Actions (siehe Block G)
|
||
- Export (gefilterte Auswahl als CSV) — Permission `leads.admin`
|
||
|
||
### Performance-Anforderungen
|
||
|
||
- Server-side-Filter (kein Client-side-Filtern)
|
||
- Index auf `tenant_id, status, created_at DESC`
|
||
- Index auf `tenant_id, assigned_to_user_id, status`
|
||
- Trigram-Index auf `email`, `phone` (normalisiert), `last_name` für Fuzzy-Suche
|
||
- Real-time-Refresh bei neuem Lead (Server-Sent-Event oder Polling alle 30 Sek; Designer-Hinweis nicht nötig, technische Wahl)
|
||
|
||
---
|
||
|
||
## Block D — Detail-View (Triage + Promotion)
|
||
|
||
> **Lead-Datenmodell und Promotions-Modal sind in Modul 1 spec'd.** Modul 2 ergänzt die Triage-Funktionen.
|
||
|
||
### Zu zeigende Daten zusätzlich zu Modul 1
|
||
|
||
- Quellen-Detail (z.B. Form-Name + Submission-ID + Submitter-IP / Email-Header / Anruf-Aufzeichnungs-Link)
|
||
- Anti-Spam-Score (falls verfügbar) mit Klartext-Begründung
|
||
- Match-Hinweise:
|
||
- Existing Contact mit gleicher Email
|
||
- Existing Contact mit gleicher Telefonnummer
|
||
- Soft-Match (Name + Adresse / Firma)
|
||
- Bisheriger Verlauf falls Re-Submission (mehrere Form-Eingänge derselben Email innerhalb 30 Tagen)
|
||
- Verknüpfungen falls schon vorhanden (Antwort-Mails, Notizen, Tasks)
|
||
|
||
### Benötigte UI-Elemente
|
||
|
||
- Triage-Action-Funktionen:
|
||
- Annehmen (Status `new` → `qualified`)
|
||
- Zu Contact promovieren (öffnet Modul-1-Promotions-Modal)
|
||
- Spam markieren
|
||
- Verloren markieren
|
||
- Verantwortlichen zuweisen / ändern
|
||
- Antwort senden (Email/WhatsApp falls Daten vorhanden — Compose öffnet Modul-9-Editor)
|
||
- Anrufen (Click-to-Call via Modul 12)
|
||
- Notiz hinzufügen
|
||
- Aufgabe anlegen (mit Lead-Verknüpfung — Modul 26)
|
||
- Termin vorschlagen (öffnet Booking-Slot-Picker — Modul 6)
|
||
- Anzeige der Quellen-Detail-Sektion (Form-Submission-Felder roh, Email-Header, etc.)
|
||
- Anzeige der Match-Hinweise mit direkten Übergängen („Diesen Contact öffnen", „Dorthin promovieren")
|
||
- Activity-Stream (gefiltert auf Lead-Subject) — siehe Block I
|
||
|
||
### Operationen
|
||
|
||
- Status-Wechsel (siehe Block F)
|
||
- Promotion (in Modul 1 spec'd)
|
||
- Antwort / Anruf / Termin / Notiz / Task
|
||
- Lead-Stamm-Daten editieren (Inline-Edit pro Feld)
|
||
- Hard-Delete (mit Klartext-Warnung)
|
||
|
||
### Sub-Sections (optional, Designer-Hinweis: Tabs oder Sektionen-Anordnung freie Wahl)
|
||
|
||
- Übersicht (Stamm-Daten + Quelle + Match-Hinweise)
|
||
- Konversation (alle Antwort-Mails / WhatsApp / Anruf-Notizen, chronologisch)
|
||
- Activity-Stream
|
||
- Custom-Felder
|
||
|
||
---
|
||
|
||
## Block E — Quellen-Erkennung & Auto-Anlage
|
||
|
||
### Quellen-Enum (siehe Modul 1 Lead-Modell)
|
||
|
||
```
|
||
form → Form-Builder-Submission (Modul 5)
|
||
email → eingehende Mail an verbundene Mailbox (Modul 9)
|
||
whatsapp → eingehende WhatsApp-Nachricht (Phase 2 — Mail-Stub in Phase 1)
|
||
phone → AirCall-Inbound-Webhook ohne existierenden Contact (Modul 12)
|
||
manual → User-Eintrag in /leads/new
|
||
import → CSV/JSON-Import (Phase 2)
|
||
referral → User markiert Lead manuell als Empfehlung
|
||
other → Catch-All
|
||
```
|
||
|
||
### Auto-Anlage-Pfade
|
||
|
||
**(a) Form-Submission → Lead:**
|
||
- Form-Builder schreibt `Lead` mit `source = form` und `metadata.form_id` + `metadata.submission_id`
|
||
- Match-Check gegen existing Contacts (Email-/Telefon-exakt)
|
||
- Bei Match → Hinweis im Lead-Detail, kein Auto-Merge in Phase 1 (Mensch entscheidet)
|
||
- Trigger für Automation-Engine (`lead.created`-Event)
|
||
|
||
**(b) Eingehende Mail → Lead (Modul 9 Logic):**
|
||
- Modul 9 erkennt: Absender-Email NICHT in Contacts → Lead anlegen mit `source = email`, `message` = Mail-Body-Snippet, `metadata.message_id`
|
||
- Mail bleibt in Inbox + verlinkt zu Lead (bidirektional)
|
||
- Bei Match auf existing Contact → Mail wird Contact zugeordnet, KEIN Lead
|
||
|
||
**(c) AirCall-Inbound-Anruf → Lead (Modul 12 Logic):**
|
||
- AirCall-Webhook mit unbekannter Telefonnummer
|
||
- Lead angelegt mit `source = phone`, `phone` aus Webhook-Payload, `message` = „Anruf eingegangen am [Datum]"
|
||
- Verantwortlicher = AirCall-Empfänger (User-Mapping in Modul 12)
|
||
- Aufzeichnungs-Link in Activity-Stream
|
||
|
||
**(d) Manueller Eintrag:**
|
||
- Route `/leads/new` mit Formular: Vor-/Nachname, Email, Phone, Message, Source (Default `manual`), Verantwortlicher (Default Self), Tags
|
||
- Inline-Match-Check beim Tippen (analog Modul 1)
|
||
|
||
### Quellen-Verwaltung (`/{tenant}/admin/lead-sources`)
|
||
|
||
**Zu zeigende Daten:**
|
||
- Liste aller Quellen-Definitionen (System-Defaults + Custom)
|
||
- Pro Quelle: Name, Typ (System/Custom), Lead-Count letzte 30 Tage, Status
|
||
|
||
**Benötigte UI-Elemente:**
|
||
- Listen-Anzeige
|
||
- Custom-Quelle anlegen (Name, Display-Label, optional: Default-Verantwortlicher, Default-Tags)
|
||
- Edit / Archivieren
|
||
|
||
**Use-Case Custom-Quellen:** Geerkens hat Messe-Stand → Quelle „Messe SHK 2027" → Manuelle Leads landen vorgefiltert mit Default-Tag.
|
||
|
||
---
|
||
|
||
## Block F — Lead-Status-Workflow
|
||
|
||
### Status-Enum (in Modul 1 definiert)
|
||
|
||
```
|
||
new → unbearbeitet, Default bei Anlage
|
||
qualified → manuell als ernsthaft eingestuft, im Auge
|
||
converted → zu Contact promoviert (FKs gesetzt)
|
||
lost → nicht weiterverfolgt (Begründung optional)
|
||
spam → markiert für DSGVO-Auto-Lösch
|
||
```
|
||
|
||
### Übergangs-Regeln
|
||
|
||
| Von | Nach | Trigger |
|
||
|---|---|---|
|
||
| `new` | `qualified` | manuell „Annehmen" oder Automation |
|
||
| `new` | `converted` | Promotion (siehe Modul 1) |
|
||
| `new` | `lost` | manuell mit optionaler Begründung |
|
||
| `new` | `spam` | manuell ODER Anomalie-Detection-Auto-Mark |
|
||
| `qualified` | `converted` | Promotion |
|
||
| `qualified` | `lost` | manuell |
|
||
| `lost` | `qualified` | Re-Engagement (manuell) |
|
||
| `lost` | `spam` | manuell |
|
||
| `spam` | `qualified` | manuell (False-Positive-Reverse) |
|
||
| `converted` | (lock) | Status final, nicht änderbar; Hard-Delete des Contact löscht auch konvertierten Lead-Stub |
|
||
|
||
### DSGVO-Auto-Lösch
|
||
|
||
- Leads in `spam` → Hard-Delete nach 30 Tagen (täglicher Cron-Job)
|
||
- Leads in `lost` → Hard-Delete nach 90 Tagen (Tenant-Admin-konfigurierbar in `/admin/lead-anti-spam`, 0 = nie)
|
||
- Vor Hard-Delete: Activity-Trail-Eintrag bleibt (anonymisiert ohne PII), Audit-Log-Eintrag bleibt
|
||
- Klartext-Hinweis im Lead-Detail: *„Wird automatisch gelöscht am [Datum] — [Status ändern um zu erhalten]"*
|
||
|
||
### Anti-Spam / Anomalie-Detection (EC-1-Erweiterung)
|
||
|
||
**Settings unter `/{tenant}/admin/lead-anti-spam`:**
|
||
|
||
- Hard-Limit pro Quelle pro Stunde (Default 100; bei Überschreiten: Rest verworfen mit Notification an Tenant-Admin)
|
||
- Hard-Limit pro IP pro Stunde (Default 20; bei Form-Submissions)
|
||
- Anomalie-Detection: erkennt 10x-normale-Rate-Spike → Auto-Pause der Quelle + Klartext-Notification
|
||
- Auto-Mark-as-Spam-Heuristiken (alle optional, Tenant-Admin-Toggles):
|
||
- Submitter-IP auf Blocklist (extern gepflegt)
|
||
- Email-Domain in Disposable-Mail-Provider-Liste
|
||
- Honeypot-Feld in Form gefüllt (Form-Builder-Feature)
|
||
- Submission < 3 Sek nach Form-Load (Bot-Verdacht)
|
||
- Quarantäne-Modus: bei Spam-Verdacht → Status `new` mit Marker, KEIN Auto-Spam (Mensch entscheidet)
|
||
- Vollständig-Spam-Modus (für Hard-Cases): Status direkt `spam` ohne UI-Anzeige in Default-Filter
|
||
|
||
**Klartext-Hinweise:**
|
||
- *„Quelle ‚Kontaktformular' wurde automatisch pausiert: 247 Submissions in 5 Minuten (10x üblich). Eingehende Leads werden verworfen. [Wieder aktivieren] [Anti-Spam-Settings]"*
|
||
|
||
---
|
||
|
||
## Block G — Bulk-Actions
|
||
|
||
**Verfügbare Bulk-Actions in der Listen-View:**
|
||
|
||
- Verantwortlichen zuweisen (Picker oder Round-Robin innerhalb Group)
|
||
- Status setzen (Multi-Select, mit Begründungs-Feld bei `lost`)
|
||
- Tag hinzufügen / entfernen
|
||
- Spam markieren (mit Klartext-Bestätigung über Auto-Lösch in 30 Tagen)
|
||
- Hard-Delete (mit Klartext-Warnung; Permission `leads.admin`)
|
||
- Export als CSV (Permission `leads.admin`)
|
||
- Bulk-Promote (Phase 2 — komplex weil pro Lead Match-Check nötig)
|
||
|
||
**Klartext-Bestätigungen vor Bulk-Action:**
|
||
- *„124 Leads als ‚Spam' markieren? Sie werden in 30 Tagen automatisch gelöscht."*
|
||
- *„12 Leads hard-löschen? Diese Aktion ist nicht rückgängig."*
|
||
|
||
**Permissions-Wirkung in Bulk-Actions:**
|
||
- User mit `leads.read_own` sieht Bulk-Action nur über eigene Leads
|
||
- Bei gemischter Auswahl mit nicht-eigenen Leads: Klartext-Hinweis *„X von Y Leads sind nicht dir zugewiesen — diese werden übersprungen."*
|
||
|
||
---
|
||
|
||
## Block H — Statistiken (`/{tenant}/leads/statistics`)
|
||
|
||
### Zu zeigende Daten
|
||
|
||
**KPI-Kacheln:**
|
||
- Eingegangene Leads (gewählter Zeitraum)
|
||
- Konvertierungsrate Lead → Projekt *(pre-pivot: „Lead → Contact")*
|
||
- Konvertierungsrate Lead → gewonnen (Projekt erreicht Gewinn-Status der Sales-Pipeline) *(pre-pivot: „Lead → Deal (won)")*
|
||
- Durchschnittliche Reaktionszeit (Eingang bis erste Antwort/Status-Wechsel)
|
||
- Spam-Quote
|
||
- Open-Leads (nicht zugewiesen oder Status `new` älter als 24h)
|
||
|
||
**Aufschlüsselungen:**
|
||
- Nach Quelle (Lead-Volumen + Konversionsrate pro Quelle)
|
||
- Nach Verantwortlichem (Volumen + Konversionsrate)
|
||
- Nach Tag
|
||
- Nach Wochentag / Tageszeit
|
||
- Nach Status-Verteilung (aktuelle Snapshot)
|
||
|
||
**Trend-Anzeige:**
|
||
- Lead-Volumen über Zeit (Line-Chart)
|
||
- Konvertierungs-Rate über Zeit
|
||
- Vergleich zur Vorperiode (delta in %)
|
||
|
||
### Benötigte UI-Elemente
|
||
|
||
- Date-Range-Selektor (Default: letzte 30 Tage)
|
||
- Vergleichs-Period-Toggle (Vorperiode / kein Vergleich)
|
||
- KPI-Kachel-Komponente
|
||
- Bar-/Line-Chart-Komponenten für Trends und Aufschlüsselungen
|
||
- Drill-Down-Funktion: Klick auf Quelle/Verantwortlichen filtert Lead-Listen-View vor
|
||
|
||
### Operationen
|
||
|
||
- Filter setzen / Date-Range ändern
|
||
- Drill-Down zur gefilterten Listen-View
|
||
- Export der aktuellen Sicht als CSV (Permission `leads.admin`)
|
||
|
||
### Performance-Anforderungen
|
||
|
||
- Aggregat-Query mit Materialized View oder Cron-aggregierter Statistik-Tabelle (täglich neu berechnet)
|
||
- Live-Berechnung nur für aktuellen Tag
|
||
- Index auf `tenant_id, source, created_at` für Quellen-Aggregat
|
||
|
||
### Permissions-Wirkung
|
||
|
||
- `leads.read_own`: nur eigene Leads in Statistiken (Verantwortlicher-Filter immer auf Self)
|
||
- `leads.read_all`: alle Statistiken
|
||
- Aufschlüsselung „Nach Verantwortlichem" nur sichtbar mit `leads.read_all`
|
||
|
||
---
|
||
|
||
## Block I — Activity-Stream-Integration
|
||
|
||
**Lead produziert folgende Activity-Typen (über Modul-1-Activity-Stream):**
|
||
|
||
- `lead_created` (Quelle aus `metadata`)
|
||
- `lead_assigned` / `lead_unassigned`
|
||
- `lead_status_changed` (mit Vorher/Nachher)
|
||
- `lead_promoted` (im resultierenden Contact gespiegelt — siehe Modul 1)
|
||
- `lead_responded` (manuelle Antwort gesendet)
|
||
- `lead_marked_spam`
|
||
- `lead_auto_paused` (Quelle pausiert wegen Anomalie)
|
||
|
||
**Verknüpfungen mit anderen Modulen:**
|
||
- Modul 5 (Form-Builder): Form-Submission erzeugt `form_submitted` + `lead_created`
|
||
- Modul 9 (Email-Inbox): Eingehende Mail erzeugt `email_received` + `lead_created`
|
||
- Modul 12 (Telefonie): Inbound-Anruf erzeugt `call_inbound` + `lead_created`
|
||
- Modul 17 (Automation): `lead.created`-Event triggert konfigurierte Automationen; Action-Resultate als `automation_triggered`-Activity
|
||
|
||
---
|
||
|
||
## Block J — Permissions-Anwendung
|
||
|
||
### Permission-IDs
|
||
|
||
| Permission | Erlaubt |
|
||
|---|---|
|
||
| `leads.read_own` | Leads sehen, bei denen User = `assigned_to_user_id` |
|
||
| `leads.read_all` | Alle Leads sehen |
|
||
| `leads.write` | Lead anlegen, bearbeiten, Status ändern, antworten (Owner-Check bei nur `read_own`) |
|
||
| `leads.delete` | Hard-Delete |
|
||
| `leads.admin` | Bulk-Actions, Export, Quellen-Verwaltung, Anti-Spam-Settings |
|
||
|
||
### Bundle-Mapping (Variante 2)
|
||
|
||
| Bundle | Atomare Permissions |
|
||
|---|---|
|
||
| `leads.none` | (keine) |
|
||
| `leads.read_own` | `leads.read_own` |
|
||
| `leads.read_all` | `leads.read_own` + `leads.read_all` |
|
||
| `leads.write` | `leads.read_all` + `leads.write` |
|
||
| `leads.admin` | `leads.read_all` + `leads.write` + `leads.delete` + `leads.admin` |
|
||
|
||
### Anwendung in Routes
|
||
|
||
- `/leads` → `leads.read_own` oder `leads.read_all`
|
||
- `/leads/new` → `leads.write`
|
||
- `/leads/:id` → `leads.read_own` (mit Owner-Check) oder `leads.read_all`
|
||
- `/leads/statistics` → `leads.read_own` oder `leads.read_all`
|
||
- `/admin/lead-sources` → `leads.admin` oder `tenant.admin`
|
||
- `/admin/lead-anti-spam` → `leads.admin` oder `tenant.admin`
|
||
|
||
### Anwendung in Action-Funktionen
|
||
|
||
- Inline-Edit, Status-Wechsel, Antwort senden: `leads.write` (Owner-Check bei `read_own`)
|
||
- Promotion zu Contact: `leads.write` UND `crm.write` (beide Module)
|
||
- Hard-Delete: `leads.delete`
|
||
- Bulk-Actions, Export: `leads.admin`
|
||
- Quellen-Verwaltung: `leads.admin` oder `tenant.admin`
|
||
|
||
### Owner-Check-Logik (für `read_own`)
|
||
|
||
- Lead sichtbar wenn `lead.assigned_to_user_id = current_user_id`
|
||
- ODER Lead `assigned_to_user_id IS NULL` UND User in einer Group, die als „Lead-Pool" markiert ist (Phase 2 — in Phase 1: nicht-zugewiesene Leads sind für jeden mit `read_all` sichtbar; mit `read_own` unsichtbar)
|
||
|
||
### Permissions-aware-Default in Listen
|
||
|
||
- Server-side-Filter wendet Permission-Filter automatisch an (AV #5)
|
||
- Bei Wechsel des Verantwortlichen: Real-time-Update entfernt Eintrag aus eigener Liste
|
||
- Statistiken: Aufschlüsselung „Nach Verantwortlichem" nur mit `read_all`
|
||
|
||
---
|
||
|
||
## Block K — Klartext-Hinweise / -Fehler
|
||
|
||
**Inbox leer:**
|
||
- *„Noch keine Leads — sobald über Forms, Mails oder Anrufe Eingänge kommen, erscheinen sie hier. [Form anlegen] [Mail-Inbox verbinden]"*
|
||
|
||
**Filter ohne Treffer:**
|
||
- *„Keine Leads passen zu deinen Filtern. [Filter zurücksetzen]"*
|
||
|
||
**Lead ohne Verantwortlichen länger als 24h:**
|
||
- Marker im Lead-Eintrag mit Klartext: *„Seit X Stunden unbearbeitet — [Mir zuweisen]"*
|
||
|
||
**Promotion-Versuch mit fehlenden Pflichtdaten:**
|
||
- *„Um diesen Lead zu promovieren, brauchen wir mindestens Vor- und Nachname. [Daten ergänzen]"*
|
||
|
||
**Auto-Pause durch Anomalie-Detection:**
|
||
- Tenant-Admin-Notification: *„Quelle ‚X' wurde automatisch pausiert (10x normales Aufkommen). Y Leads wurden seitdem verworfen. [Quelle prüfen] [Wieder aktivieren] [Hard-Limit anpassen]"*
|
||
|
||
**Spam-Markierung mit Auto-Lösch:**
|
||
- *„Lead als Spam markiert. Wird am [Datum + 30 Tage] automatisch gelöscht. [Wiederherstellen]"*
|
||
|
||
**Bulk-Action mit gemischten Permissions:**
|
||
- *„Du hast 50 Leads ausgewählt. 12 davon sind nicht dir zugewiesen — diese werden übersprungen. [Trotzdem fortfahren] [Auswahl anpassen]"*
|
||
|
||
**Quelle pausiert (Tenant-Admin):**
|
||
- *„Quelle ‚Messe SHK 2027' ist pausiert — eingehende Leads aus dieser Quelle werden derzeit verworfen. [Reaktivieren]"*
|
||
|
||
**Hard-Limit-Überschreitung:**
|
||
- Notification an Tenant-Admin + im Quellen-Detail: *„In den letzten 60 Min wurden 134 Submissions verworfen (Hard-Limit: 100/h). [Hard-Limit anpassen]"*
|
||
|
||
---
|
||
|
||
## Block L — Phase 2 / spätere Features
|
||
|
||
- **CSV/JSON-Lead-Import** (geparkt mit Migration HubSpot/Quiply)
|
||
- **Bulk-Promote** (mit gruppen-weisem Match-Check-Workflow)
|
||
- **Lead-Score-KI** (semantische Bewertung, automatische Priorisierung — über Modul 18)
|
||
- **WhatsApp als Lead-Quelle** (komplett — Phase 2 Modul 11)
|
||
- **Round-Robin-Auto-Assignment** (Tenant-Admin definiert Verteilungs-Regeln auf Group-Ebene)
|
||
- **Lead-Pool-Groups** (nicht-zugewiesene Leads sichtbar für Group-Mitglieder)
|
||
- **Erweiterte Statistiken:** Funnel-Visualisierung, Quellen-ROI mit Marketing-Spend (Modul 10 Integration), Cohort-Analyse
|
||
- **Lead-Webhook-Auto-Filter** (KI-getriebene Spam-Erkennung über Modul 18)
|
||
- **Templated-Quick-Replies** für häufige Lead-Antworten (mit Personalisierung)
|
||
- **Lead-Routing-KI**: KI schlägt besten Verantwortlichen vor basierend auf Quelle, Branche, Verfügbarkeit
|
||
|
||
---
|
||
|
||
## Architektur-Vorschriften (Querschnitt)
|
||
|
||
- **AV #1, LP-10:** Klartext-Diagnostik bei Auto-Pause, Hard-Limit, Spam-Markierung, Auto-Lösch
|
||
- **AV #5:** Permissions-aware-Default in Listen + Statistiken
|
||
- **AV #6:** Audit-Trail für jeden Status-Wechsel, Verantwortlichen-Wechsel, Bulk-Action, Hard-Delete
|
||
- **AV #16:** Rate-Limiting + Anomalie-Detection für Lead-Trigger (EC-1)
|
||
- **AV #20:** Action-Boundary für KI — KI darf Leads niemals automatisch promovieren oder löschen ohne User-Bestätigung
|
||
- **LP-3, AV #3:** Quellen-System ist deklarativ; Custom-Quellen sind Daten, nicht Code
|
||
- **LP-7:** HubSpot-Lead-Komponente vollständig abgelöst (Inbox + Statistik + Auto-Konvertierung)
|
||
|
||
---
|
||
|
||
## Detail-Spec-Status: DRAFT
|
||
|
||
Erste vollständige Detail-Spec für Modul 2. **Vor Bau:** Verifizierung mit Noah zusammen mit Modul 1 (CRM-Kern), Modul 5 (Form-Builder), Modul 9 (Email-Inbox), Modul 12 (Telefonie).
|
||
|
||
**Offene Detail-Punkte (nicht-blockierend):**
|
||
- Konkrete Anti-Spam-Heuristiken finalisieren (Disposable-Domain-Liste, IP-Blocklist-Provider — externe Liste oder selbst pflegen)
|
||
- Round-Robin-Auto-Assignment final entscheiden (Phase 1 minimal vs. Phase 2)
|
||
- Default-Konfigurationswerte für Anti-Spam-Limits (100/h pro Quelle / 20/h pro IP) mit Noah validieren — Geerkens-spezifisch ggf. anders
|
||
- Form-Honeypot-Feld-Mechanik mit Modul 5 abstimmen
|
||
- Lead-Pool-Group-Konzept (nicht-zugewiesene Leads für Group sichtbar) als Phase 1 oder Phase 2 entscheiden — Annahme hier: Phase 2
|
||
|
||
**Abhängige Module:**
|
||
- Modul 1 (CRM-Kern) — Lead-Datenmodell, Promotion-Logik
|
||
- Modul 5 (Form-Builder) — Hauptquelle Form-Submissions
|
||
- Modul 9 (Email-Inbox) — Email-Quelle
|
||
- Modul 12 (Telefonie/AirCall) — Phone-Quelle
|
||
- Modul 17 (Automation Engine) — `lead.created`-Trigger
|
||
- Modul 22 (Notifications) — Tenant-Admin-Alerts bei Anomalie
|
||
- Modul 21 (Audit-Log) — Audit-Trail für Status- und Bulk-Operationen
|
||
- Modul 27 (Auth/Permissions) — Permission-Bundle `leads.*`
|