Files
HiveGrid-Wireframes/hivegrid-cloud/docs/boilerplate-mapping/M23-files.md
T

16 KiB
Raw Blame History

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).