Files
HiveGrid-Wireframes/hivegrid-cloud/docs/boilerplate-mapping/M04-auftragspipeline.md
T

17 KiB
Raw Blame History

Boilerplate-Abgleich — M04 Auftrags- / Projektpipeline

Modul-ID M04
Name Auftrags- / Projektpipeline (Geerkens-Kern)
Milestones M065 (Pipeline-Konfig) · M066 (Auftrag-CRUD + KWP-Archiv) · M067 (Plantafel) · M068 (Mitglieder-Mgmt) · M069 (Abnahme-Workflow) · M070 (Material-Listen + Lager)
Block Pflichtenheft Block 3, Abschnitt 4.1–4.14
Reuse-Level low (nur Fundament + Querschnitts-Bausteine + UI-Primitive nutzbar; KEINE Domänen-Modelle, kein Pipeline-/Kanban-/Plantafel-/Abnahme-Code vorhanden)
Boilerplate-Wurzel /Users/raffaelsheikh/Documents/GitHub/boilerplate
Verifiziert am 2026-06-04 (Greps/Reads direkt im Schema + package.json, nicht nur Inventur)

Kernbefund (Anti-Erfindung)

Die Boilerplate enthält kein einziges Domänen-Modell für dieses Modul. Grep über alle 27 prisma/schema/*.prisma (190 Modelle) liefert für Project|Order|Auftrag|Pipeline|Stage|Schedule|Acceptance|Plantafel|Deal|Verkaufsfall|Contact|Kontakt|Company|Firma → NONE FOUND. prisma/schema/app.prisma ist ein leerer Platzhalter (// custom database models). Alle M04-Entitäten (ProjectPipeline, ProjectPipelineStage, Project, ProjectMember, ScheduleEntry, AcceptanceProtocol, ProjectTemplate, ProjectForm) sind komplett neu zu modellieren.

Was vorhanden ist: ein generischer No-Code-EntityBuilder (mit board/calendar-View-Layout-Flag), die volle App-Shell + shadcn/Radix-Komponenten, DnD-/PDF-/Push-/Realtime-Libs, sowie das DB-Layer-Fundament (Outbox, Audit-Hash-Kette, Notification-Delivery, RBAC-Schema). Die HiveGrid-Querschnittsdienste (logActivity M045, notify M011, withTenantScope/withPermission M004) existieren noch nicht als Code — nur ihre DB-Bausteine.


Übernehmbar aus Boilerplate

Boilerplate-Pfad Was Wie nutzbar
prisma/schema/app.prisma Leerer Platzhalter für HiveGrid-eigene Modelle als-vorlage — hier kommen ALLE M04-Modelle rein, ohne Boilerplate-Domänen zu berühren
packages/db/src/client.server.ts getDbClient / getWriteDbClient / getReadDbClient / getExtendedDbClient 1:1 — Read-Replica wichtig für Plantafel/Kanban (read-heavy)
packages/db/src/transactions.server.ts runDbTransaction / runDbTransactionBatch 1:1 — Project-Anlage + Channel + ScheduleEntries atomar
packages/db/src/outbox.ts publishOutboxEvent(tx, …), Event-Pattern <domain>.<entity>.<verb> 1:1 — alle Side-Effects (KWP-Sync, Notifications, Auto-Chat, Calendar-Push, Mängel→Tasks) transaktional
packages/db/src/audit-hash.ts Tamper-evidente Hash-Kette (computeAuditHash, verifyAuditChain) 1:1 — Pflicht für AcceptanceProtocol (rechtssichere 6-Jahre-Aufbewahrung)
packages/db/src/rows.server.ts (getNextRowMutationNumber, folio-Aggregat) Fortlaufende Nummern-Vergabe pro Tenant/Entity via _max-Aggregat als-vorlage — Muster für project_number „P-2026-0042" (eigener Sequenz-Generator, da Project kein Row ist)
packages/db/src/dsgvo/user-fk-map.ts Zentrale FK-auf-User-Karte (CI-Test erzwingt Vollständigkeit) anpassen — Pflicht-Eintrag für jedes neue Modell mit user_id (ProjectMember, ScheduleEntry.assigned_user_id, AcceptanceProtocol.staff_signature_user_id …), sonst bricht CI
prisma/schema/permissions.prisma (Role/Permission/RolePermission/UserRole/Group/GroupUser) RBAC-Schema inkl. Gruppen 1:1 — Object/Field/Plantafel/Acceptance-Permissions hängen hier dran; Group/GroupUser deckt „Team Süd"-Gruppen-Add (4.10.2 / M068) ab
prisma/schema/core.prisma (AuditEvent, FileObject/FileUploadProgress/FileChunk) Audit-Trail-Modell + Storage-Metadaten 1:1 — Audit auto via M001-Middleware; FileObject für Baustellen-Fotos + Acceptance-PDF (M23/M052-M055)
prisma/schema/notifications.prisma (NotificationDelivery, UserNotificationPreference, DeviceToken) In-App/Email/Push-Delivery + Geräte-Token (APNs/FCM/WebPush) 1:1 — Push bei ScheduleEntry-Zuweisung / Stage-Wechsel / Mängeln (4.6.13.5 / 4.12.12)
apps/worker/src/jobs/push-notification.ts Fertiger Push-Job (firebase-admin FCM + node-apn APNs + WebPush, pro DeviceToken) 1:1 — Mobile-Push für Monteur
prisma/schema/appsEngine.prisma (App, DataConnection, AppSyncRun, AppSyncRunLog, AppSyncItem) Integrations-/Sync-Engine mit Rollback-fähigen Sync-Runs + Source→Destination-Mapping anpassen — Träger für KWP-Plantafel-Bidi-Sync (4.6.14, M094) + KWP-Dokumenten-Archiv (M066/M095); AppSyncItem modelliert die cross-System-ID-Zuordnung (4.6.14.2)
packages/foundation/src/adapters.ts (defineAdapter/getAdapter, Status-Lifecycle) Adapter-Registry (von AGENTS.md als KWP-Adapter-Pfad genannt, LP-11) 1:1 — KWP-Adapter-Kapselung (4.12.11)
packages/queue/* (@toolctrl/queue: factory, producers, priority, groups, names) BullMQ-Wrapper inkl. Idempotenz-Hilfen 1:1 — Plantafel-Pull-Fallback-Cron (4.6.14.3), PDF-Gen, Auto-Email, Auto-Archive-Jobs
packages/shared-store/* (@toolctrl/shared-store) Redis-KV: Cache, Rate-Limit, Idempotenz 1:1 — Aggregat-Cache für Wochen-/Monats-Plantafel (Perf-Anforderung 4.6), Sync-Idempotenz
@hocuspocus/server + @hocuspocus/provider (packages/hocuspocus) Realtime-Server (WebSocket/Y.js) als-vorlage — Realtime-Plantafel-Updates (Spec G „Realtime-Updates (WebSocket)")
packages/exports/src/audit-pdf.ts + ./pdf (@react-pdf/renderer ^4.3.2) PDF-Streaming-Renderer + S3-Multipart-Sink anpassen — Acceptance-Protokoll-PDF (4.7.4.5); eigenes PDF-Template nötig, aber Renderer + S3-Sink 1:1
@dnd-kit/core + @dnd-kit/sortable + react-dnd (Root-deps) Drag-&-Drop-Bibliotheken 1:1 — Kanban-Stage-Move (4.5.3) + Plantafel-Block-Move/Resize (4.6.4)
apps/web/app/components/ui/calendar.tsx + date-fns / date-fns-tz Kalender-Primitive + Datums-Utils als-vorlage — Plantafel-Raster (Tag/Woche/Monat) muss eigenes Grid bauen (kein react-big-calendar/fullcalendar vorhanden)
apps/web/app/components/layouts/sidebars/shadcn/* + apps/web/app/application/sidebar/AppSidebar.tsx + SidebarItem.ts Datengetriebene Sidebar mit Permission-/Feature-Gating 1:1 / anpassen — Sidebar-Eintrag „Aufträge (Projekte)" (Gruppe ARBEITEN, INTEGRATION-CONTRACTS §1)
apps/web/app/components/ui/tables/* (TableNew, TablePagination, ColumnSelector) Tabellen-Komponenten 1:1 — Listen-View /projects/list (4.5.1)
apps/web/app/components/ui/modals/* (ConfirmDialog, ActionResultModal, ErrorModal) Bestätigungs-/Ergebnis-Dialoge 1:1 — Klartext-Confirms (Konflikt „Trotzdem zuweisen?", Storno-Grund-Pflicht, Hard-Delete-Block)
apps/web/app/components/ui/{emptyState,loaders} Empty-/Loading-States 1:1 — DoD-Pflicht (Empty/Loading-State mit Klartext)
apps/web/app/components/ui/forms/* + .../editors (Markdown/Rich) Formulare + Editoren 1:1 — Stammdaten-Edit, Markdown-Description
apps/web/app/components/entities/{rows,views,properties}/* + EntityView.layout (board/calendar) No-Code-Board/Calendar-View-Engine als-vorlage — Kanban-/Board-Render-Muster studieren; M04 braucht aber dedizierte relationale Modelle, NICHT generische Rows
prisma/schema/formWidget.prisma (Form, FormSubmission) + packages/form-widget + Form-Builder UI (apps/web/app/modules/formWidget/builder/*) Form-Builder + Submission-Inbox + Field-Mapping/Routing anpassen — Acceptance-Form-Templates (Subtyp acceptance_form, 4.7.1) + „Projekt aus Formular" (4.4.4) bauen auf M5/M121 auf; Field-Mapping-Helfer (applyFieldMapping) wiederverwendbar
prisma/schema/portals.prisma + apps/web/app/modules/portals/* Customer-Portal-System anpassen — Kunden-Sicht auf Projekt-Status + Acceptance-PDF (4.12.9, M15/M141-M146)
packages/view-models/* (VMState, ActionCallbacks, I18nLabel, assertI18nLabel) View-Model-Vertrag + i18n-Key-Zwang 1:1 — M013-Layer-Pflicht (Loader baut VM, UI nur VM+Actions)
packages/ui-app/* (createSidebarRegistry/createShellRegistries, generateA11yTest) Shell-Registry-Factories + a11y-Test-Template 1:1 — Navigations-Wiring + a11y-Gate
packages/ui-mock/* + packages/i18n/* (de/en, @toolctrl/i18n) Hot-Swap-Mock-Generator + i18n-Setup 1:1 — Hot-Swap-Drill (M017) + i18n-Keys (M003), de Default
prisma/schema/featureFlags.prisma (FeatureFlag, FeatureFlagFilter, FeatureFlagAudit) Feature-Flag-Engine 1:1 — Modul ohne Deploy abschaltbar (DoD-Pflicht, M006)

Vorhandene Daten-Modelle (konkret, mit Pfad)

Direkt M04-relevant (Querschnitt + Träger):

  • prisma/schema/app.prisma — leerer Platzhalter, Ziel für alle M04-Modelle.
  • prisma/schema/accounts.prisma — User, Tenant, TenantUser, Group-Bezug (Mitarbeiter, Mandanten-Scope, Mitglieder).
  • prisma/schema/permissions.prisma — Role, Permission, RolePermission, UserRole, Group, GroupUser (Berechtigungen 4.11 + Gruppen-Add 4.10.2).
  • prisma/schema/core.prisma — AuditEvent (Hash-Kette → Acceptance-Compliance), FileObject/FileUploadProgress/FileChunk (Fotos + PDF), IdempotencyKey.
  • prisma/schema/notifications.prisma — NotificationDelivery, UserNotificationPreference, DeviceToken (Push 4.6.13.5 / 4.12.12).
  • prisma/schema/appsEngine.prisma — App, DataConnection, AppSyncRun, AppSyncRunLog, AppSyncItem (KWP-Bidi-Sync-Träger 4.6.14, Dokumenten-Archiv M066/M095).
  • prisma/schema/outbox.prisma — OutboxEvent (transaktionale Side-Effects).
  • prisma/schema/featureFlags.prisma — Feature-Flag-Gating.
  • prisma/schema/formWidget.prisma — Form, FormSubmission (Acceptance-Forms / Projekt-aus-Form, via M5/M121).

Als Pattern/Vorlage (NICHT direkt M04-Daten):

  • prisma/schema/entityBuilder.prisma — Entity, Property, EntityView (Layout-Flag table|board|calendar|list|gallery, Zeile 95), EntityViewFilter/Sort, Row, RowValue, RowTag, RowTask, RowComment, RowPermission, RowMedia. Generische No-Code-Engine — als Render-/Filter-/Board-Muster studierbar, ersetzt aber NICHT die dedizierten M04-Relationen.

NICHT vorhanden (Beweis: Schema-Grep = NONE): Project, ProjectPipeline, ProjectPipelineStage, ProjectMember, ScheduleEntry, AcceptanceProtocol, ProjectTemplate, ProjectForm, Deal/Verkaufsfall, Contact/Kontakt, Company/Firma, Task/Aufgabe.


Lücken / komplett neu zu bauen

Daten-Layer (alles neu, in app.prisma):

  • Alle 8 Kern-Entitäten der Spec Block A: ProjectPipeline, ProjectPipelineStage (inkl. stage_kind-Enum, requires_acceptance_protocol, auto_archive_after_days, color), Project (inkl. project_number-Sequenz, source_deal_id nullable, Baustellen-Adresse, cancellation_reason), ProjectMember (M:N + frei-textuelle Rolle), ScheduleEntry (Status-Enum, Index (tenant_id, assigned_user_id, start_at, end_at)), AcceptanceProtocol (nicht-löschbar, Signatur-Bilder, IP+Timestamp, defects[] JSON, acceptance_kind-Enum), ProjectTemplate, ProjectForm.
  • Verfügbarkeits-Regeln pro MA (4.6.10 — /admin/users/:id/availability), neues Modell.
  • Stage-Historie-Modell (4.8.1).
  • Material-Listen-Modell (M070 — Position/Menge/Status; Phase 1 read-only aus KWP via M095).

Domänen-Logik (neu, in app/domain/**):

  • Pipeline-Engine wird laut M065 aus M059 (Sales-Pipeline) wiederverwendet — beide sind HiveGrid-Milestones, NICHT Boilerplate. Reine Boilerplate-Wiederverwendung gibt es hier nicht.
  • Stage-Wechsel-Validation (Acceptance-Pflicht-Block, Storno-Grund-Pflicht, 24h-Reverse-Window).
  • Sequenz-Generator „P-YYYY-NNNN" (Muster aus rows.server.ts adaptierbar, aber eigene Implementierung).
  • Konflikt-Detektor Plantafel (Doppel-Belegung, Urlaub/Krankheit aus M14, Verfügbarkeit, Arbeitszeit — 4.6.9).
  • Acceptance-Workflow-State-Machine (Mängel-Klassifizierung → acceptance_kind → Folge-Aktionen 4.7.5; Mängel→Tasks-Auto-Erzeugung 4.7.5.2/4.12.15).
  • Sales-Verlauf-View-Model-Composition (read-only Snapshot aus Deal, Field-Level-Volumen-Gate — 4.8.4).
  • Auto-Projekt-Chat-Lifecycle (4.10.3/4.12.7, hängt an M104).
  • Auto-Archive-Jobs (90/30 Tage) + Stuck-Detection.

UI (neu, in packages/ui-hivegrid/** via Subframe-Adapter):

  • Kanban-Board mit Project-Karten (DnD via @dnd-kit vorhanden; Karten-/Board-Layout neu).
  • Plantafel-Grid (Y=Mitarbeiter, X=Zeit, Resize+Move, Konflikt-Indikatoren, Zoom) — größte UI-Lücke; KEIN react-big-calendar/fullcalendar in der Boilerplate, nur calendar.tsx-Primitive + date-fns. Eigenes Grid (ggf. @xyflow/react oder Custom).
  • Project-Detail mit Tab-/Sektions-Navigation, visueller Pipeline-Komponente, Activity-Stream.
  • Mobile-first Acceptance-Workflow (mehrschrittig, Foto-Kamera-Upload, Touch-Signatur).
  • Mobile „Meine Termine heute" / „Meine Woche" (4.6.13).

Querschnitt-Dienste (noch nicht als Code in BP — HiveGrid-Milestones):

  • logActivity (M045) — Grep: keine Implementierung in BP.
  • notify({…}) (M011) — kein standalone @toolctrl/notifications-Paket; nur DB-Modelle + Worker-Job. Service-Fassade neu.
  • withTenantScope() / withPermission() (M004) — Permission-Filter-Fassade neu (RBAC-Schema vorhanden, Filter-Logik nicht).
  • i18n-Keys-Namespace projects.* neu (M003-Build-Lint blockt sonst).

Externe Lib, die FEHLT und ergänzt werden muss:

  • signature_pad — NICHT in der Boilerplate (Grep über alle package.json = NONE). Die Behauptung im M069-PLAN.md „signature_pad ist in Boilerplate-Deps" ist falsch und muss korrigiert werden (Dependency neu hinzufügen für Touch-Signatur 4.7.4.3/4.7.4.4).
  • firebase-admin / node-apn — der Push-Worker-Job referenziert sie; Verifizieren, dass die SDKs tatsächlich installiert sind (Job-Header nennt sie, aber als optionale Adapter).

Integrationen, die auf andere HiveGrid-Milestones warten (keine BP-Lücke i.e.S.):

  • KWP-Bidi-Sync (M094/M095, LP-11) · Calendar-Sync M25/M119 · Email-Versand M092 · Whisper-Transkription M18 · HR-Hub-Konflikte M14/M129/M135.

Empfohlenes Vorgehen

Phase 0 — Fundament aus BP übernehmen (vor jedem Modul-Code):

  1. M04-Modelle in prisma/schema/app.prisma modellieren (NICHT EntityBuilder-Rows nutzen — dedizierte Relationen wegen Deal-/Contact-/User-FKs, Sequenznummer, Field-Level-Volumen, rechtlicher Aufbewahrung). Forward-Only-Migration mit Inverse-SQL-Kommentar.
  2. Für jedes neue Modell mit user_id SOFORT Eintrag in packages/db/src/dsgvo/user-fk-map.ts (sonst CI-Block). AcceptanceProtocol als retain-tombstone (6-Jahre-Pflicht), nicht hard-delete.
  3. DB-Zugriff über getDbClient/getReadDbClient + runDbTransaction; alle Side-Effects über publishOutboxEvent.

Phase 1 — Pipeline-Konfig (M065): 4. Pipeline-/Stage-Modelle + SHK-Default-Seeding (3 Pipelines, LP-3-Branchen-Template). RBAC-Permissions (projects.*, plantafel.*, acceptance.*) in permissions.prisma-Seed registrieren. 5. ProjectTemplate-Modell + Admin-UI (shadcn-Forms aus BP). 6. Sidebar-Eintrag „Aufträge (Projekte)" (Gruppe ARBEITEN) + Settings-Eintrag „Pipelines" via sidebar.config.ts / AppSidebar.tsx-Muster.

Phase 2 — Auftrag-CRUD + Detail (M066): 7. Project-CRUD, Sequenz-Generator (Muster rows.server.ts), Kanban + Liste (DnD via @dnd-kit, Tabellen aus BP). Stage-Wechsel-Validation. 8. Project-Detail-VM (View-Model-Composition inkl. read-only Sales-Verlauf mit Volumen-Gate). FileObject-Anbindung für Fotos. 9. KWP-Dokumenten-Archiv über appsEngine + defineAdapter (M095).

Phase 3 — Mitglieder (M068, blockt Plantafel): 10. ProjectMember + Gruppen-Add über Group/GroupUser (BP) + Auto-Chat-Channel (M104).

Phase 4 — Plantafel (M067, größter Neubau): 11. Eigenes Calendar-Grid (kein BP-Fertigbaustein) mit DnD-Resize/Move. Konflikt-Detektor. Read-Replica + shared-store-Aggregat-Cache für Perf. Hocuspocus für Realtime. Push via vorhandenem Worker-Job + DeviceToken.

Phase 5 — Abnahme (M069): 12. Zuerst signature_pad als Dependency ergänzen (fehlt!). Acceptance-Form auf Form-Builder (M5/M121). Mobile-Workflow. PDF via @react-pdf/renderer + packages/exports-S3-Sink (eigenes Template). Audit-Hash-Kette für Manipulationssicherheit. Mängel→Tasks (M073). Auto-Email (M092).

Phase 6 — Material/Lager (M070): 13. Material-Listen-Modell; Phase 1 read-only KWP-Daten via M095/appsEngine; Lagerist-Permission-Cluster (M023.1).

Querschnitt durchgängig: logActivity (M045), notify (M011), withTenantScope/withPermission (M004), i18n projects.* (M003), Feature-Flag (M006), VM-Layer (M013), Subframe-Adapter (M015) — alle als HiveGrid-Querschnitt nutzen, NICHT im Modul nachbauen (PR-Block sonst).