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

27 KiB
Raw Blame History

module, title, phase, status, last_updated, session_source, related_lps, spec_style
module title phase status last_updated session_source related_lps spec_style
3 Sales-Pipeline (Deals) 1 detail-spec-draft 2026-05-08 brainstorming-session-2026-05-07-2206.md
LP-3
LP-4
LP-7
LP-9
LP-10
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