Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/designer-briefs/P08-projekt-pipelines-kern.md
T
2026-07-08 16:15:37 +02:00

52 lines
8.4 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.
# Designer-Brief · P8 — Projekt & Pipelines (Kern + Pipeline-Engine)
**Phase:** 8/21 · **Modul:** M03 · **Owner-Dev:** Raffael (R-P8a/b) · **Designer:** David (D-CRM, Kanban-Paket Fr 26.06.)
**Quellen:** `ROADMAP.md` §Phase 8 (+ Pivot-Note) · `ENTITY-MODEL.md` Domäne 5 (Projekt-Kern + Pipeline/Stage/FieldConfig/Access) + Kern-Ketten-Diagramm + Modellierungs-Fragen 3/4 · `SCREEN-MAP.md` §3 (Kanban, Pipeline-Editor) · `REQUIREMENTS.md` (REQ-sales-*) · `_bmad-output/specs/M03-sales-pipeline.md`
**Subframe:** Pflicht je Route. Archetypen aus D0 (A2 Liste, A3 Detail, A6 Settings, KPI-Kit); Pipeline-Kanban ist **BESPOKE**.
> 🔴 **Pivot-Vorrang (AD-20):** Für Projekt & Pipelines gilt das **`ENTITY-MODEL.md`**, nicht die teils noch pre-Pivot-SCREEN-MAP. Konkret: Es gibt **EINEN `Projekt`-Kern** (typisierte Superset-Tabelle: Deal- + Auftrags-Felder in einer Tabelle) und **konfigurierbare Pipeline-Views**. **„Deal" und „Auftrag" sind Pipeline-Typen (`Pipeline.typ_hint = sales/auftrag/custom`), KEINE eigenen Entitäten.** Es gibt **EINEN konfigurierbaren Pipeline-Kanban** statt getrenntem Sales-Kanban + Projekt-Kanban (SCREEN-MAP §3 zeigt noch „Sales-Kanban [/deals]" — überholt; Route/Wording = projekt-zentrisch). **Kein Won-Handoff** und **kein zweiter Datensatz**: ein Projekt wechselt nur die Pipeline. **`Status` ist immer pipeline-intern** (`PipelineStage.stage_kind = offen/gewonnen/verloren`); es gibt keinen globalen Projektstatus. Neu gegenüber alter Spec: der **Pipeline-Feld-Config-Layer** (`PipelineFieldConfig`: Sichtbarkeit + Pflicht je Feld pro Pipeline+Status) und **`PipelineAccess`** (wer darf Pipeline sehen/bearbeiten) — Field-Level-Sichtbarkeit (z.B. Volumen nur für Vertrieb) läuft jetzt darüber statt nur über harte `deals.read_volume_*`-Bundles. Wo M03-Spec von „Deal"/„won_handoff_project_id" spricht, ist der `Projekt`-Kern bzw. ein Pipeline-Wechsel gemeint.
## Was dieses Modul tut (Kurzfassung)
Baut den `Projekt`-Kern als eine typisierte Tabelle (Superset der Felder, dazu `CustomFieldValue`) und die Pipeline-Engine als frei konfigurierbare Views: Pipeline anlegen/benennen/duplizieren, Statuswerte (Stages) je Pipeline, Zugriff je Rolle/User/Gruppe (`PipelineAccess`), Feld-Sichtbarkeit + Pflichtfelder pro Pipeline+Status (`PipelineFieldConfig`). Darauf der EINE konfigurierbare Kanban (ein Board für alle Pipeline-Typen) plus Listen-View, Projekt-Detail, fortlaufende Projekt-Nummern (HiveNumberSeq), Forecast/KPIs und Lost-Reasons. Konsumiert das `lead.qualified`-Event aus P7 (Auto-Projekt M049 = Projekt in Sales-Pipeline). Auftrags-Features + Sub-Areas folgen in P9.
## Benötigte Screens
| Screen [Route] | Kern-Inhalt | Archetyp |
|---|---|---|
| **Pipeline-Kanban (konfigurierbar)** [`/projects` bzw. `/projects/pipelines/:id`] | Spalten = Stages der gewählten Pipeline (in Reihenfolge): Stage-Name, Projekt-Anzahl, Aggregat-Volumen (gegated), Win-% · Projekt-Karten: Titel, Volumen (gegated über PipelineFieldConfig + Field-Level-Perms), Verantwortlicher-Avatar, Close-/Zeitraum-Datum, max. 3 Tags, Stuck-/Überzogen-Marker · **Drag&Drop** Stage-Wechsel mit Validation · Drop in `gewonnen`-Stage → Bestätigung · Drop in `verloren`-Stage → Lost-Reason-Pflicht · **Pipeline-Switcher** (zwischen sales/auftrag/custom-Pipelines) · Filter (Verantwortlicher/Tags/Volumen-Range/Datum) + „nur meine" · Bulk-Select · Pagination pro Spalte (100+) · Real-Time (SSE) | **BESPOKE** (ein Board für ALLE Pipeline-Typen) |
| Projekt-Liste [`/projects/list`] | Projekt-Nummer, Titel, Pipeline, Status (Stage), Volumen (gegated), verknüpfter Kontakt/Firma, Zeitraum/Close-Datum, letzte Activity · Cross-Pipeline-Sicht mit Pipeline-Spalte + -Filter · sortierbare Header, Spalten-Konfig, Bulk, CSV-Export, Pagination | A2 |
| **Projekt-Detail** [`/projects/:id`] | Stammdaten inline-editierbar (Nummer, Name, Beschreibung, Volumen/potenzieller Wert, Pipeline, Stage, Zeitraum, Adressen-Slots) · verknüpfte Kontakte mit Rolle (auftraggeber/bauherr/rechnungsempfaenger/ansprechpartner) · Lead-Herkunft-Hinweis (`konvertiert_aus_lead_id`) · **Status-Visualisierung als klickbare Stage-Bar** (pipeline-intern) · Stage-Historie mit Verweildauer · Gewonnen/Verloren-Banner mit 24h-Rückgängig · Tags · Custom-Felder (pro Pipeline via PipelineFieldConfig geschaltet) · Activity-Stream · Quick-Actions (Anrufen/Email/Termin/Task/Notiz) · Sub-Area-Tabs (Termine/Aufgaben/Aktivitäten/Dokumente — Rechnungen/Checklisten/Abnahme in P9) | A3 (Muster-Detail-View) |
| **Pipeline-Config-Admin** [`/admin/pipelines` bzw. `/admin/pipelines/:id`] | Pipelines-Liste (Name, typ_hint, Stage-Anzahl, aktive Projekte, Status) · Editor: Stages mit Drag&Drop je Name/stage_kind (offen/gewonnen/verloren)/Win-%/Farbe · **PipelineAccess** (wer darf sehen/bearbeiten: Rolle/User/Gruppe, kann_sehen/kann_bearbeiten) · **PipelineFieldConfig** (pro Feld — System ODER `custom:<id>` — Sichtbarkeit + Pflicht + Reihenfolge, optional je Status) · Validation min. 1 gewonnen + 1 verloren · neue Pipeline anlegen/duplizieren/archivieren | A2 + A6 |
| Lost-Reasons [`/admin/pipelines/lost-reasons`] | Liste: Name, Anzahl verknüpfter Projekte, Status · Add/Edit/Archive (kein Hard-Delete — Reporting) · SHK-Default 5 Reasons geseedet | A2 |
| Forecast/KPI-Quellen (Dashboard-Widgets in P11) | Datenquellen/Berechnungen: Pipeline-Forecast (Volumen × Win-%), realisierter Umsatz, KPIs pro Verantwortlichem, Stage-Conversion-Rates, Lost-Reason-Verteilung · Aggregat-Cache | (kein eigener Screen — Widgets in P11) |
*(Sales-Kanban [`/deals`] + Projekt-Kanban [`/projects`] aus SCREEN-MAP §3/§4 sind EIN Board. „Deal-Liste/Deal-Detail/Pipeline-Editor [/admin/sales/...]" → projekt-zentrische Routen oben. Plantafel + Rechnungen/Checklisten/Abnahme-Sub-Areas → P9.)*
## Geplante Features (muss abgedeckt sein)
- [ ] **EIN `Projekt`-Kern** (typisierte Superset-Tabelle, Deal- + Auftrags-Felder, + CustomFieldValue) mit fortlaufenden Projekt-Nummern (HiveNumberSeq); RLS + Soft-Delete
- [ ] **Pipeline-Engine:** Pipeline anlegen/benennen/duplizieren/archivieren (`typ_hint` sales/auftrag/custom); Stages = die Statuswerte; min. 1 gewonnen + 1 verloren
- [ ] **PipelineAccess** (Sichtbarkeit/Bearbeitung je Rolle/User/Gruppe) + **PipelineFieldConfig** (Feld-Sichtbarkeit + Pflicht + Reihenfolge je Pipeline/Status); nicht sichtbare Felder bleiben erhalten
- [ ] **EIN konfigurierbarer Kanban** (Drag&Drop, Stage-Wechsel-Validation, gewonnen/verloren-Workflow, Real-Time SSE) + Listen-View mit Filter/Bulk/CSV
- [ ] Lead→Projekt-Eingang (P7) + `lead.qualified`→Auto-Projekt in Sales-Pipeline (M049); Pipeline-Wechsel statt Won-Handoff (kein zweiter Datensatz)
- [ ] Forecast, KPIs pro Verantwortlichem, Stage-Conversion-Rates, Lost-Reason-Auswertung mit Aggregat-Cache
- [ ] Field-Level-Sichtbarkeit (Volumen/Aggregate) primär über PipelineFieldConfig; `deals.read_volume_*`/`read_aggregates` als Permission-Backstop — Volumen ohne Recht zeigt „—"
## Benötigte UI-Elemente (Liste, KEIN Layout — Anordnung = Davids freie Hand)
Kanban-Board (Spalten = Stages, horizontal scrollbar/responsive), Drag&Drop-Karten, Stage-Spalten-Header mit Aggregat (Count + Volumen + Win-%), Projekt-Karte (Titel, gegatetes Volumen, Avatar, Datum, Tag-Chips, Stuck-Marker), Pipeline-Switcher, Filter-Bar + „nur meine"-Quick-Filter, Bulk-Action-Toolbar, gewonnen/verloren-Bestätigungs-Dialog (Lost-Reason-Pflicht), 24h-Rückgängig-Banner, Daten-Tabelle (sortierbar, paginiert, Spalten-Konfig, CSV), Detail-Panel mit Inline-Edit, klickbare Status-/Stage-Bar, Stage-Historie mit Verweildauer, Lead-Herkunft-Hinweis, Relations-Liste mit Rollen-Badge, Custom-Feld-Renderer je Typ, Tag-Chips, Activity-Timeline, Quick-Action-Buttons, Pipeline-Editor (Stage-Drag&Drop, stage_kind/Win-%/Farbe), PipelineAccess-Matrix (Principal × sehen/bearbeiten), PipelineFieldConfig-Liste (Feld × sichtbar/pflicht/Reihenfolge je Status), Lost-Reasons-CRUD-Liste, KPI-Kacheln/Charts (Forecast/Conversion/Lost-Verteilung), „Volumen verborgen (—)"-Zustand, Empty-/Loading-/Fehler-/Permission-Denied-States (Klartext).
## Davids Delta (David füllt aus)
- [ ] Überschriebene/geänderte Spec-Punkte:
- [ ] Neue UI/UX-Entscheidungen:
- [ ] Subframe-Screen-Link(s):
- [ ] Offene Fragen an Dev:
## Dev-Nachzug (wir nach Davids Delta)
- [ ] Spec/ENTITY-MODEL an Davids Entscheidungen angepasst:
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen:
- [ ] Plane-Ticket (R-P8a/b) aktualisiert: