Files
HiveGrid-Wireframes/hivegrid-cloud/_bmad-output/specs/M03-sales-pipeline.md
T

621 lines
27 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.
---
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