52 lines
8.4 KiB
Markdown
52 lines
8.4 KiB
Markdown
# 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-Verkaufsfall 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:
|