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,115 @@
# Boilerplate-Abgleich: M23 — Files / Dokumentenablage
| Feld | Wert |
| --- | --- |
| **Modul-ID** | M23 |
| **Name** | Files / Dokumentenablage |
| **Milestones** | M052 (Datei-Upload), M053 (Speicher-Backend Scaleway), M054 (Permissions/Sharing/Versionierung), M055 (Suche/Tagging/Archivierung) |
| **Block** | Block 2 (CRM-Kern), Pflichtenheft Modul 23 |
| **Reuse-Level** | **medium** |
| **Spec** | `/Users/raffaelsheikh/Documents/GitHub/HiveGrid-Cloud/_bmad-output/specs/M23-files.md` |
## Kurzfazit
Die Boilerplate hat ein **reifes Storage-Infrastruktur-Fundament** (`packages/storage`): S3-Adapter (Scaleway-tauglich), Signed-URLs mit SigV4, Tenant-Pfad-Isolation, MIME-Magic-Bytes-Validierung, ClamAV-Anti-Virus-Pipeline (web → queue → worker → quarantine), MIME-Allow-List und Pre-Upload-Scan. Diese decken **Block E (teilweise), J (Storage-Tenant-Check), K (Storage-Architektur) und M052/M053 großflächig** ab.
**Aber:** Das HiveGrid-Fachdomänen-Modell (`File`, `FileVersion`, `FileEntityLink`, das fachliche `FileUploadProgress`/`FileChunk` mit Tenant/Resume/Checksum) fehlt komplett. Die Boilerplate-Modelle `FileObject`/`FileUploadProgress`/`FileChunk` (`core.prisma`) sind **nicht tenant-scoped, nicht versioniert, kein Entity-Link, kein Resume-State** — nur generische Storage-Metadaten. Der komplette **Files-Browser (UI), Versionierung, Entity-Verknüpfung, Preview-/Thumbnail-Generierung und Volltextsuche/OCR** ist neu zu bauen.
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
| --- | --- | --- |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/storage/src/index.ts` | `createS3StorageAdapter` / `createLocalStorageAdapter`, `putObject`/`deleteObject`, `StorageAdapterError` (mit Secret-Redaction), `UploadBody`-Typen | **1:1** — S3-PUT/DELETE auf Scaleway. Bucket-pro-Region passt zur Spec K. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/storage/src/signed/index.ts` | `createS3SignedUrlAdapter`, `createSignedUploadUrl`/`createSignedDownloadUrl`, Expiry-Clamping (`DEFAULT_MAX_SIGNED_URL_EXPIRY_SECONDS=3600`), `checksumSha256`/`contentLength`-Header | **1:1** — kurzlebige Signed-URLs für Download/Preview (Spec K: keine Public-URLs). |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/storage/src/access/index.ts` | `authorizeStorageObjectAccess` (Tenant-Prefix `tenants/{tenantId}/` Mismatch-Check, blocked/quarantined-Gate), `authorizeStorageUploadConstraints` (MIME-Allow + maxBytes) | **1:1** — Spec K „App-Code prüft storage_key ↔ tenant_id" + Spec E Max-Size + Mime-Block. Pfad-Konvention `tenants/{tenantId}/...` deckt sich exakt mit Spec A/F. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/storage/src/scan/magic-bytes-adapter.ts` | `createMagicBytesScanAdapter` — synchroner Pre-Upload-Scan: Magic-Bytes vs. declared MIME, Allow-List, Filename-Path-Traversal-/Control-Char-Schutz, SVG-Sonderfall | **anpassen** — Allow-List-Kontexte erweitern (siehe unten). Deckt Spec E „Mime-Typ blockiert" + M052 Format-Whitelist. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/storage/src/scan/allow-list.ts` | `DEFAULT_ALLOW_LIST` + `resolveAllowList(env)` (env-overridable `STORAGE_SCAN_ALLOWLIST_<CONTEXT>`) | **anpassen** — Kontexte sind aktuell `avatar/mediaLibrary/emailAttachment/formUpload/kbAsset`; ein `files`-Kontext mit der breiteren HiveGrid-Liste (Video/Audio/HEIC/ODF) fehlt. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/storage/src/scan/clamav-scanner.ts` | `createClamAVStorageScanner` (clamd TCP, `loadObject`-Seam, Reachability-Check, `ClamAVUnreachableError`) | **1:1** — M052 Anti-Virus (ClamAV-EU/self-hosted). |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/storage/src/scan/s3-quarantine.ts` | `createS3StorageQuarantineAdapter` — infizierte Objekte nach `quarantine/`-Prefix kopieren + Original löschen | **1:1** — Sicherheits-Quarantäne für infizierte Uploads. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/storage/src/scan/index.ts` | `createStorageScanService` (Scanner+Quarantine-Orchestrator), `ScanVerdict`, `StorageScanResult` (clean/infected/error, mit Klartext-Diagnostik) | **1:1** — Worker-Orchestrierung des Post-Upload-Scans. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/web/app/utils/integrations/storageService.ts` | `storeFile` (Pre-Scan → PUT → `enqueuePostScan`), `putBufferAsFile`, `deleteFile`, SSRF-sichere `fetchUploadContent`, Provider-Fallback (s3↔local), `StorageScanRejectedError` | **als-vorlage** — fertiges Web-Wiring von Scan+Upload+Fallback; HiveGrid braucht tenant-scoped Variante (Bucket/Key aus `tenant_id`) und Chunked-Upload statt Single-Shot. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/web/app/utils/integrations/storageAudit.server.ts` | `auditRejectedUpload(request, context)` — onReject-Callback schreibt `upload.rejected.scan` Audit-Event (PII-frei) | **als-vorlage** — Audit-Pattern für abgelehnte Uploads (Spec AV #6, M002 Klartext). |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/worker/src/scanService.ts` | `createWorkerScanService(env)` — verdrahtet ClamAV-Scanner + S3-Quarantine aus Env, undefined-safe Boot | **1:1** — Worker-Bootstrap des Scan-Service. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/worker/src/handlers.ts` (queue `fileScan`, ab Zeile 753) | `toolctrl.file-scan`-Handler: ruft `scanService.scanObject`, liefert `scan.clean`/`scan.infected`, Klartext-Diagnostik bei `error` | **als-vorlage** — Vorlage für HiveGrid Scan-Job; muss um Status-Rückschreibung in `File.preview_status`/Scan-Status erweitert werden. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/api/src/storage.ts` | Vollständige **SigV4-Signierung** für S3-Signed-URLs inkl. Adapter-/Signing-Key-Cache (Secret nie roh gecached) | **1:1** — die konkrete Signer-Implementierung für `createS3SignedUrlAdapter`. Direkt für Scaleway nutzbar. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/web/app/utils/integrations/fileScanQueue.server.ts` | `enqueueFileScan` (BullMQ-Enqueue für Post-Upload-Scan, no-op ohne `SCAN_QUEUE_ENABLED`) | **1:1** — Enqueue-Helper für den Scan-Job. |
| `prisma/schema/core.prisma` → `FileObject` (Zeile 213) | Storage-Metadaten (`provider/bucket/key` unique, `contentType`, `byteSize`, `checksumSha256`, `publicUrl`, `uploadedAt`, `lastSignedUpload/DownloadAt`, `metadata`) | **als-vorlage** — Feld-Set für das HiveGrid-`File`-Modell; aber **nicht tenant-scoped, keine Versionen, keine Soft-Delete/Tags/Preview** — als Spaltenvorlage, nicht 1:1. |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/web/app/components/ui/uploaders/` (`UploadDocument`, `PreviewUploadersDocument`, `MediaItem`), `input/InputMedia.tsx`, `input/InputImage.tsx` | Drag-and-Drop-Dropzone + Base64-Multi-File-Upload + Media-Preview-Modal (i18n-fähig) | **als-vorlage** — UI-Bausteine für Drag-and-Drop. **Achtung:** Base64-Single-Shot, kein Chunked/Resume; in HiveGrid via `packages/ui-hivegrid`-Adapter + Subframe neu zu bauen (Layer-Disziplin AGENTS A). |
| `packages/exports` + Worker `dsgvo-export.ts` | `createS3MultipartUploadSink` (8 MB Multipart, Concurrency 4, Abort-on-fail), DSGVO-Export-Bundle als ZIP/JSON → S3 + Signed-URL + AuditEvent | **als-vorlage** — Spec D „DSGVO-Export (Datei + Metadaten als ZIP)" + Spec C „Download als ZIP" (Bulk). Multipart-Sink hilft bei Chunk-Concat (Spec E Schritt 5). |
| `prisma/schema/core.prisma` → `AuditEvent` (Zeile 55) + Audit-Worker (`audit-event-persist.ts`, `audit-retention.ts`) | Compliance-Audit-Trail-Modell + Persist-/Retention-Jobs | **1:1 (Querschnitt)** — Spec AV #6 / Block I Audit-Default. |
---
## Vorhandene Daten-Modelle (Boilerplate)
Quelle: `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/core.prisma`
- **`FileObject`** (Zeile 213) — generische Storage-Objekt-Metadaten. **Nicht** tenant-scoped, **keine** Soft-Delete/Versionen/Tags/Preview/Entity-Links. → Feldvorlage für HiveGrid-`File`, **kein** Ersatz.
- **`FileUploadProgress`** (Zeile 195) — `id, fileName, progressServer, progressStorage, url, error, chunks[]`. **Deutlich dünner** als Spec A: **kein** `tenant_id`, `created_by_user_id`, `total_size_bytes`, `total_chunks`, `received_chunks`, `expires_at`, `status`-Enum, `target_file_id`, `target_version_intent`. → Konzept gleich, Felder fast komplett neu.
- **`FileChunk`** (Zeile 205) — `id (Int autoincrement), fileUploadId, index, data Bytes`. Speichert Chunk-Bytes **in der DB** (`data Bytes`), nicht im temporären Storage-Bucket wie Spec A (`storage_key`). **Kein** `tenant_id`, `checksum_sha256`, `size_bytes`, `received_at`, **kein** `(upload_id, chunk_index)`-Unique. → Architektur-Abweichung (DB-Bytes vs. Storage-Temp); neu zu modellieren.
- **`AuditEvent`** (Zeile 55) — Compliance-Audit-Trail (Querschnitt, 1:1 nutzbar).
**Nicht vorhanden** (komplett neu): `File` (fachlich, tenant-scoped, soft-delete, RLS), `FileVersion`, `FileEntityLink`.
**Kein passendes Tag/Activity-Modell auf Datei-Ebene:** Tags existieren nur row-scoped im Entity-Builder (`EntityTag`/`RowTag` in `entityBuilder.prisma`) — nicht das HiveGrid-Tag-System (M044) und nicht der zentrale Activity-Stream (M045). Beides ist HiveGrid-Eigenbau, auf den M23 nur referenziert.
---
## Lücken / komplett neu zu bauen
### Daten-Layer
- **`File`-Modell** (tenant-scoped, soft-delete, RLS) mit `display_name`, `mime_type`, `size_bytes`, `storage_key`, `current_version`, `checksum_sha256`, `preview_status`-Enum, `preview_storage_key`, `assigned_to_user_id`, `tags[]`, `notes`, `archived_at`, `source`-Enum, `created_by_portal_user_id` (Block H). Inkl. Indizes (Default-Sort, Owner, Checksum-Dedupe, **Trigram-Index `display_name`**).
- **`FileVersion`** (append-only, `(file_id, version_number)` unique).
- **`FileEntityLink`** (M:N, `(file_id, entity_type, entity_id)` unique, Index `(tenant_id, entity_type, entity_id)`, `link_role`).
- **Fachliches `FileUploadProgress`/`FileChunk`** mit Tenant, Resume-State, Checksum, Storage-Temp-Pfad (Boilerplate-Modelle reichen nicht).
### Domänen-/Worker-Logik
- **Chunked Upload mit Resume** (5 MB Chunks, max 3 parallel, Init→Stream→Concat→Finalize, Resume nach Reconnect) — Boilerplate kann nur Single-Shot `storeFile`. Multipart-Sink aus `packages/exports` als Concat-Baustein nutzbar.
- **Versionierung** (gleicher Display-Name → V2/V3, Rollback legt neue Version an, Storage-Pfad `…/v{n}/original`) — nicht vorhanden.
- **Preview-Generation** (PDF direkt, **HEIC→JPEG**, **Office→PDF via LibreOffice-Headless**, Video-Thumbnail, Thumbnail für Grid) — **kein** Worker-Job, **keine** Image/PDF/Office-Libs in der Boilerplate (`sharp` nur in pnpm `onlyBuiltDependencies`, **nicht** als Dependency; **kein** `browser-image-compression` trotz M052-Plan-Hinweis; kein libheif/imagemagick/libreoffice/pdf-lib). Komplett neu inkl. Library-Auswahl.
- **Duplikat-Erkennung per Checksum** (Spec E: „Datei existiert bereits…") — `checksumSha256`-Feld + Index vorhanden, Match-Logik + UI-Dialog neu.
- **Transitive Sichtbarkeit / `files.read_own`** (Owner ∨ Assignee ∨ Entity-Link mit Lese-Recht; Materialized-View/Cache-Erwägung) — Permission-Logik komplett neu; `withTenantScope()`/`withPermission()` (M004) als Wrapper.
- **Bulk-Actions** (Tag/Assign/Link/Archive/ZIP-Download/Hard-Delete) — neu.
- **Cleanup-Jobs** (expired Chunks täglich, Hard-Delete-Cascade Storage, Orphan-Reconciliation wöchentlich) — neu (Cron-Pattern wie `audit-retention.ts`/`dsgvo-grace-cron.ts` als Vorlage).
- **OCR + Volltextsuche** (M055; Tesseract Phase 1) — neu; Such-Index-Registrierung via M056/`indexed-entities`.
### Permissions
- **Bundle `files.none/read_own/read_all/write/delete/admin`** (Spec J Variante 2) — neu; HR-Sonderfall (`user`-Entity folgt HR-Hub M14).
### UI (komplett neu in `packages/ui-hivegrid` + Subframe via Adapter)
- Files-Browser (Tabelle/Grid umschaltbar, Filter, Bulk, Cursor-Pagination, Spalten-Config, Thumbnail-Lazy-Load).
- File-Detail (Preview-Viewer PDF/Bild-Zoom/Office/Video/Audio, Inline-Edit, Verknüpfungs-Verwaltung mit Auto-Complete, Versions-Sektion).
- Upload-View (Drag-and-Drop, Multi-File-Queue, Chunked-Progress mit Klartext + ETA, Resume) — Boilerplate-Dropzone nur als Vorlage.
- Embedded Files-Browser (vorgefiltert) in Detail-Views von Kontakt/Firma/Deal/Projekt/Lead/Auftrag (Spec B / Pflichtenheft 23.7.4).
- Versionsverlauf-Sub-View.
### Querschnitt-Wiring (HiveGrid-Eigenbau, M23 referenziert nur)
- Activity-Stream-Integration (`logActivity`, Activity-Typen `file_uploaded`/`file_version_added`/`file_link_*`/`file_archived`/`file_renamed`/`file_deleted`) — M045.
- Tags-Wiederverwendung — M044.
- Notifications via `notify()` — M011.
- Feature-Flag-Schaltbarkeit — M006.
- Sidebar-Eintrag „Dateien" — `packages/ui-hivegrid/src/app-shell/sidebar.config.ts` (INTEGRATION-CONTRACTS §1, Gruppe gem. Sidebar-Baum, Zeile 25).
- Mobile Offline-Foto-Upload (IndexedDB-Queue, LP-8) — Modul 36 / M170, nicht in Boilerplate.
---
## Empfohlenes Vorgehen
**Reihenfolge — zuerst BP-Infrastruktur verdrahten, dann Fachdomäne, dann UI:**
1. **M053 (Storage-Backend) zuerst-nah verdrahten:** `@toolctrl/storage` als Workspace-Dep einziehen. S3-Adapter + Signed-URL-Adapter (`apps/api/src/storage.ts`-SigV4 als Signer) auf Scaleway konfigurieren. `authorizeStorageObjectAccess` als verbindlichen Tenant-Pfad-Gate (`tenants/{tenantId}/files/{fileId}/v{n}/original`) übernehmen — **1:1**.
2. **M052 Anti-Virus + MIME-Whitelist:** ClamAV-Scanner + Quarantine + `createStorageScanService` + `file-scan`-Worker-Handler **1:1/als-vorlage** übernehmen. **Allow-List um `files`-Kontext erweitern** (Video/Audio/HEIC/ODF/Text/Markdown). `storageService.ts`/`storageAudit.server.ts` als Vorlage für das HiveGrid-Upload-Wiring (tenant-scoped, Audit bei Reject).
3. **Daten-Modell neu bauen:** `File`/`FileVersion`/`FileEntityLink` + fachliches `FileUploadProgress`/`FileChunk` (tenant-scoped, Resume, Checksum). `FileObject`/`AuditEvent` als Feld-/Querschnitt-Vorlage. Forward-Only-Migration mit Inverse-SQL-Kommentar (DoD).
4. **Chunked Upload + Versionierung** (M052/M054): Init/Stream/Concat-Endpoints; Multipart-Sink aus `packages/exports` für Concat; Resume-Logik gegen `FileUploadProgress`. Versionierung + Rollback (neue Version statt In-Place).
5. **M054 Permissions:** Bundle-Engine `files.*` + transitive Sichtbarkeit über `FileEntityLink` (Index nutzen), via `withTenantScope()`/`withPermission()`. HR-Sonderfall an M14 anbinden.
6. **Preview-Generation neu** (eigener Worker-Job, Pattern aus `handlers.ts`): Library-Auswahl finalisieren (sharp/libheif für HEIC, LibreOffice-Headless für Office, pdf/Frame für Video). Status-Rückschreibung in `File.preview_status`. **Höchster Eigenbau-Aufwand, keine BP-Vorlage.**
7. **M055 Suche/Tagging/Archivierung:** Tags via M044, Archivierung (`archived_at`-Soft-Delete + „Archivierte anzeigen"-Toggle), OCR-Pipeline + Such-Index-Registrierung (M056). Cleanup-Jobs (Cron-Pattern aus `audit-retention.ts`).
8. **UI in `packages/ui-hivegrid` + Subframe** (Layer-Disziplin AGENTS A, mandatory Subframe-Design): Files-Browser, Detail, Upload (Chunked-Progress), Versions-Sub-View, embedded vorgefilterter Browser. Boilerplate-Dropzone nur als Funktions-Vorlage. Sidebar-Wiring + Breadcrumb + i18n-Keys.
9. **Querschnitt schließen:** Activity-Stream (M045), Notifications (M011), Feature-Flag (M006), Audit (M001), DSGVO-Export (`packages/exports`-Vorlage). Smoke-Test + Hot-Swap-Drill + Visual-Regression-Snapshot (DoD).
**Achtung-Punkte:**
- BP-`FileChunk` speichert Bytes in der DB (`data Bytes`) — Spec will Chunks im temporären **Storage-Bucket** (`storage_key`). Architektur-Entscheidung früh treffen, BP-Modell nicht blind übernehmen.
- `browser-image-compression` ist **nicht** in der Boilerplate (entgegen M052-Plan-Hinweis) — als Dependency neu hinzufügen oder Server-side-Compression.
- Preview/HEIC/Office-Konvertierung ist der größte Greenfield-Block — frühzeitig spiken (Library + Worker-Timeout).