707 lines
30 KiB
Markdown
707 lines
30 KiB
Markdown
---
|
||
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
|