621 lines
27 KiB
Markdown
621 lines
27 KiB
Markdown
---
|
||
module: 3
|
||
title: Sales-Pipeline (Deals)
|
||
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 3 — Sales-Pipeline (Deals)
|
||
|
||
> 🔴 **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:
|
||
> - **`Deal` existiert NICHT als eigene Entität.** Es gibt EINEN `Projekt`-Kern. „Sales-Pipeline" ist eine **Pipeline-View** (`typ_hint=sales`) auf denselben `Projekt`-Datensatz, den auch M4 (Auftrags-Sicht) zeigt. Überall wo unten „Deal" steht, ist ein **Projekt in der Sales-Pipeline-Sicht** gemeint; `deal_number` → `projekt_nummer` (P-…), `Deal.title` → `projektname` usw.
|
||
> - **KEIN Won-Handoff.** Bei Gewinn wechselt der Projekt-Datensatz nur die **Pipeline** (von Sales- in Auftrags-Pipeline) bzw. den Status — es entsteht **kein zweiter Datensatz** und kein `won_handoff_project_id`. Alle „Won-Handoff"-/„Projekt anlegen?"-Abschnitte unten sind durch **Pipeline-Wechsel** zu ersetzen.
|
||
> - **Pipeline = View, NICHT generische Eigen-Tabelle pro Sales-Fall** — aber `Pipeline`/`PipelineStage` sind sehr wohl konfigurierbare First-Class-Tabellen (Multi-Pipeline v1 bleibt). Rechte/Sichtbarkeit komplex schon v1: `PipelineAccess` + `PipelineFieldConfig` + **`PipelineFieldVisibility`** (Field-Level, z.B. Volumen nur Vertrieb) — ersetzt die unten beschriebenen `deals.read_volume_*`-Permission-Bundles für Feld-Sichtbarkeit.
|
||
> - **Lost-Reasons** = Status-/Checklisten-Metadaten am Verloren-Status, keine eigene `LostReason`-Tabelle nötig. **Lead-Promotion** → Lead→Projekt (kein Deal). **KWP komplett v2**, PWA-only (AD-17), v1 DE-only.
|
||
|
||
> **Detail-Spec gemäß LP-9.** Kern-Vertriebs-Modul. Löst HubSpot-Pipeline-Tool ab (LP-7). Baut auf M1 (CRM-Kern) und M2 (Lead-Inbox) auf; bei Gewinn wechselt das Projekt in die Auftrags-Pipeline (M4) — **kein Won-Handoff, kein zweiter Datensatz** (AD-20).
|
||
|
||
## Themenblöcke
|
||
|
||
```
|
||
A. Datenmodell (Pipeline, Stages, Deal, DealActivity, HiveNumberSeq)
|
||
B. Menü-Struktur und Routes
|
||
C. Pipeline-Verwaltung (Multi-Pipeline-Konfiguration, Stages)
|
||
D. Kanban-View / Listen-View
|
||
E. Deal-Detail-View
|
||
F. Deal-Lifecycle (Anlegen, Stage-Wechsel, Won/Lost, Archivierung)
|
||
G. Forecast & KPIs
|
||
H. Integration mit anderen Modulen
|
||
I. Permissions-Anwendung (mit Field-Level-Permissions)
|
||
```
|
||
|
||
---
|
||
|
||
## Block A — Datenmodell
|
||
|
||
### Architektur-Entscheidung (revidiert AD-20): Projekt-Kern + Pipeline-Views, Multi-Pipeline ab Tag 1
|
||
|
||
> 🔴 **Pivot:** Der **Arbeitsdatensatz ist das `Projekt`** — NICHT ein eigener `Deal`. `Pipeline`/`PipelineStage` sind konfigurierbare First-Class-Tabellen und liefern **Views** auf den Projekt-Kern; „Sales" ist eine Pipeline mit `typ_hint=sales`. Tenant kann mehrere Pipelines mit unterschiedlichen Statuswerten anlegen. Begründung: Verkaufsfälle (Anlagen-Verkauf vs. Wartungsverträge vs. Reparaturen) haben unterschiedliche Statuswerte — und Geerkens kommt von HubSpot, kennt das Pattern. **Lies die `Deal`-Felder unten als `Projekt`-Felder in der Sales-Sicht.**
|
||
|
||
### Kern-Entitäten
|
||
|
||
```
|
||
Pipeline — eine Sales-Pipeline pro Tenant (mehrere möglich)
|
||
PipelineStage — Phase innerhalb einer Pipeline
|
||
Deal — ein Verkaufsfall in einer Pipeline
|
||
DealForm — Verknüpfung Deal ↔ Form-Submission
|
||
LostReason — Tenant-konfigurierbare Lost-Gründe
|
||
HiveNumberSeq — fortlaufende Deal-Nummern pro Tenant
|
||
```
|
||
|
||
### Pipeline
|
||
|
||
- `id`, `tenant_id`, `created_at`, `updated_at`
|
||
- `name` (z.B. „Anlagen-Verkauf", „Wartungsverträge")
|
||
- `description` (optional)
|
||
- `is_default` (Boolean — eine pro Tenant ist Default für neue Deals ohne Pipeline-Auswahl)
|
||
- `position` (Sortierung im UI)
|
||
- `archived_at`
|
||
|
||
### PipelineStage
|
||
|
||
- `id`, `tenant_id`, `pipeline_id`
|
||
- `name` (z.B. „Anfrage", „Besichtigung", „Angebot", „Verhandlung", „Gewonnen", „Verloren")
|
||
- `position` (innerhalb Pipeline)
|
||
- `stage_kind` (Enum: `open | won | lost`) — Markiert Stage-Typ; `won`/`lost` sind Terminal-Stages
|
||
- `win_probability` (0-100 % — für Forecast; bei `won` automatisch 100, `lost` automatisch 0)
|
||
- `auto_archive_after_days` (optional — Stuck-Detection oder Auto-Archivierung)
|
||
- `color` (visueller Hinweis; Designer entscheidet konkrete Wahl)
|
||
- `archived_at`
|
||
|
||
**Validation:** Pipeline muss mind. 1 `won`- und 1 `lost`-Stage haben (UI-Validation beim Speichern).
|
||
|
||
### Deal
|
||
|
||
- `id`, `tenant_id`, `created_at`, `updated_at`, `created_by_user_id`
|
||
- `deal_number` (fortlaufend über `HiveNumberSeq`, z.B. „D-2026-0042")
|
||
- `pipeline_id`, `stage_id`
|
||
- `title` (Pflicht)
|
||
- `description` (Markdown-Freitext)
|
||
- `volume` (`numeric(12,2)` — Cent-Genauigkeit, UI zeigt Default ganze Euro)
|
||
- `currency` (Default EUR)
|
||
- `expected_close_date` (geschätzter Abschluss-Termin)
|
||
- `actual_close_date` (gesetzt bei Won/Lost)
|
||
- `assigned_to_user_id` (Verantwortlicher Vertriebler)
|
||
- `contact_id` (FK auf primären Kontakt — Pflicht)
|
||
- `company_id` (FK auf primäre Firma, optional bei B2C)
|
||
- `lead_id` (FK auf ursprünglichen Lead, falls aus Promotion)
|
||
- `lost_reason` (Pflicht bei Status = `verloren`; Verloren-Grund als Status-Metadatum/Checklisten-Wert, **keine eigene `LostReason`-Tabelle**, AD-20)
|
||
- *(KEIN `won_handoff_project_id` — es gibt keinen zweiten Datensatz; bei Gewinn wechselt dasselbe Projekt nur die Pipeline, AD-20)*
|
||
- `archived_at`
|
||
|
||
### DealActivity (Schreibt in zentrale `Activity`-Tabelle aus M1)
|
||
|
||
Activity-Typen pro Deal:
|
||
- `deal_created`
|
||
- `deal_stage_changed` (Metadata: `from_stage_id`, `to_stage_id`, `duration_in_previous_stage_seconds`)
|
||
- `deal_volume_changed`
|
||
- `deal_assignee_changed`
|
||
- `deal_pipeline_changed`
|
||
- `deal_won` / `deal_lost`
|
||
- `note_added`
|
||
- Alle CRM-Activities mit verknüpftem Contact erscheinen automatisch im Deal-Stream
|
||
|
||
### DealForm
|
||
|
||
- `deal_id`, `form_submission_id`, `linked_at`
|
||
- Verknüpft Deal mit Form-Submissions
|
||
|
||
### LostReason (Tenant-konfigurierbar)
|
||
|
||
- `id`, `tenant_id`, `name`, `archived_at`
|
||
- Tenant-Admin verwaltet in `/admin/sales/lost-reasons/`
|
||
- SHK-Template seedet 5 Standard-Reasons (z.B. „Zu teuer", „Konkurrenz", „Kein Bedarf mehr", „Kein Budget", „Nicht erreicht")
|
||
|
||
### HiveNumberSeq
|
||
|
||
- `id`, `tenant_id`, `entity_type` (`deal | project | invoice | ...`)
|
||
- `current_number` (fortlaufend)
|
||
- `prefix` (z.B. „D-2026-")
|
||
- `format` (z.B. `{prefix}{number:04d}` → „D-2026-0042")
|
||
- Reset-Strategie: Phase 1 nie reset; Phase 2 jährlich konfigurierbar
|
||
|
||
### SHK-Template-Pipelines (beim Tenant-Anlegen geseedet)
|
||
|
||
**Pipeline 1: „Anlagen-Verkauf"**
|
||
1. Anfrage (open, 10 %)
|
||
2. Besichtigung (open, 30 %)
|
||
3. Bedarfsanalyse (open, 50 %)
|
||
4. Angebot (open, 70 %)
|
||
5. Verhandlung (open, 85 %)
|
||
6. Gewonnen (won, 100 %)
|
||
7. Verloren (lost, 0 %)
|
||
|
||
**Pipeline 2: „Wartungsverträge"**
|
||
1. Erstkontakt (open, 30 %)
|
||
2. Vertrag-Versand (open, 60 %)
|
||
3. Unterschrift erhalten (open, 90 %)
|
||
4. Aktiv (won, 100 %)
|
||
5. Abgesagt (lost, 0 %)
|
||
|
||
Reparatur-Aufträge laufen direkt als Auftrag (M4), nicht über Sales-Pipeline.
|
||
|
||
---
|
||
|
||
## Block B — Menü-Struktur und Routes
|
||
|
||
**Sidebar-Hauptpunkt:** *Sales* (oder direkt *Deals* — Designer-Entscheidung)
|
||
|
||
```
|
||
/{tenant}/deals → Default-Pipeline (Kanban der is_default=true Pipeline)
|
||
/{tenant}/deals/list → Alle Deals als Tabelle (Cross-Pipeline-Sicht)
|
||
/{tenant}/deals/pipelines → Pipeline-Switcher / Übersicht
|
||
/{tenant}/deals/pipelines/:id → Spezifische Pipeline-Ansicht (Kanban)
|
||
/{tenant}/deals/pipelines/:id/list → Spezifische Pipeline als Tabelle
|
||
/{tenant}/deals/new → Neuer Deal (mit Pipeline-Vorauswahl wenn aus Pipeline-View)
|
||
/{tenant}/deals/:id → Deal-Detail
|
||
/{tenant}/deals/archive → Archivierte Deals (Won/Lost + soft-archived)
|
||
|
||
/{tenant}/admin/sales/pipelines → Pipeline-Verwaltung
|
||
/{tenant}/admin/sales/pipelines/:id → Einzelne Pipeline editieren (Stages, Defaults)
|
||
/{tenant}/admin/sales/lost-reasons → Lost-Reasons-Liste
|
||
```
|
||
|
||
**Default-Routen-Logik:**
|
||
- `/{tenant}/deals` öffnet immer die `is_default=true`-Pipeline
|
||
- Bei Multi-Pipeline-Tenants: Pipeline-Switcher-Komponente im Header der Sales-View
|
||
|
||
---
|
||
|
||
## Block C — Pipeline-Verwaltung
|
||
|
||
### Pipeline-Liste (`/{tenant}/admin/sales/pipelines/`)
|
||
|
||
**Zu zeigende Daten:**
|
||
- Liste aller Pipelines pro Tenant
|
||
- Pro Pipeline: Name, Anzahl Stages, Anzahl aktiver Deals, is_default-Markierung, Status
|
||
|
||
**Benötigte UI-Elemente:**
|
||
- Listen-Anzeige
|
||
- Drag-&-Drop für Pipeline-Reihenfolge
|
||
- Funktion: neue Pipeline anlegen
|
||
- Funktion: Pipeline duplizieren
|
||
- Funktion: Pipeline editieren / archivieren / als Default markieren
|
||
|
||
**Operationen:**
|
||
- Pipeline anlegen (Name, Description, optional aus Template)
|
||
- Pipeline duplizieren (alle Stages werden mitkopiert, neue IDs)
|
||
- Pipeline archivieren (Block falls aktive Deals — Reassign-Workflow)
|
||
- Pipeline löschen (hard, nur wenn keine Deals jemals drin waren)
|
||
- Pipeline als Default markieren
|
||
|
||
### Pipeline-Editor (`/{tenant}/admin/sales/pipelines/:id`)
|
||
|
||
**Zu zeigende Daten:**
|
||
- Pipeline-Stammdaten (Name, Description, is_default)
|
||
- Liste der Stages mit allen Feldern
|
||
|
||
**Benötigte UI-Elemente:**
|
||
- Editor-Funktion für Stammdaten
|
||
- Stage-Liste mit Drag-&-Drop für Reihenfolge
|
||
- Add-Funktion für neue Stage
|
||
- Edit-/Delete-Funktion pro Stage
|
||
- Validation-Anzeige für Won-/Lost-Stage-Pflicht
|
||
|
||
**Operationen:**
|
||
- Stage hinzufügen (Name, Stage-Kind, Win-Probability, Color, auto_archive_after_days)
|
||
- Stage editieren
|
||
- Stage löschen (Block falls noch Deals — Reassign-Workflow nötig)
|
||
- Stages umsortieren
|
||
- Pipeline als Default markieren
|
||
|
||
**Klartext-Validation:**
|
||
- *„Diese Pipeline hat keine ‚Gewonnen'-Stage. Bitte mindestens eine Stage vom Typ ‚won' anlegen."*
|
||
- *„Diese Pipeline hat keine ‚Verloren'-Stage. Bitte mindestens eine Stage vom Typ ‚lost' anlegen."*
|
||
- Stage löschen mit Deals: *„In dieser Stage sind 8 aktive Deals. Bitte zuerst neu zuweisen oder Stage archivieren statt löschen."*
|
||
|
||
### Lost-Reasons-Verwaltung (`/{tenant}/admin/sales/lost-reasons/`)
|
||
|
||
**Zu zeigende Daten:** Liste mit Name, Anzahl verknüpfter Deals, Status.
|
||
|
||
**Benötigte UI-Elemente:** Standard-Listen-Editor mit Add/Edit/Archive.
|
||
|
||
**Operationen:** Standard-CRUD; Archivieren statt Hard-Delete (Reporting-Konsistenz).
|
||
|
||
---
|
||
|
||
## Block D — Kanban-View / Listen-View
|
||
|
||
### Kanban-View (`/{tenant}/deals/pipelines/:id` oder Default `/{tenant}/deals`)
|
||
|
||
**Zu zeigende Daten:**
|
||
- Spalten entsprechen Stages der gewählten Pipeline (in `position`-Reihenfolge)
|
||
- Pro Stage-Spalte: Stage-Name, Anzahl Deals, Aggregat-Volumen, Win-Probability
|
||
- Pro Deal-Karte:
|
||
- Deal-Titel
|
||
- Volumen (gegated über `deals.read_volume_*` — siehe Block I)
|
||
- Verantwortlicher (Avatar/Initialen)
|
||
- Erwarteter Close-Date
|
||
- Tags (max. 3 sichtbar, Rest als „+N"-Hinweis)
|
||
- Visueller Hinweis bei überzogenem Close-Date
|
||
- Visueller Hinweis bei Stage-Stuck
|
||
|
||
**Benötigte UI-Elemente:**
|
||
- Spalten-Layout (Designer entscheidet horizontal scrollbar / responsive)
|
||
- Drag-&-Drop-Funktion zwischen Spalten
|
||
- Filter-Leiste mit Multi-Select für: Verantwortlicher, Tags, Volumen-Range, Erwarteter Close-Date Range
|
||
- Such-Funktion (Volltext über Titel + Description + verknüpfte Kontakt-/Firmen-Namen)
|
||
- Pipeline-Switcher
|
||
- Toggle „Nur meine Deals" (Quick-Filter)
|
||
- Klick auf Deal-Karte öffnet Deal-Detail
|
||
- Bulk-Auswahl für Mass-Actions
|
||
- Pagination pro Stage-Spalte: bei 100+ Deals „Mehr laden"-Funktion
|
||
|
||
**Operationen — Drag-&-Drop:**
|
||
- Drag von Spalte A nach Spalte B → `stage_changed`-Activity (Metadata: `from_stage_id`, `to_stage_id`, `duration_in_previous_stage_seconds`)
|
||
- Bei Drag in `gewonnen`-Status: Bestätigungs-Dialog mit Option **„Projekt in Auftrags-Pipeline überführen"** (= Pipeline-Wechsel desselben Datensatzes; **kein** zweites Objekt). *(pre-pivot: „Won-Handoff-Option")*
|
||
- Bei Drag in `verloren`-Status: Bestätigungs-Dialog erzwingt `lost_reason`-Auswahl
|
||
- Reverse-Window: Gewonnen/Verloren-Status kann innerhalb 24h zurückgenommen werden
|
||
|
||
**Operationen — Bulk:**
|
||
- Tags hinzufügen/entfernen
|
||
- Verantwortlichen ändern
|
||
- Stage-Wechsel (Bulk-Move)
|
||
- Archivieren
|
||
|
||
### Listen-View (`/{tenant}/deals/list` oder `/{tenant}/deals/pipelines/:id/list`)
|
||
|
||
**Zu zeigende Daten pro Eintrag:**
|
||
- Deal-Nummer, Titel, Pipeline (bei Cross-Pipeline-Sicht), Stage, Verantwortlicher, Volumen (gegated), Verknüpfter Kontakt + Firma, Tags, Erwarteter Close-Date, Letzte Activity
|
||
|
||
**Benötigte UI-Elemente:**
|
||
- Tabellarische Anzeige
|
||
- Spalten-Header für Sortierung
|
||
- Filter wie in Kanban
|
||
- Spalten-Konfiguration pro User (gespeichert)
|
||
- Bulk-Auswahl
|
||
- Export als CSV (gefilterte Auswahl)
|
||
- Pagination (Cursor-basiert, 50/Page, „Mehr laden")
|
||
|
||
**Default-Sortierung:** zuletzt geändert absteigend.
|
||
|
||
### Cross-Pipeline-Listen-View (`/{tenant}/deals/list`)
|
||
|
||
Gleiche Funktionalität, zeigt Deals aus allen Pipelines mit zusätzlicher Pipeline-Spalte und Pipeline-Filter.
|
||
|
||
### Performance-Anforderungen
|
||
|
||
- Server-side-Filter (kein Client-side bei 1.000+ Deals)
|
||
- Index auf `tenant_id, pipeline_id, stage_id, archived_at, last_activity_at`
|
||
- Aggregat-Cache pro Stage (Anzahl + Volumen-Summe), invalidiert bei Stage-Wechsel
|
||
- Real-Time-Updates: bei Stage-Wechsel durch andere User wird Kanban Live aktualisiert (WebSocket oder Server-Sent-Events)
|
||
|
||
---
|
||
|
||
## Block E — Deal-Detail-View
|
||
|
||
### Deal-Detail (`/{tenant}/deals/:id`)
|
||
|
||
**Zu zeigende Daten:**
|
||
- Deal-Stammdaten (Deal-Nummer, Titel, Description, Volumen, Pipeline, Stage, erwarteter Close-Date, tatsächlicher Close-Date)
|
||
- Verknüpfter Kontakt + Firma
|
||
- Verantwortlicher
|
||
- Lead-Origin-Hinweis (falls aus Promotion mit Link zu Lead)
|
||
- Tags
|
||
- Custom-Felder (separate Definitionen mit `applicable_to=deal`)
|
||
- Stage-Historie (Liste aller Stage-Wechsel mit Datum und Dauer)
|
||
- Activity-Stream (M1 Block E)
|
||
- Verknüpfte Files
|
||
- Verknüpfte Form-Submissions
|
||
- Verknüpfte Tasks
|
||
- Verknüpftes Projekt (falls Won-Handoff erfolgt — Link zu M4)
|
||
|
||
**Benötigte UI-Elemente:**
|
||
- Sektionierte Anzeige der Stammdaten
|
||
- Inline-Edit für editierbare Felder
|
||
- Stage-Anzeige als visuelle Pipeline-Komponente (zeigt aktuelle Position, Klick auf andere Stage triggert Stage-Wechsel)
|
||
- Activity-Stream-Komponente
|
||
- Tab- oder Sektions-Navigation für: Übersicht / Activities / Files / Tasks / Forms / Custom-Felder
|
||
- Action-Funktionen für die unten gelisteten Operationen
|
||
- Markdown-Editor für Description und Notizen
|
||
|
||
**Operationen:**
|
||
- Stammdaten editieren (Inline)
|
||
- Stage wechseln (mit Bestätigungs-Workflow für Won/Lost)
|
||
- Verantwortlichen ändern
|
||
- Pipeline wechseln (Edge-Case mit Klartext-Hinweis über Historie)
|
||
- Verknüpften Kontakt/Firma ändern
|
||
- Tags hinzufügen/entfernen
|
||
- Custom-Feld-Werte setzen
|
||
- Click-to-Call (über AirCall-Integration)
|
||
- Email schreiben (Compose mit Empfänger vorausgefüllt)
|
||
- Termin buchen
|
||
- Aufgabe anlegen
|
||
- Notiz hinzufügen
|
||
- File hochladen
|
||
- Form-Submission verknüpfen
|
||
- Archivieren / Reaktivieren
|
||
- Hard-Delete
|
||
|
||
**Gewinn-Workflow (Pipeline-Wechsel statt Won-Handoff, AD-20):**
|
||
- Bei Status-Wechsel zu `gewonnen`: Bestätigungs-Dialog *„Projekt in die Auftrags-Pipeline überführen?"*
|
||
- Bei Bestätigung:
|
||
- **Dasselbe Projekt** wechselt von der Sales- in die Auftrags-Pipeline (`pipeline_id`/`stage_id` neu) + ggf. Start-Status der Auftrags-Pipeline wählen
|
||
- **Kein** Mapping/Kopieren von Feldern, **kein** zweiter Datensatz — Kontakte, Files, Notizen, Aktivitäten bleiben am selben Datensatz
|
||
- Bei Ablehnung: Projekt bleibt in Sales-Pipeline, nur Status `gewonnen`
|
||
- Reverse innerhalb 24h: Status/Pipeline zurück (kein Objekt zu löschen)
|
||
|
||
**Lost-Workflow:**
|
||
- Bei Stage-Wechsel zu `lost`: Bestätigungs-Dialog erzwingt `lost_reason`-Auswahl
|
||
- Optional: Freitext-Notiz
|
||
- Reverse innerhalb 24h möglich
|
||
|
||
**Klartext-Hinweise:**
|
||
- Won-Stage: Banner *„Dieser Deal wurde als gewonnen markiert am [Datum]. [Won-Status zurücknehmen — 24h verfügbar]"*
|
||
- Lost-Stage: Banner *„Dieser Deal ist als verloren markiert. Grund: [Reason]. [Wieder öffnen]"*
|
||
- Stuck: Banner *„Dieser Deal ist seit X Tagen in Stage [Name] — typisch sind Y Tage. Soll eine Erinnerung erstellt werden?"*
|
||
- Verknüpfter Kontakt archiviert: Hinweis *„Der zugeordnete Kontakt ist archiviert"* mit Reaktivierungs-Link
|
||
|
||
---
|
||
|
||
## Block F — Deal-Lifecycle
|
||
|
||
### Deal-Anlage-Quellen
|
||
|
||
**Manuelle Anlage** (`/{tenant}/deals/new`):
|
||
- Pflichtfelder: Titel, Pipeline (Default = is_default), Verantwortlicher (Default = current_user), Verknüpfter Kontakt (Auto-Complete-Suche aus M1)
|
||
- Optionale Felder: Volumen, erwarteter Close-Date, Description, Tags, verknüpfte Firma, Custom-Felder
|
||
- Bei Anlage: Deal startet in der ersten Stage (`position=0`) der gewählten Pipeline
|
||
- Deal-Nummer wird automatisch generiert
|
||
|
||
**Aus Lead-Promotion (M1):**
|
||
- Promotion-Modal optional „Deal anlegen" (Default ja)
|
||
- Lead-Daten werden auf Deal-Felder gemappt
|
||
- `Deal.lead_id` zeigt auf Lead, Lead bekommt `converted_to_deal_id`
|
||
|
||
**Aus Form-Submission (M5):**
|
||
- Form-Action „Deal anlegen" konfigurierbar pro Form
|
||
- Field-Mapping vom Tenant-Admin definiert
|
||
- Submission wird über `DealForm` verknüpft
|
||
|
||
**Aus Email-Conversation (M9):**
|
||
- „Deal aus dieser Email anlegen"-Funktion in Email-Detail
|
||
- Auto-Match: existierender Kontakt mit Email → vorausgewählt
|
||
- Email-Subject wird Deal-Titel-Vorschlag
|
||
|
||
**Aus Anruf (M12):**
|
||
- AirCall-Webhook nach Anruf → optionale Deal-Anlage in Anruf-Detail
|
||
- Auto-Match Telefon → Kontakt
|
||
- Anruf-Notiz wird Deal-Description-Vorschlag
|
||
|
||
**Aus Automation (M17):**
|
||
- Action `create-deal` mit konfigurierbarem Mapping
|
||
- Trigger z.B. „neuer Lead aus Quelle X"
|
||
|
||
### Stage-Wechsel-Validation
|
||
|
||
- Vorwärts-Wechsel: erlaubt
|
||
- Rückwärts-Wechsel: erlaubt mit Klartext-Hinweis
|
||
- Wechsel zu Won/Lost: Bestätigungs-Workflow (siehe Block E)
|
||
- Wechsel von Won/Lost zurück: nur 24h Reverse-Window
|
||
- Pipeline-Wechsel: erfordert `tenant.admin` oder `deals.admin`, Activity wird mit Diff geschrieben
|
||
|
||
### Auto-Archive
|
||
|
||
- Won-Deals: nach 30 Tagen ins Archiv (konfigurierbar pro Pipeline)
|
||
- Lost-Deals: nach 90 Tagen ins Archiv (konfigurierbar pro Pipeline)
|
||
- Archivierte Deals bleiben in Reports/KPIs sichtbar
|
||
- Tenant-Admin kann Auto-Archive deaktivieren
|
||
|
||
### Stage-Stuck-Detection (Cron)
|
||
|
||
- `auto_archive_after_days` pro Stage konfigurierbar
|
||
- Daily-Cron markiert Deals, die länger als Schwelle in einer Stage sind
|
||
- Stuck-Status zeigt sich als visueller Hinweis im Kanban + Banner im Detail
|
||
- Optional: Automation-Trigger `deal.stuck.in_stage`
|
||
|
||
### Reaktivierung archivierter Deals
|
||
|
||
- Tenant-Admin oder Verantwortlicher kann reaktivieren
|
||
- Reaktivierung setzt `archived_at = null`, führt Deal in ursprüngliche oder gewählte Stage zurück
|
||
- Activity-Eintrag
|
||
|
||
### Hard-Delete
|
||
|
||
- Erfordert `deals.admin`
|
||
- Multi-Step-Confirm mit Klartext-Warnung über Anzahl verknüpfter Tasks/Files/Activities
|
||
- Falls Deal mit Won-Handoff verknüpft (`won_handoff_project_id != null`): Block, *„Dieser Deal hat ein verknüpftes Projekt. Bitte zuerst Verknüpfung lösen oder Projekt selbst archivieren/löschen."*
|
||
- Audit-Trail bleibt nach Hard-Delete (Hash-Eintrag mit Lösch-Datum + User)
|
||
|
||
---
|
||
|
||
## Block G — Forecast & KPIs
|
||
|
||
> Diese Metriken werden im Dashboard-Modul (M20) als Widgets gezeigt. Sales-Pipeline stellt Datenquellen und Berechnungen bereit.
|
||
|
||
### Forecast-Berechnung
|
||
|
||
**Pipeline-Forecast (pro Pipeline und cross-pipeline):**
|
||
- Summe über alle aktiven Deals (nicht in Won/Lost-Stage, nicht archiviert): `volume × stage.win_probability / 100`
|
||
- Beispiel: Deal über 25.000 EUR in Stage „Verhandlung" mit `win_probability=70` → trägt 17.500 EUR zum Forecast bei
|
||
- Aufteilbar nach Zeitraum (anhand `expected_close_date`): „dieser Monat", „dieses Quartal", „nächste 12 Monate"
|
||
|
||
**Realisierter Umsatz:**
|
||
- Summe `volume` aller Deals mit `stage_kind=won` und `actual_close_date` im Zeitraum
|
||
- Vergleichbar zum Forecast als Genauigkeits-Indikator
|
||
|
||
### KPIs pro Vertriebler
|
||
|
||
- Aktive Deals (Anzahl + Gesamt-Volumen)
|
||
- Forecast-Beitrag (gewichtetes Volumen)
|
||
- Won-Rate (`won / (won + lost)` der letzten 90 Tage)
|
||
- Aktivitäts-Metriken (basierend auf Activity-Stream): Anzahl Anrufe, Mails, Termine
|
||
- Durchschnittliche Cycle-Time (Tage von Anlage bis Won)
|
||
- Stuck-Deals (Anzahl in Stuck-Status)
|
||
|
||
### Stage-Conversion-Rates
|
||
|
||
Pro Pipeline: *„Wie viele % der Deals, die je in Stage A waren, kommen in Stage B an?"* — berechnet aus `stage_changed`-Activities.
|
||
|
||
### Lost-Reason-Auswertung
|
||
|
||
Anteilige Verteilung der Lost-Reasons.
|
||
|
||
### Performance-Anforderungen
|
||
|
||
- Aggregat-Cache pro Stage (Deal-Count + Volumen-Summe)
|
||
- Stage-Verweildauer-Index auf Activity-Tabelle
|
||
- Forecast-Cache pro Pipeline + Zeitraum
|
||
- KPI-Berechnung server-side
|
||
|
||
---
|
||
|
||
## Block H — Integration mit anderen Modulen
|
||
|
||
### Lead → Projekt (M1)
|
||
- Lead → **Projekt**-Konvertierung (kein Deal, kein 4-Optionen-Modal); Kontakt separat verknüpft, AD-20
|
||
- `Projekt.konvertiert_aus_lead_id` gesetzt; Lead-Activity-Stream wandert in den Projekt-Activity-Stream
|
||
|
||
### Gewinn → Auftrags-Pipeline (M4) — Pipeline-Wechsel, kein Won-Handoff
|
||
- Bei Status-Wechsel zu `gewonnen` mit Bestätigung: **dasselbe Projekt** wechselt in die Auftrags-Pipeline (M4-Sicht)
|
||
- **Kein** Feld-Mapping, **kein** zweiter Datensatz, **kein** `won_handoff_project_id` (AD-20)
|
||
|
||
### Form-Submission → Deal (M5)
|
||
- Form-Action „Deal anlegen" pro Form konfigurierbar
|
||
- Field-Mapping vom Tenant-Admin definiert
|
||
- Submission über `DealForm` verknüpft
|
||
|
||
### Email-Sync → Deal (M9)
|
||
- Eingehende Mail mit Bezug zu verknüpftem Kontakt erscheint im Activity-Stream
|
||
- Manuelle „Deal aus Mail anlegen"-Funktion
|
||
- Email-Subject-Pattern (z.B. `[D-2026-0042]`) → Auto-Verknüpfung
|
||
|
||
### Telefonie → Deal (M12)
|
||
- AirCall-Anrufe werden mit Kontakt verknüpft, erscheinen im Activity-Stream
|
||
- Click-to-Call aus Deal-Detail
|
||
- Anruf-Notiz nach Anruf editierbar
|
||
|
||
### Automation-Engine (M17)
|
||
|
||
**Trigger aus Sales-Pipeline:**
|
||
- `deal.created`
|
||
- `deal.stage_changed` (mit `from_stage`, `to_stage`)
|
||
- `deal.won` / `deal.lost`
|
||
- `deal.stuck.in_stage` (Cron-basiert)
|
||
- `deal.assignee_changed`
|
||
|
||
**Actions für Sales-Pipeline:**
|
||
- `create-deal`
|
||
- `update-deal-stage`
|
||
- `update-deal-volume`
|
||
- `assign-deal-to-user`
|
||
- `create-project-from-deal` (Won-Handoff)
|
||
|
||
### Tasks (M26)
|
||
- Tasks können mit Deal verknüpft werden
|
||
- Sichtbar im Deal-Detail Tab „Tasks"
|
||
|
||
### Custom-Felder (M1 Block F)
|
||
- Deal hat eigene Custom-Definitionen mit `applicable_to=deal`
|
||
- SHK-Template-Defaults: *„Anlagen-Typ"* (select), *„Wärmebedarf kW"* (number), *„Bestandsanlage"* (boolean)
|
||
|
||
---
|
||
|
||
## Block I — Permissions-Anwendung (mit Field-Level-Permissions)
|
||
|
||
### Object-Level-Permission-IDs
|
||
|
||
| Permission | Erlaubt |
|
||
|---|---|
|
||
| `deals.read_own` | Deals sehen, bei denen User = `assigned_to_user_id` |
|
||
| `deals.read_all` | Alle Deals sehen |
|
||
| `deals.write` | Anlegen + Bearbeiten (Permissions-aware) |
|
||
| `deals.change_stage` | Stage-Wechsel (kann separat sein, z.B. Junior darf editieren aber nicht Won markieren) |
|
||
| `deals.delete` | Hard-Delete |
|
||
| `deals.admin` | Pipeline-Verwaltung, Lost-Reasons-Verwaltung, Bulk-Operations, Forecast-Reports |
|
||
|
||
### Field-Level-Permission-IDs
|
||
|
||
| Permission | Erlaubt |
|
||
|---|---|
|
||
| `deals.read_volume_own` | Volumen *eigener* Deals sehen |
|
||
| `deals.read_volume_all` | Volumen *aller* sichtbaren Deals sehen |
|
||
| `deals.read_aggregates` | Aggregierte KPIs (Forecast, Stage-Volumen, Sales-Performance-Charts) sehen |
|
||
| `deals.read_close_date_all` | Erwartete Close-Dates aller Deals sehen (sonst nur eigene) |
|
||
|
||
### Bundle-Mapping (Variante 2)
|
||
|
||
| Bundle | Atomare Permissions |
|
||
|---|---|
|
||
| `deals.none` | (keine) |
|
||
| `deals.read_own` | `deals.read_own` + `deals.read_volume_own` |
|
||
| `deals.read_all` | `deals.read_own` + `deals.read_all` + `deals.read_volume_own` |
|
||
| `deals.write` | `deals.read_all` + `deals.read_volume_all` + `deals.read_aggregates` + `deals.read_close_date_all` + `deals.write` + `deals.change_stage` |
|
||
| `deals.admin` | alle obigen + `deals.delete` + `deals.admin` |
|
||
|
||
Field-Level-Permissions können im Advanced-Mode atomar überschrieben werden für Spezialfälle.
|
||
|
||
### SHK-Template-Default-Rollen
|
||
|
||
| Rolle | Deal-Permissions |
|
||
|---|---|
|
||
| GF | `deals.admin` (alles inkl. Volumen + Aggregate) |
|
||
| Vertriebsleiter | `deals.write` + `read_volume_all` + `read_aggregates` |
|
||
| Vertriebler | `deals.read_all` + `read_volume_own` + `write_own` (sieht alle Deals, aber Volumen nur bei eigenen) |
|
||
| Projektleiter / Bauleiter | `deals.read_all` (sieht Deals als Kontext, **kein** Volumen, **keine** Aggregate) |
|
||
| Büro | `deals.read_all` + `read_volume_all` (für Rechnungen/Aufträge) |
|
||
| Marketing | `deals.read_all` + `read_aggregates` (Conversion-Analyse, **ohne** Volumen-Detail) |
|
||
| Monteur | `deals.none` |
|
||
|
||
### UI-Anwendung der Field-Level-Permissions
|
||
|
||
- Volumen-Feld ohne Read-Permission: zeigt *„—"* oder ist ausgeblendet (Kanban-Karte + Detail-View + Listen-Spalte)
|
||
- Aggregat-Volumen pro Stage-Spalte im Kanban: ausgeblendet ohne `read_aggregates`
|
||
- Forecast-Widget im Dashboard: ausgeblendet ohne `read_aggregates`
|
||
- Custom-Felder mit sensitiven Daten (z.B. Marge): kommen in Phase 2 mit Field-Level-Permission pro Custom-Feld
|
||
|
||
### Anwendung in Routes
|
||
|
||
- `/{tenant}/deals` → `deals.read_own` oder `deals.read_all`
|
||
- `/{tenant}/deals/list` → analog
|
||
- `/{tenant}/deals/pipelines/:id` → analog
|
||
- `/{tenant}/deals/new` → `deals.write`
|
||
- `/{tenant}/deals/:id` → `deals.read_own` (mit Owner-Check) oder `deals.read_all`
|
||
- `/{tenant}/deals/archive` → analog
|
||
- `/{tenant}/admin/sales/pipelines` → `tenant.admin` ODER `deals.admin`
|
||
- `/{tenant}/admin/sales/lost-reasons` → analog
|
||
|
||
### Klartext-Fehler
|
||
|
||
- Zugriff auf nicht-eigenen Deal mit `read_own`: 404 (nicht 403)
|
||
- Stage-Wechsel ohne `change_stage`: Server-side abgelehnt, Klartext: *„Du darfst Deals nicht in andere Phasen verschieben. Bitte einen Vertriebsleiter."*
|
||
- Won-Handoff ohne `projects.write`: Klartext: *„Du kannst diesen Deal als gewonnen markieren, aber das automatische Anlegen eines Projekts erfordert zusätzliche Berechtigung. Möchtest du nur den Won-Status setzen?"*
|
||
- Volumen-Feld ohne Read-Permission: kein expliziter Fehler, einfach *„—"* angezeigt (Permissions-aware-Default, AV #5)
|
||
|
||
---
|
||
|
||
## Architektur-Vorschriften (Querschnitt)
|
||
|
||
- **LP-3, AV #3:** SHK-Pipelines + Lost-Reasons sind Branchen-Template-Seeding, nicht Hardcode
|
||
- **LP-4:** Sales-Pipeline ist Commodity (HubSpot-Ablösung) — sauber bauen, aber kein Über-Engineering
|
||
- **LP-10, AV #1:** Klartext-Diagnostik überall (Stage-Validation, Stuck-Hinweise, Won/Lost-Bestätigung)
|
||
- **AV #5:** Permissions-aware-Default in allen Listen/Filtern
|
||
- **AV #6:** Audit-Trail-Default für alle schreibenden Aktionen (insb. Stage-Wechsel)
|
||
|
||
---
|
||
|
||
## Detail-Spec-Status: DRAFT
|
||
|
||
Erste vollständige Detail-Spec für Modul 3. **Vor Bau:** Verifizierung mit Noah. Bei Implementierung dann konkrete Index-Definitionen, Migrations-SQL und Caching-Strategie ergänzen.
|
||
|
||
**Offene Detail-Punkte:**
|
||
- Konkrete Index-Strategie pro Tabelle
|
||
- WebSocket vs. SSE für Real-Time-Kanban-Updates (Boilerplate-Entscheidung)
|
||
- Cache-Invalidierungs-Strategie für Aggregate (Pub/Sub vs. Trigger-basiert)
|
||
- Konkrete Won-/Lost-Reverse-Mechanik (Soft-Revert vs. neue Stage-Activity)
|
||
- Konkrete SHK-Stage-Probabilities mit Noah finalisieren
|