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,706 @@
---
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