Files
HiveGrid-Wireframes/hivegrid-cloud/_bmad-output/specs/M04-auftragspipeline.md
T

707 lines
30 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: 4
title: Auftrags- / Projektpipeline
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-2, LP-3, LP-4, LP-7, LP-9, LP-10, LP-11]
spec_style: requirements-pur
---
# Modul 4 — Auftrags- / Projektpipeline
> 🔴 **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:
> - **EIN `Projekt`-Kern** — derselbe Datensatz wie in der Sales-Sicht (M3). „Auftrag" ist eine **Pipeline-View** (`typ_hint=auftrag`), keine eigene Entität. `ProjectPipeline`/`ProjectPipelineStage` = die generischen `Pipeline`/`PipelineStage`. `Project` = `Projekt`.
> - **KEIN Won-Handoff / kein `source_deal_id`.** Das Projekt **entsteht nicht aus einem Deal**, es wechselt nur die Pipeline. Es gibt keinen separaten „Deal"-Datensatz und keine Sales→Auftrag-Kopie. Die **„Sales-Verlauf (read-only)"-Sektion entfällt** als Fremd-Objekt-Ansicht: Status-Historie/Aktivitäten/Files sind direkt am selben Projekt (Filter „aus Sales-Phase" optional, aber editierbar im selben Datensatz).
> - **`AcceptanceProtocol`** = immutable Sub-Area am Projekt (+ `AbnahmeSignatur`); **„Mängel" = Checkliste** (`Checkliste`/`ChecklistItem`, typ=maengel), kein `defects[]`-JSON. **`Rechnung`** ist v1 NEU als Sub-Entity am Projekt (E3).
> - **Mitglieder** über `ProjektMitglied` (Rolle projektleiter/monteur/zustaendig/beobachter). Rechte/Sichtbarkeit komplex schon v1 via `PipelineAccess`+`PipelineFieldConfig`+**`PipelineFieldVisibility`** (Field-Level, z.B. Volumen) — ersetzt die unten beschriebenen `projects.read_volume_*`-Bundles für Feld-Sichtbarkeit.
> - **KWP komplett v2** (Block I „M19 KWP-Integration" = v2; auch kein Feld-Halter v1). **PWA-only** (AD-17; kein Expo/native), v1 DE-only. **Customer-Portal (M15) = v2.**
> **Detail-Spec gemäß LP-9.** Geerkens-Kern. Auftragsabwicklung vom Pipeline-Wechsel (Gewinn in der Sales-Sicht) bis Abnahme — **kein Won-Handoff, ein Projekt-Datensatz** (AD-20).
## Themenblöcke
```
A. Datenmodell (ProjectPipeline, Stages, Project, Member, ScheduleEntry, AcceptanceProtocol)
B. Menü-Struktur und Routes
C. Pipeline-Verwaltung
D. Kanban / Listen / Plantafel-View
E. Project-Detail-View (mit Sales-Verlauf-Sektion)
F. Project-Lifecycle
G. Plantafel (Ressourcen-/Termin-Planung)
H. Acceptance-Protokoll (Abnahme)
I. Integration mit anderen Modulen
J. Permissions-Anwendung (Object + Field-Level)
```
---
## Block A — Datenmodell
### Architektur-Entscheidung (revidiert AD-20)
EIN `Projekt`-Kern; die Auftrags-Pipeline ist eine **View** (`typ_hint=auftrag`) auf denselben Datensatz wie die Sales-Sicht (M3). `Pipeline`/`PipelineStage` sind konfigurierbare First-Class-Tabellen, Multi-Pipeline ab Tag 1 (SHK hat verschiedene Auftragstypen: Anlagen-Installation vs. Wartungseinsatz vs. Notfall-Reparatur). **Lies `ProjectPipeline`→`Pipeline`, `Project`→`Projekt`.**
### Kern-Entitäten
```
ProjectPipeline — Auftrags-Pipeline pro Tenant
ProjectPipelineStage — Stage innerhalb einer Pipeline
Project — ein konkreter Auftrag
ProjectMember — Mitarbeiter-Zuordnung (M:N)
ScheduleEntry — Plantafel-Eintrag (Person + Projekt + Zeitraum)
AcceptanceProtocol — Abnahmeprotokoll (1:N pro Project, für Teilabnahmen)
ProjectForm — Verknüpfung Project ↔ Form-Submissions
ProjectTemplate — Projekt-Vorlagen pro Tenant
```
### ProjectPipeline
- `id`, `tenant_id`, `name`, `description`, `is_default`, `position`, `archived_at`
### ProjectPipelineStage
- `id`, `tenant_id`, `pipeline_id`, `name`, `position`
- `stage_kind` (Enum: `open | completed | cancelled`)
- `requires_acceptance_protocol` (Boolean — Stage erzwingt ausgefülltes Acceptance vor Wechsel)
- `auto_archive_after_days`
- `color`
- `archived_at`
**Validation:** Pipeline muss mind. 1 `completed`-Stage haben. Falls Stage `requires_acceptance_protocol = true`: muss zugewiesene Acceptance-Form-Template haben (oder Tenant-Default).
### Project
- `id`, `tenant_id`, `created_at`, `updated_at`, `created_by_user_id`
- `project_number` (fortlaufend, z.B. „P-2026-0042")
- `pipeline_id`, `stage_id`
- `title` (Pflicht)
- `description` (Markdown)
- `volume` (`numeric(12,2)`)
- `currency` (Default EUR)
- `start_date`, `expected_end_date`, `actual_end_date`
- `address_street`, `address_zip`, `address_city`, `address_country` (Baustellen-/Auftrags-Adresse — kann von Kontakt-Adresse abweichen)
- `assigned_pl_user_id` (Hauptverantwortlicher)
- `contact_id` (FK auf primären Kontakt — Pflicht; im Modell über `ProjektKontakt`)
- `company_id` (optional; = Kontakt mit kontakt_typ=organisation)
- `konvertiert_aus_lead_id` (FK auf Lead, **nullable** — falls aus Lead→Projekt entstanden) *(pre-pivot: `source_deal_id` — es gibt keinen Deal-Datensatz, AD-20)*
- `template_id` (FK auf ProjectTemplate)
- `cancellation_reason` (Freitext, nur bei `cancelled`)
- `archived_at`
**Wichtig:** Ein Projekt entsteht **nicht aus einem Deal** (es gibt keinen). Anlage-Wege: Lead→Projekt, Sales-Pipeline-Sicht (Pipeline-Wechsel bei Gewinn), Notfall-Reparatur, Wartungstermin, manuelle Anlage, Automation, Template.
### ProjectMember (M:N)
- `id`, `project_id`, `user_id`
- `role_in_project` (Freitext, z.B. „Projektleiter", „Bauleiter", „Monteur", „Lehrling")
- `added_at`, `added_by_user_id`
- Mehrere Members pro Project; ein User in mehreren Projects möglich
### ScheduleEntry (Plantafel)
- `id`, `tenant_id`, `project_id`
- `assigned_user_id`
- `start_at`, `end_at`
- `note`
- `status` (Enum: `planned | confirmed | in_progress | done | cancelled`)
- Sync zu Calendar (M25)
### AcceptanceProtocol
- `id`, `project_id`, `tenant_id`, `created_at`, `created_by_user_id`
- `customer_name` (kann von `Project.contact` abweichen)
- `customer_signature_image` (Base64 oder File-ID)
- `customer_signature_ip`, `customer_signature_timestamp`
- `staff_signature_user_id`, `staff_signature_image`
- `notes` (Markdown)
- `defects[]` (JSON-Array — Beschreibung + Foto-IDs)
- `acceptance_kind` (Enum: `full | with_defects | rejected`)
- `form_submission_id` (FK auf Form-Submission der Acceptance-Form)
- **Nicht löschbar** (Audit-Compliance, rechtliche Aufbewahrungspflicht 6 Jahre)
### ProjectTemplate
- `id`, `tenant_id`, `name`, `description`
- Vorgefertigte Felder: Default-Pipeline, Default-Stage, Default-Members, Default-Tasks, Default-ScheduleEntries, Default-Custom-Felder
- Anwendung beim Project-Anlegen aus Template
### ProjectForm
- `project_id`, `form_submission_id`, `linked_at`
### Sales-Sicht ↔ Auftrags-Sicht (derselbe Projekt-Datensatz, AD-20)
> 🔴 **Pivot:** Es gibt **keine Deal↔Project-Verknüpfung**, weil es keinen Deal-Datensatz gibt. Ein Projekt durchläuft erst die Sales-Pipeline-Sicht und wechselt bei Gewinn in die Auftrags-Pipeline — **immer derselbe Datensatz**.
- **Pipeline-Wechsel** (Gewinn in der Sales-Sicht, M3) → Projekt wechselt in die Auftrags-Pipeline; kein zweites Objekt, kein Mapping.
- Brauchst du aus einem gewonnenen Projekt mehrere Folge-Aufträge (z.B. Installation + Wartungsvertrag): das sind **separate Projekte** (neu angelegt, ggf. derselbe Kontakt) — kein „Mehrfach-Promotion aus einem Deal".
- *(Entfallen: frühere Wege A „Auto-Won-Handoff", B „Mehrfach-Promotion", C „nachträgliche `source_deal_id`-Verknüpfung".)*
### SHK-Template-Pipelines
**Pipeline 1: „Anlagen-Installation"**
1. Vorbereitung (open)
2. Disposition / Materialbestellung (open)
3. Ausführung (open)
4. Abnahme (open, `requires_acceptance_protocol = true`)
5. Abgeschlossen (completed)
6. Storniert (cancelled)
**Pipeline 2: „Wartungseinsatz"**
1. Termin geplant (open)
2. In Ausführung (open)
3. Abgeschlossen (completed)
4. Storniert (cancelled)
**Pipeline 3: „Notfall-Reparatur"**
1. Eingegangen (open)
2. Unterwegs (open)
3. Vor Ort (open)
4. Abgeschlossen (completed)
---
## Block B — Menü-Struktur und Routes
**Sidebar-Hauptpunkt:** *Aufträge* / *Projects*
```
/{tenant}/projects → Default-Pipeline (Kanban)
/{tenant}/projects/list → Cross-Pipeline Tabelle
/{tenant}/projects/pipelines → Pipeline-Switcher / Übersicht
/{tenant}/projects/pipelines/:id → Pipeline-Kanban
/{tenant}/projects/pipelines/:id/list → Pipeline-Tabelle
/{tenant}/projects/plantafel → Plantafel-View (Cross-Pipeline)
/{tenant}/projects/new → Neuer Auftrag
/{tenant}/projects/:id → Project-Detail
/{tenant}/projects/:id/acceptance → Acceptance-Protokoll-Liste
/{tenant}/projects/:id/acceptance/new → Neue Abnahme starten
/{tenant}/projects/archive → Archivierte Projekte
/{tenant}/admin/projects/pipelines → Pipeline-Verwaltung
/{tenant}/admin/projects/pipelines/:id → Pipeline-Editor
/{tenant}/admin/projects/templates → Project-Templates verwalten
/{tenant}/admin/projects/acceptance-forms → Acceptance-Form-Templates
```
**Mobile-Sichtbarkeit (LP-2 Baustelle-Modus):**
- `/{tenant}/projects/:id` und `/{tenant}/projects/:id/acceptance/new` haben mobile-first-optimierte Views
- Plantafel ist nicht mobile-optimiert; Monteur sieht stattdessen „Heute"-View seiner ScheduleEntries
---
## Block C — Pipeline-Verwaltung
Analog M3 mit Project-spezifischen Erweiterungen:
### Pipeline-Editor (`/{tenant}/admin/projects/pipelines/:id`)
**Pro Stage editierbar:**
- Stage-Kind (`open | completed | cancelled`)
- `requires_acceptance_protocol` (Boolean)
- Acceptance-Form-Template-Zuweisung (wenn Boolean = true)
- `auto_archive_after_days`
- Color
**Klartext-Validation:**
- *„Stage ‚Abnahme' verlangt Acceptance-Protokoll, aber kein Template ist zugewiesen. Bitte Template auswählen oder Pflicht deaktivieren."*
### Project-Templates (`/{tenant}/admin/projects/templates/`)
- Tenant-Admin definiert Vorlagen mit Default-Pipeline, Default-Stage, Default-Members, Default-Tasks, Default-ScheduleEntries, Default-Custom-Felder
### Acceptance-Form-Templates (`/{tenant}/admin/projects/acceptance-forms/`)
- Form-Builder-basiert (M5) mit Subtyp `acceptance_form`
- SHK-Default-Template wird beim Tenant-Anlegen geseedet
---
## Block D — Kanban / Listen / Plantafel
### Kanban-View (`/{tenant}/projects/pipelines/:id`)
**Zu zeigende Daten pro Project-Karte:**
- Project-Nummer, Titel
- Volumen (gegated über Field-Level-Permission)
- Mehrere Member-Avatare (PL hervorgehoben)
- Zeitraum (`start_date` → `expected_end_date`)
- Visueller Hinweis bei Stuck/Überzogen
- Visueller Hinweis bei offenen Mängeln aus Acceptance
- Tags
- Verknüpfter Kontakt + Adresse-Kurzform
**Operationen — Drag-&-Drop:**
- Bei Drag in Stage mit `requires_acceptance_protocol`: Block falls kein Acceptance-Protokoll. Klartext: *„Diese Stage erfordert ein Abnahmeprotokoll. [Acceptance starten]"*
- Bei Drag in `completed`-Stage: optional `actual_end_date` setzen
- Bei Drag in `cancelled`-Stage: `cancellation_reason`-Pflicht
**Filter, Bulk-Actions, Pagination:** analog M3.
### Listen-View (`/{tenant}/projects/list`)
Analog M3 mit Project-spezifischen Spalten (Pipeline, Stage, PL, Members-Anzahl, Zeitraum, Volumen).
### Plantafel-View
Siehe Block G.
---
## Block E — Project-Detail-View
### Project-Detail (`/{tenant}/projects/:id`)
**Zu zeigende Daten:**
- Project-Stammdaten (Number, Title, Description, Volume, Pipeline, Stage, Start-/End-Daten, Baustellen-Adresse)
- Verknüpfter Kontakt + Firma
- Source-Deal (falls vorhanden, Link zu M3)
- PL (`assigned_pl_user_id`)
- Members (alle ProjectMembers mit Rolle)
- Tags
- Custom-Felder (mit `applicable_to=project`)
- Tasks
- ScheduleEntries
- Files
- Form-Submissions (verknüpfte ProjectForms)
- AcceptanceProtocol(s)
- Activity-Stream (siehe M1 Block E + Project-spezifische Activities)
- Stage-Historie
**Benötigte UI-Elemente:**
- Sektionierte Anzeige der Stammdaten
- Inline-Edit für editierbare Felder
- Stage-Anzeige als visuelle Pipeline-Komponente (Klick auf andere Stage triggert Wechsel)
- Activity-Stream-Komponente
- Tab- oder Sektions-Navigation für: Übersicht / Members / Tasks / Schedule / Files / Forms / Acceptance / Sales-Verlauf / Custom-Felder
- Action-Funktionen für die Operationen unten
- Markdown-Editor für Description und Notizen
- Map-Anzeige der Baustellen-Adresse (falls Maps-Integration)
- **Mobile-Modus** (LP-2): vereinfachte Variante (Stammdaten + heutige Tasks + Acceptance-Funktion + Foto-Upload prominent — Plantafel/Custom-Felder/Activity-Stream reduziert)
**Operationen:**
- Stammdaten editieren
- Stage wechseln (mit Acceptance-Pflicht-Validation)
- PL ändern
- Member hinzufügen/entfernen/Rolle ändern (Multi-Add aus Group möglich)
- Tags
- Custom-Felder editieren
- Click-to-Call (zum Kontakt)
- Email schreiben
- Termin buchen
- Aufgabe anlegen (mit Project-Verknüpfung)
- Notiz hinzufügen
- File hochladen / Foto-Direct-Upload (Mobile)
- Form-Submission verknüpfen
- ScheduleEntry anlegen
- Acceptance-Protokoll starten
- Source-Deal-Verknüpfung ändern (mit `tenant.admin` oder `projects.admin`)
- Archivieren / Reaktivieren
- Hard-Delete (mit Reassign-Workflow)
**Klartext-Hinweise:**
- Project ohne Members: Banner *„Diesem Projekt sind keine Mitarbeiter zugewiesen. [Member hinzufügen]"*
- Offene Mängel aus Acceptance: roter Banner mit Mängel-Liste
- Stuck-Status: analog M3
- Completed/Cancelled: Banner mit Datum + 24h-Reverse-Funktion
**Mobile-spezifische Operationen:**
- One-Tap *„Foto vom Auftrag"*
- One-Tap *„Acceptance starten"*
- One-Tap *„Notiz diktieren"* (Whisper-EU-Transkription M18)
- Tasks mit Tap-Toggle zum Erledigen
### Sales-Phase-Filter (derselbe Datensatz, AD-20 — KEINE read-only Fremd-Objekt-Sektion)
> 🔴 **Pivot:** Da Sales- und Auftrags-Sicht **denselben Projekt-Datensatz** zeigen, gibt es keine „read-only Deal-Historie". Die frühere Sales-Phase ist die **Status-Historie desselben Projekts** in der Sales-Pipeline-Sicht.
**Zu zeigende Daten (alles am selben Projekt):**
- Frühere Sales-Status-Historie (durchlaufene Statuswerte, Gewinn-Datum, Verloren-Grund falls Reverse, Lead-Herkunft `konvertiert_aus_lead_id`)
- Activity-Stream — im Activity-Tab optional über Filter „Aus Sales-Phase" eingrenzbar
- Files / Form-Submissions aus der Sales-Phase — im selben Files-/Forms-Tab (optional Sektion „Aus Sales-Phase")
**Logik:**
- Daten sind **editierbar im selben Projekt** (kein Fremd-Objekt). Kein Klartext-Hinweis „bitte im Deal editieren".
**Permission-Wirkung:**
- Feld-Sichtbarkeit (z.B. Volumen) über `PipelineFieldVisibility` der jeweiligen Pipeline-Sicht — z.B. Bauleiter sieht Volumen verborgen, wenn die Field-Level-Rechte das so setzen.
**Edge-Cases:** entfallen (kein separater Deal, der archiviert/gelöscht werden könnte).
---
## Block F — Project-Lifecycle
### Anlage-Quellen
**(1) Manuell** (`/{tenant}/projects/new`):
- Pflicht: Titel, Pipeline (Default = is_default), PL, Verknüpfter Kontakt
- Optional: Volumen, Zeitraum, Adresse, Description, Tags, Firma, Members, Custom-Felder
**(2) Aus Sales-Pipeline-Sicht (M3)** — Pipeline-Wechsel bei Gewinn (derselbe Datensatz, **kein Won-Handoff**, AD-20).
**(3) Aus Form-Submission (M5)** — Form-Action „Projekt anlegen". Field-Mapping vom Tenant-Admin.
**(4) Aus Booking (M6)** — Wartungstermin-Buchung erzeugt automatisch Project in „Wartungseinsatz"-Pipeline.
**(5) Aus Anruf (M12)** — *„Notfall-Auftrag aus Anruf"* in AirCall-Webhook-Detail.
**(6) Aus Automation (M17)** — Action `create-project`.
**(7) Aus Template** — *„Aus Template erstellen"* füllt Pipeline, Stage, Default-Members, Default-Tasks, Default-Custom-Felder vor.
**Wichtig:** Es gibt keinen Deal-Datensatz; ein Projekt kann frisch (ohne Sales-Phase) angelegt werden. `konvertiert_aus_lead_id` ist nullable (AD-20).
### Stage-Wechsel-Validation
- Vorwärts/Rückwärts: erlaubt (Klartext bei Rückwärts)
- In Stage mit `requires_acceptance_protocol`: Block falls kein Acceptance
- In `completed`-Stage: optional `actual_end_date`
- In `cancelled`-Stage: `cancellation_reason` Pflicht
- Reverse aus Terminal-Stages: nur 24h-Reverse-Window
### Auto-Archive
- `completed`: nach 90 Tagen ins Archiv (konfigurierbar pro Pipeline)
- `cancelled`: nach 30 Tagen ins Archiv
- Archivierte bleiben in Reports sichtbar
### Stage-Stuck-Detection
Analog M3 mit `auto_archive_after_days`.
### Reaktivierung
- Tenant-Admin oder PL kann reaktivieren
- Member-Zuweisung wird bestätigt
### Hard-Delete
- Erfordert `projects.admin`
- **Block** falls aktive Acceptance-Protokolle (rechtliche Aufbewahrung)
- Reassign-Workflow für offene Tasks/Schedule-Entries/Files
- Klartext: *„Dieses Projekt hat 2 Acceptance-Protokolle und 14 verknüpfte Files (rechtlich aufbewahrungspflichtig). Hard-Delete blockiert. Bitte archivieren statt löschen."*
---
## Block G — Plantafel (Ressourcen-/Termin-Planung)
### Plantafel-View (`/{tenant}/projects/plantafel`)
**Zu zeigende Daten:**
- Y-Achse: Mitarbeiter-Liste
- X-Achse: Zeitraum (Tag / Woche / Monat — wechselbar)
- Im Raster: ScheduleEntries pro Person × Zeitslot
- Pro Block: Project-Titel, Status, Adresse-Kurzform, Color basierend auf Pipeline
- Optional sichtbar (Toggle): Urlaube + Krankmeldungen aus HR-Hub (M14), externe Calendar-Termine (M25), Verfügbarkeits-Regeln
**Benötigte UI-Elemente:**
- Zeitraum-Switcher (Tag/Woche/Monat/Custom)
- Mitarbeiter-Filter (Rolle, Group, Verfügbarkeit-Status)
- Project-Filter (Pipeline, Stage, Tag, Status)
- Drag-&-Drop für ScheduleEntries (Verschieben + Resize)
- „Neue ScheduleEntry"-Funktion (Klick auf leeren Slot)
- Visuelle Konflikt-Indikatoren bei Überschneidungen
- Zoom-Funktion
- Sync-Indikator zu Calendar-Push
- Mass-Reassign-Funktion
**Operationen:**
- ScheduleEntry anlegen / verschieben / resizen / löschen
- Status ändern (`planned → confirmed → in_progress → done | cancelled`)
- Bulk-Reassign (z.B. Krankheits-Vertretung)
- Templated-Anlage aus Project-Template (z.B. „Anlagen-Installation = 3 Tage Vorbereitung + 2 Tage Installation + 1 Tag Abnahme")
### Konflikt-Detection
- Doppel-Belegung: roter Indikator + Klartext: *„Max ist Mo 10-14 schon im Projekt P-2026-0042 verplant. Trotzdem zuweisen?"*
- Urlaub (HR-Hub): *„Max hat am Dienstag genehmigten Urlaub. Trotzdem zuweisen?"*
- Krankmeldung: *„Max ist seit gestern krankgemeldet. Trotzdem einplanen?"*
- Außerhalb Verfügbarkeits-Regeln: *„Max arbeitet normalerweise nur Mo-Do. Trotzdem für Freitag einplanen?"*
- Außerhalb Arbeitszeit: *„Slot ist um 22:00 — außerhalb der üblichen Arbeitszeit. Bestätigen?"*
### Verfügbarkeits-Regeln
- Pro MA konfigurierbar (`/{tenant}/admin/users/:id/availability/`): Standard-Wochenarbeitszeit, Pause-Zeiten, Ausnahmen
### Drag-&-Drop-Sync zu Calendar (M25)
- Anlage/Änderung triggert Sync zum MA-Calendar
- MA sieht Termin in seinem privaten Kalender
- Wenn MA in seinem Kalender absagt: Webhook → Status `cancelled` mit Notification an PL
### Performance-Anforderungen
- Lazy-Load nur sichtbarer Zeitraum-Slice
- Index auf `tenant_id, assigned_user_id, start_at, end_at`
- Realtime-Updates (WebSocket)
- Aggregat-Cache für Wochen-/Monats-Sicht
### Mobile-Sicht für Monteur (LP-2)
Plantafel nicht mobile. Stattdessen:
- **„Meine Termine heute"** — Liste eigener ScheduleEntries des Tages
- Pro Termin: Project-Titel, Adresse mit Map-/Navigation-Link, Notiz, Status, Tap-Toggle für `confirmed → in_progress → done`
- **„Meine Woche"** — kompakte Wochen-Übersicht
- Push-Notification bei neuer Zuweisung oder Änderung
---
## Block H — Acceptance-Protokoll (Abnahme)
### Acceptance-Form-Templates (Tenant-Admin)
- Konfigurierbare Forms basieren auf Form-Builder M5 mit Subtyp `acceptance_form`
- Verwaltung in `/{tenant}/admin/projects/acceptance-forms/`
### SHK-Default-Acceptance-Form (geseedet)
- Datum/Uhrzeit der Abnahme
- Anwesende Personen (Liste mit Rollen)
- Druckprobe durchgeführt? (Boolean + Wert)
- Funktionsprüfung Heizkreis erfolgt? (Boolean)
- Wärmemengenzähler-Werte (Number)
- Inbetriebnahme-Datum
- Garantie-Beginn (Date)
- Übergebene Dokumente (Multi-Select: Bedienungsanleitung, Garantiekarte, Wartungs-Termin-Übersicht)
- Mängel-Liste (Repeater: Beschreibung + Fotos)
- Foto-Anhänge (Multi-Foto-Upload)
- Bemerkungen Kunde (Text)
- Bemerkungen Monteur (Text)
### Acceptance-Workflow (`/{tenant}/projects/:id/acceptance/new`)
**Mobile-first** (LP-2). Schritte:
**1. Form ausfüllen** — Acceptance-Form-Template wird gerendert. Foto-Upload aus Kamera. Mängel-Liste mit Foto-Anhang. Whisper-EU-Transkription (M18) für lange Bemerkungen.
**2. Mängel-Klassifizierung** — pro Mangel: `kritisch (Abnahme verweigert)` / `kleinere Mängel (mit Vorbehalt)` / `kosmetisch (erfolgt)` → bestimmt `acceptance_kind`.
**3. Kunde unterschreibt** — Touch-Signatur. Kunden-Name eingeben (kann von `Project.contact` abweichen). IP + Timestamp automatisch.
**4. MA unterschreibt** — Touch-Signatur des MA.
**5. Bestätigen** — AcceptanceProtocol gespeichert, PDF generiert (im Files-Tab + Customer-Portal verfügbar).
**6. Auto-Email an Kunden** — Klartext-Email mit PDF-Anhang (Template anpassbar).
**7. Stage-Wechsel-Optionen:**
- `full`: Project wechselt automatisch in „Abgeschlossen" (oder nächste konfigurierte Stage)
- `with_defects`: Project bleibt in „Abnahme", Mängel werden als Tasks angelegt mit Default-Deadline
- `rejected`: Project zurück in „Ausführung", Notification an PL
### Mehrfach-Acceptance pro Projekt
- Möglich bei großen Aufträgen (Teilabnahmen)
- Project hat 0..N AcceptanceProtocols
- Letzte `full`-Acceptance bestimmt Project-Status
### Klartext-Hinweise
- Acceptance ohne Kunden-Unterschrift: Block, *„Bitte Kunden-Unterschrift einholen — sonst keine rechtsgültige Abnahme."*
- Mängel ohne Beschreibung: Block, *„Mindestens ein Mangel angekreuzt aber keine Beschreibung. Bitte Mängel detailliert beschreiben."*
- Acceptance-Form fehlend in Pipeline: Konfigurations-Hinweis für Tenant-Admin
### Rechtliche Hinweise
- AcceptanceProtocol ist **nicht löschbar** (Audit-Compliance) — nur archivierbar
- IP + Timestamp + Signatur-Bilder werden mind. 6 Jahre aufbewahrt
- PDF mit Cryptographic-Hash signiert (Manipulations-Sicherheit Phase 2)
---
## Block I — Integration mit anderen Modulen
### M1 CRM
- `Project.contact_id`, `Project.company_id` → M1
- Custom-Felder mit `applicable_to=project` → M1-Custom-Field-Architektur
- Activity-Stream → auch im verknüpften Contact-/Firma-Stream
### M3 Sales-Pipeline
- Won-Handoff (Mehrfach-Promotion)
- `Project.source_deal_id`
- Sales-Verlauf-Sektion im Project-Detail
### M5 Form Builder
- Acceptance-Forms (Subtyp `acceptance_form`)
- Foto-Checklisten als ProjectForms
- Sales-Aufnahme-Formulare wandern aus Deal mit Won-Handoff
- Form-Action „Projekt anlegen"
### M6 Booking
- Wartungs-Buchung erzeugt automatisch Project in „Wartungseinsatz"-Pipeline + ScheduleEntry
### M9 Email Inbox
- Mails an Kontakt erscheinen im Project-Activity-Stream
- Subject-Pattern (`[P-2026-0042]`) → Auto-Verknüpfung
### M12 Telefonie
- AirCall-Anrufe an Kontakt erscheinen im Project-Stream
- Click-to-Call aus Project-Detail
- *„Notfall-Auftrag aus Anruf"*-Funktion
### M13 Team-Chat
- **Auto-Projekt-Chat** bei Project-Anlage mit allen Members als Mitglieder
- Channel wird beim Project-Abschluss archiviert
- Bidirektionale Navigation
### M17 Automation-Engine
**Trigger:**
- `project.created`, `project.stage_changed`, `project.completed`, `project.cancelled`, `project.stuck.in_stage`
- `project.member_added`, `project.member_removed`
- `project.acceptance_completed` (mit Metadata: `kind`)
- `schedule_entry.created`, `schedule_entry.changed`, `schedule_entry.cancelled`
**Actions:**
- `create-project`, `update-project-stage`, `assign-pl-to-project`, `add-project-member`
- `create-schedule-entry`, `notify-project-members`, `start-acceptance`
### M22 Notifications
- Push an MA bei neuer ScheduleEntry-Zuweisung
- Push an MA bei Stage-Wechsel des eigenen Projekts
- Push an PL bei Mängeln aus Acceptance
- Push an Kunde (über Customer-Portal) bei Project-Stage-Wechsel (konfigurierbar)
### M23 Files
- Project hat eigenen File-Namespace
- Files aus Sales-Phase als verlinkte Sektion (read-only)
- Foto-Direct-Upload aus Mobile
- Acceptance-PDF wird hier gespeichert
### M25 Calendar-Sync
- ScheduleEntries → Google/MS-Kalender der MA
- Tenant-konfigurierbar pro MA (Opt-Out)
### M26 Tasks
- Tasks mit Project verknüpft
- Mängel aus Acceptance werden automatisch als Tasks angelegt mit Default-Deadline
- Default-Tasks aus Project-Templates
### M14 HR-Hub
- Urlaubs-Anträge + Krankmeldungen → Plantafel-Konflikt-Detection
### M15 Customer-Portal
- Kunde sieht Project-Status (konfigurierbare Phasen-Sichtbarkeit)
- Acceptance-PDF im Portal automatisch freigegeben
- Auto-Status-Mail bei Stage-Wechsel
- Foto-Material aus Acceptance für Kunde sichtbar
### M19 KWP-Integration — **komplett v2 (AD-20, Entsch. 16.06.)**
- 🔴 In v1 **nicht vorhanden** (auch kein Feld-Halter; `ProjektExternesFeld` = v2).
- v2: Auto-Sync zu KWP, Stage-Wechsel triggert Rechnungs-Bereitschaft, Adapter-Pattern (LP-11), Sync „KWP gewinnt".
---
## Block J — Permissions-Anwendung
### Object-Level-Permissions
| Permission | Erlaubt |
|---|---|
| `projects.read_own_member` | Projekte sehen, in denen User Mitglied ist |
| `projects.read_own_pl` | Projekte sehen, bei denen User = `assigned_pl_user_id` |
| `projects.read_all` | Alle Projekte sehen |
| `projects.read_active_only` | Nur aktive (für Monteur — keine archivierten) |
| `projects.write` | Anlegen + Bearbeiten |
| `projects.change_stage` | Stage-Wechsel |
| `projects.manage_members` | Members hinzufügen/entfernen |
| `projects.delete` | Hard-Delete |
| `projects.admin` | Pipeline-Verwaltung, Templates, Acceptance-Form-Templates, Bulk-Operations |
### Field-Level-Permissions
| Permission | Erlaubt |
|---|---|
| `projects.read_volume_own` | Volumen *eigener* Projekte |
| `projects.read_volume_all` | Volumen *aller* sichtbaren Projekte |
| `projects.read_aggregates` | Aggregierte KPIs (Auslastung, Forecast, Performance-Charts) |
### Plantafel-Permissions
| Permission | Erlaubt |
|---|---|
| `plantafel.read_own` | Eigene ScheduleEntries |
| `plantafel.read_all` | Plantafel komplett |
| `plantafel.write` | ScheduleEntries anlegen/verschieben (typisch PL/Disposition) |
| `plantafel.bulk_reassign` | Bulk-Reassign (typisch Tenant-Admin) |
### Acceptance-Permissions
| Permission | Erlaubt |
|---|---|
| `acceptance.write` | Acceptance erstellen + ausfüllen + signieren lassen |
| `acceptance.read` | Acceptance-Protokoll lesen |
| `acceptance.admin` | Acceptance-Form-Templates verwalten |
### Bundle-Mapping
| Bundle | Atomare Permissions |
|---|---|
| `projects.none` | (keine) |
| `projects.read_own_member` | `projects.read_own_member` + `projects.read_active_only` + `acceptance.read` für eigene |
| `projects.read_own_pl` | obigen + `projects.read_own_pl` + `projects.read_volume_own` + `projects.write_own` + `acceptance.write` für eigene + `plantafel.write` für eigene MA |
| `projects.read_all` | obigen + `projects.read_all` + `projects.read_volume_all` + `projects.read_aggregates` + `plantafel.read_all` |
| `projects.write` | obigen + `projects.write` + `projects.change_stage` + `projects.manage_members` + `plantafel.write` + `acceptance.write` |
| `projects.admin` | alle obigen + `projects.delete` + `projects.admin` + `plantafel.bulk_reassign` + `acceptance.admin` |
### SHK-Template-Default-Rollen
| Rolle | Project-Permissions |
|---|---|
| GF | `projects.admin` |
| Vertriebsleiter | `projects.read_all` |
| Vertriebler | `projects.read_all` |
| Projektleiter / Bauleiter | `projects.read_all` + `projects.write` + `plantafel.write` |
| Büro / Backoffice | `projects.read_all` + `projects.write` + `plantafel.read_all` |
| Marketing | `projects.read_all` (ohne Volumen + Aggregates) |
| Monteur | `projects.read_own_member` + `acceptance.write` für eigene aktive Projekte (sieht **nur aktive**, **keine** archivierten, **kein** Volumen) |
### UI-Anwendung
- Volumen verborgen ohne Read-Permission
- Plantafel-Sicht: Monteur sieht nur eigene Slots
- Project-Liste/Kanban: server-side gefiltert nach Member-Sichtbarkeit
- Acceptance: Monteur erstellt für eigene; Tenant-Admin sieht alle
### Anwendung in Routes
- `/{tenant}/projects` → mind. `projects.read_*`
- `/{tenant}/projects/:id` → Permission-Check je nach Member/PL-Status
- `/{tenant}/projects/new` → `projects.write`
- `/{tenant}/projects/plantafel` → `plantafel.read_all` (sonst Mobile-Heute-View)
- `/{tenant}/projects/:id/acceptance/new` → `acceptance.write` für dieses Project
- `/{tenant}/admin/projects/pipelines` → `tenant.admin` ODER `projects.admin`
- `/{tenant}/admin/projects/templates` → analog
- `/{tenant}/admin/projects/acceptance-forms` → `acceptance.admin`
### Klartext-Fehler
- Zugriff auf nicht-eigenes Project mit `read_own_member`: 404
- Stage-Wechsel ohne `change_stage`: server-side abgelehnt mit Klartext
- Plantafel-Schreib-Versuch ohne `plantafel.write`: *„Du kannst die Plantafel sehen, aber nicht ändern. Bitte den PL/Disposition kontaktieren."*
- Acceptance ohne `acceptance.write`: Block, *„Du darfst keine Abnahme starten. Bitte einen PL oder Bauleiter."*
---
## Architektur-Vorschriften (Querschnitt)
- **LP-2:** Mobile-Modus für Project-Detail, Acceptance, eigene Schedule-Entries
- **LP-3, AV #3:** SHK-Pipelines + Acceptance-Form-Templates sind Branchen-Template-Seeding
- **LP-7:** PandaDoc bleibt für Sales-Signatur (M3); Acceptance läuft eigenständig (Touch-Signatur)
- **LP-10, AV #1:** Klartext-Diagnostik
- **LP-11:** Adapter für KWP-Integration kapselt KWP-Spezifika
- **AV #5:** Permissions-aware-Default
- **AV #6:** Audit-Trail-Default
---
## Detail-Spec-Status: DRAFT
Modul 4 komplett spec'd. **Vor Bau:** Verifizierung mit Noah, speziell Acceptance-Form-Defaults und Pipeline-Stages.
**Offene Detail-Punkte:**
- Konkrete SHK-Acceptance-Form-Felder finalisieren (Druckprobe-Werte, Übergabe-Dokumente)
- Plantafel-Performance-Strategie bei 50+ MA × Wochen-View
- KWP-Native-Integration nach KWP-Termin neu evaluieren
- Mehrfach-Acceptance-Logik bei Teilabnahmen (UX-Detail)
- Konkrete Auto-Email-Templates für Acceptance-Bestätigung an Kunden