16 KiB
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: keintenant_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). Keintenant_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) mitdisplay_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-Indexdisplay_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/FileChunkmit 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 auspackages/exportsals 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 (
sharpnur in pnpmonlyBuiltDependencies, nicht als Dependency; keinbrowser-image-compressiontrotz 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.tsals 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-Typenfile_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:
- M053 (Storage-Backend) zuerst-nah verdrahten:
@toolctrl/storageals Workspace-Dep einziehen. S3-Adapter + Signed-URL-Adapter (apps/api/src/storage.ts-SigV4 als Signer) auf Scaleway konfigurieren.authorizeStorageObjectAccessals verbindlichen Tenant-Pfad-Gate (tenants/{tenantId}/files/{fileId}/v{n}/original) übernehmen — 1:1. - M052 Anti-Virus + MIME-Whitelist: ClamAV-Scanner + Quarantine +
createStorageScanService+file-scan-Worker-Handler 1:1/als-vorlage übernehmen. Allow-List umfiles-Kontext erweitern (Video/Audio/HEIC/ODF/Text/Markdown).storageService.ts/storageAudit.server.tsals Vorlage für das HiveGrid-Upload-Wiring (tenant-scoped, Audit bei Reject). - Daten-Modell neu bauen:
File/FileVersion/FileEntityLink+ fachlichesFileUploadProgress/FileChunk(tenant-scoped, Resume, Checksum).FileObject/AuditEventals Feld-/Querschnitt-Vorlage. Forward-Only-Migration mit Inverse-SQL-Kommentar (DoD). - Chunked Upload + Versionierung (M052/M054): Init/Stream/Concat-Endpoints; Multipart-Sink aus
packages/exportsfür Concat; Resume-Logik gegenFileUploadProgress. Versionierung + Rollback (neue Version statt In-Place). - M054 Permissions: Bundle-Engine
files.*+ transitive Sichtbarkeit überFileEntityLink(Index nutzen), viawithTenantScope()/withPermission(). HR-Sonderfall an M14 anbinden. - 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 inFile.preview_status. Höchster Eigenbau-Aufwand, keine BP-Vorlage. - 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 ausaudit-retention.ts). - 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. - 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-
FileChunkspeichert 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-compressionist 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).