Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,148 @@
# 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).