Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
1 parent 3cb93a81be
commit be2054274d
5885 files changed
+2588 -195

No files matched your search

@@ -0,0 +1,620 @@
---
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