Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/_bmad-output/specs/M04-auftragspipeline.md
T

30 KiB
Raw Blame History

module, title, phase, status, last_updated, session_source, related_lps, spec_style
module title phase status last_updated session_source related_lps spec_style
4 Auftrags- / Projektpipeline 1 detail-spec-draft 2026-05-08 brainstorming-session-2026-05-07-2206.md
LP-2
LP-3
LP-4
LP-7
LP-9
LP-10
LP-11
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