--- 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