547 lines
25 KiB
Markdown
547 lines
25 KiB
Markdown
---
|
||
module: 23
|
||
title: Files / Dokumentenablage
|
||
phase: 1
|
||
status: detail-spec-draft
|
||
last_updated: 2026-05-08
|
||
session_source: brainstorming-session-2026-05-07-2206.md
|
||
related_lps: [LP-1, LP-7, LP-9, LP-10, LP-11, LP-13]
|
||
spec_style: requirements-pur
|
||
---
|
||
|
||
# Modul 23 — Files / Dokumentenablage
|
||
|
||
> **Detail-Spec gemäß LP-9.** Zentrale Dokumentenablage pro Tenant mit Verknüpfung an alle relevanten Entitäten. Storage komplett auf Scaleway (EU, DSGVO; LP-13). Löst Datei-Anhänge in HubSpot und ad-hoc-Dropbox-Nutzung bei Geerkens ab.
|
||
|
||
## Themenblöcke
|
||
|
||
```
|
||
A. Datenmodell (File, FileVersion, FileChunk, FileUploadProgress, FileEntityLink)
|
||
B. Menü-Struktur und Routes
|
||
C. Listen-Views (Files-Browser mit Entitäts-Filter)
|
||
D. Detail-Views (File-Vorschau, Versionen, Verknüpfungen)
|
||
E. Upload-Workflow (Chunked Upload mit Progress)
|
||
F. Versionierung (gleicher Dateiname → V1, V2, ...)
|
||
G. Preview-Generation (PDF, Bild, Office)
|
||
H. Verknüpfungen an Entitäten (Kontakt, Deal, Projekt, User, Form-Submission, Auftrag)
|
||
I. Activity-Stream-Integration
|
||
J. Permissions-Anwendung
|
||
K. Storage-Architektur (Scaleway, Tenant-Isolation)
|
||
```
|
||
|
||
---
|
||
|
||
## Block A — Datenmodell
|
||
|
||
### File
|
||
|
||
Tenant-scoped, Soft-Delete, RLS-aktiv.
|
||
|
||
- `id`, `tenant_id`, `created_at`, `updated_at`, `created_by_user_id`
|
||
- `display_name` (User-sichtbarer Name; identisch zum Original-Dateinamen beim Upload)
|
||
- `mime_type`
|
||
- `size_bytes`
|
||
- `storage_key` (Pfad in Scaleway-Bucket; Format `tenants/{tenantId}/files/{fileId}/v{version}/original`)
|
||
- `current_version` (Integer, Default 1)
|
||
- `checksum_sha256` (für Duplikat-Erkennung und Integrität)
|
||
- `preview_status` (Enum: `pending | generating | ready | failed | not_supported`)
|
||
- `preview_storage_key` (Pfad zur Preview-Datei, NULL bei `not_supported`)
|
||
- `assigned_to_user_id` (optional — Hauptverantwortlicher für die Datei)
|
||
- `tags[]` (siehe Modul 1, Block H — wiederverwendet)
|
||
- `notes` (Markdown-Freitext, optional)
|
||
- `archived_at` (Soft-Delete)
|
||
- `source` (Enum: `manual_upload | customer_portal | form_submission | email_attachment | automation | api`)
|
||
|
||
**Indizes:**
|
||
- `(tenant_id, archived_at, created_at DESC)` — Default-Sortierung im Browser
|
||
- `(tenant_id, created_by_user_id)` — Owner-Filter
|
||
- `(tenant_id, checksum_sha256)` — Duplikat-Erkennung
|
||
- Trigram-Index auf `display_name` für Fuzzy-Suche
|
||
|
||
### FileVersion
|
||
|
||
Append-only — Versionen werden nie gelöscht (außer beim Hard-Delete der File).
|
||
|
||
- `id`, `file_id`, `tenant_id`, `created_at`, `created_by_user_id`
|
||
- `version_number` (Integer, fortlaufend)
|
||
- `storage_key`
|
||
- `size_bytes`
|
||
- `checksum_sha256`
|
||
- `change_note` (optional Freitext — was wurde geändert)
|
||
|
||
**Constraint:** `(file_id, version_number)` unique.
|
||
|
||
### FileChunk
|
||
|
||
Temporär während Upload, wird nach erfolgreichem Zusammenbau gelöscht.
|
||
|
||
- `id`, `tenant_id`, `upload_id` (siehe `FileUploadProgress`)
|
||
- `chunk_index`
|
||
- `storage_key` (temporärer Pfad)
|
||
- `size_bytes`
|
||
- `checksum_sha256`
|
||
- `received_at`
|
||
|
||
**Constraint:** `(upload_id, chunk_index)` unique.
|
||
|
||
### FileUploadProgress
|
||
|
||
Steuert chunked Upload; ermöglicht Resume nach Verbindungsabbruch (mobil-relevant).
|
||
|
||
- `id`, `tenant_id`, `created_by_user_id`, `created_at`, `updated_at`
|
||
- `original_filename`
|
||
- `total_size_bytes`
|
||
- `total_chunks`
|
||
- `received_chunks` (Integer)
|
||
- `expires_at` (Default: 24h nach `created_at` — danach Cleanup-Job)
|
||
- `status` (Enum: `in_progress | completed | failed | expired | cancelled`)
|
||
- `target_file_id` (NULL bis Abschluss; bei Versions-Upload bereits gesetzt)
|
||
- `target_version_intent` (Enum: `new_file | new_version`)
|
||
- `failure_reason` (optional Klartext)
|
||
|
||
**Indizes:** `(tenant_id, created_by_user_id, status)`.
|
||
|
||
### FileEntityLink
|
||
|
||
M:N-Verknüpfung von File zu beliebigen Entitäten.
|
||
|
||
- `id`, `tenant_id`, `file_id`, `created_at`, `created_by_user_id`
|
||
- `entity_type` (Enum: `contact | company | lead | deal | project | user | form_submission | order | task | appointment`)
|
||
- `entity_id`
|
||
- `link_role` (optional Freitext — z.B. „Auftragsbestätigung", „Foto vor Montage", „Acceptance-Beleg")
|
||
|
||
**Constraints:**
|
||
- `(file_id, entity_type, entity_id)` unique
|
||
- Index `(tenant_id, entity_type, entity_id)` für „alle Files an Entity X"-Query
|
||
|
||
**Begründung M:N:** Eine Datei kann gleichzeitig zu Kontakt, Deal, Projekt, Auftrag gehören (z.B. Angebots-PDF: Kontakt + Deal + ggf. Projekt nach Won).
|
||
|
||
---
|
||
|
||
## Block B — Menü-Struktur und Routes
|
||
|
||
**Sidebar-Hauptpunkt:** *Files*.
|
||
|
||
**Routen:**
|
||
|
||
```
|
||
/{tenant}/files → Files-Browser (alle Files des Tenants)
|
||
/{tenant}/files/upload → Upload-View (Drag-and-Drop oder File-Picker)
|
||
/{tenant}/files/:id → File-Detail-View (Vorschau, Versionen, Verknüpfungen)
|
||
/{tenant}/files/:id/versions → Versionsverlauf (Sub-View)
|
||
|
||
/{tenant}/admin/files/ → Admin-Übersicht (Storage-Verbrauch pro Tenant, Phase 2)
|
||
```
|
||
|
||
**Embedded-Anwendung:** Der Files-Browser erscheint zusätzlich als Sub-Sektion in Detail-Views anderer Module:
|
||
- `/{tenant}/contacts/:id` (Tab/Sektion „Files")
|
||
- `/{tenant}/contacts/companies/:id`
|
||
- `/{tenant}/deals/:id`
|
||
- `/{tenant}/projects/:id`
|
||
- `/{tenant}/leads/:id`
|
||
- usw.
|
||
|
||
In diesen Kontexten ist der Browser **vorgefiltert** auf die jeweilige Entity.
|
||
|
||
---
|
||
|
||
## Block C — Listen-Views (Files-Browser)
|
||
|
||
### Zu zeigende Daten pro Eintrag
|
||
|
||
- Datei-Identität (Display-Name, Dateityp-Indikator)
|
||
- Größe
|
||
- Erstellt-Datum + Ersteller
|
||
- Aktuelle Version (z.B. „V3")
|
||
- Tags
|
||
- Verantwortlicher
|
||
- Verknüpfte Entitäten (Anzahl + erste 1-2 als Klartext, Rest als „+N")
|
||
- Quelle (manuell / Form / Customer-Portal / Email / Automation)
|
||
- Vorschau-Thumbnail (falls verfügbar)
|
||
|
||
### Benötigte UI-Elemente
|
||
|
||
- Tabellarische oder Grid-Anzeige (Designer wählt; beide Varianten umschaltbar als User-Setting)
|
||
- Spalten-Header klickbar für Sortierung
|
||
- Such-Funktion (Volltext über Display-Name, Notes, Tags, später OCR-Text in Phase 2)
|
||
- Filter-Komponenten:
|
||
- Verknüpfte Entität (Auto-Complete: Kontakt / Firma / Deal / Projekt / ...)
|
||
- Entitäts-Typ (Multi-Select)
|
||
- Verantwortlicher (Multi-Select)
|
||
- Ersteller (Multi-Select)
|
||
- Tags (Multi-Select mit AND/OR-Toggle)
|
||
- Erstellt-Zeitraum (Date-Range-Picker)
|
||
- Dateityp / MIME-Gruppe (Multi-Select: Bild / PDF / Office / Video / Audio / Sonstige)
|
||
- Quelle (Multi-Select)
|
||
- Größe (Range-Filter)
|
||
- Toggle „Archivierte anzeigen"
|
||
- Bulk-Auswahl (Checkboxes)
|
||
- Pagination (Cursor-basiert, „Mehr laden", 50 pro Page)
|
||
- Spalten-Konfiguration pro User (sichtbare Spalten + Reihenfolge persistiert)
|
||
- Ansichts-Umschalter (Tabelle / Grid mit Thumbnails)
|
||
|
||
### Operationen
|
||
|
||
- Sortierung pro Spalte (Default: Erstellt-Datum absteigend)
|
||
- Filter anwenden / kombinieren / zurücksetzen
|
||
- Bulk-Actions:
|
||
- Tag hinzufügen / entfernen
|
||
- Verantwortlicher zuweisen
|
||
- An Entity verknüpfen / Verknüpfung lösen
|
||
- Archivieren / Reaktivieren
|
||
- Download als ZIP
|
||
- Hard-Delete (mit Klartext-Warnung)
|
||
- Klick auf File-Zeile → Detail-View
|
||
- Inline-Schnell-Vorschau (Hover oder Single-Klick öffnet Quick-Preview, ohne Detail-View zu laden)
|
||
|
||
### Performance-Anforderungen
|
||
|
||
- Server-side-Filter (kein Client-side-Filtern)
|
||
- Index siehe Datenmodell-Sektion
|
||
- Thumbnail-Lazy-Loading (Viewport-basiert)
|
||
- Bei Filter „verknüpft mit Entity X" wird `FileEntityLink` als Join genutzt, nicht Volltext-Suche
|
||
|
||
---
|
||
|
||
## Block D — Detail-Views
|
||
|
||
### File-Detail (`/{tenant}/files/:id`)
|
||
|
||
**Zu zeigende Daten:**
|
||
|
||
- Stammdaten (Display-Name, Dateityp, Größe, Checksum, Erstellt-Datum + Ersteller, Verantwortlicher, Quelle)
|
||
- Aktuelle Version (Nummer + Datum + Ersteller dieser Version)
|
||
- Tags
|
||
- Notizen
|
||
- Vorschau der aktuellen Version (PDF/Bild/Office; Fallback bei `not_supported`: Klartext-Hinweis + Download-Funktion)
|
||
- Verknüpfte Entitäten (gruppiert nach Typ, mit Link-Role)
|
||
- Versionsverlauf (Anzahl + Link auf Sub-View)
|
||
- Activity-Stream zu dieser File (Upload, Versionen, Verknüpfungs-Änderungen, Downloads — siehe Block I)
|
||
|
||
**Benötigte UI-Elemente:**
|
||
|
||
- Vorschau-Komponente (PDF-Viewer, Bild-Viewer mit Zoom, Office-Viewer, Video/Audio-Player)
|
||
- Inline-Edit für Stammdaten (Display-Name, Notes, Tags, Verantwortlicher)
|
||
- Verknüpfungs-Verwaltung mit Auto-Complete pro Entitäts-Typ und Rollen-Eingabefeld
|
||
- Action-Funktionen für Operationen (siehe unten)
|
||
- Versions-Sektion mit Anzeige aller Versionen (Nummer, Datum, Ersteller, Change-Note, Größe, Download-Funktion pro Version)
|
||
|
||
**Operationen:**
|
||
|
||
- Download (aktuelle Version)
|
||
- Download spezifische Version
|
||
- Neue Version hochladen (siehe Block F)
|
||
- Display-Name umbenennen (Original-Datei in Storage bleibt unverändert; nur `display_name` ändert sich)
|
||
- Notes editieren
|
||
- Tags hinzufügen / entfernen
|
||
- Verantwortlichen ändern
|
||
- Entitäts-Verknüpfung hinzufügen / entfernen / Rolle ändern
|
||
- Vorschau erneut generieren (manueller Trigger bei `failed`)
|
||
- Archivieren / Reaktivieren
|
||
- Hard-Delete (Multi-Step-Confirm: Klartext-Warnung über alle Versionen + Verknüpfungen + Activity-Einträge die mit gelöscht werden)
|
||
- DSGVO-Export (Datei + Metadaten als ZIP — über Modul 35)
|
||
- Permalink kopieren (auth-pflichtige URL — kein Public-Link in Phase 1)
|
||
|
||
### Versionsverlauf-Sub-View (`/{tenant}/files/:id/versions`)
|
||
|
||
**Zu zeigende Daten:**
|
||
|
||
- Liste aller Versionen chronologisch absteigend
|
||
- Pro Version: Nummer, Datum, Ersteller, Größe, Change-Note, Aktiv-Markierung (für `current_version`)
|
||
|
||
**Benötigte UI-Elemente:**
|
||
|
||
- Versionsliste
|
||
- Pro Version: Download-Funktion, Vorschau-Funktion, „Als aktuelle Version setzen" (Rollback)
|
||
|
||
**Operationen:**
|
||
|
||
- Vorschau älterer Version
|
||
- Download älterer Version
|
||
- Rollback zu älterer Version (legt **neue** Version mit Inhalt der gewählten alten Version an — kein Löschen, Audit-Trail bleibt)
|
||
- Change-Note nachträglich editieren (eigene oder mit `files.admin`)
|
||
|
||
---
|
||
|
||
## Block E — Upload-Workflow (Chunked Upload mit Progress)
|
||
|
||
### Anforderungen
|
||
|
||
- **Chunk-Größe:** 5 MB (mobil-optimiert; Trade-off zwischen Overhead und Resume-Granularität)
|
||
- **Parallel-Chunks:** max. 3 parallel pro Upload (Bandbreiten-schonend für mobile/baustelle)
|
||
- **Resume:** bei Verbindungsabbruch wird `FileUploadProgress` persistiert; Client kann nach Reconnect die fehlenden Chunks nachsenden
|
||
- **Maximum-Größe pro File:** 500 MB Default (Tenant-Admin-konfigurierbar bis 2 GB; Phase 2: Storage-Limits pro Subscription-Plan)
|
||
- **Mehrfach-Upload:** mehrere Dateien gleichzeitig (Queue)
|
||
- **Drag-and-Drop:** Browser + native Capacitor-File-Picker auf Mobile
|
||
- **Foto-Direkt-Upload:** Kamera-Integration über Capacitor (Modul 36); Foto wird sofort hochgeladen
|
||
- **Offline-Modus:** Foto/Datei wird in IndexedDB-Queue gehalten, Upload startet bei Reconnect (LP-8)
|
||
|
||
### Klartext-Progress-Anzeige
|
||
|
||
- Pro Datei: Name, Fortschritt in Prozent + Datentransfer (z.B. „12 MB / 47 MB"), geschätzte Restzeit
|
||
- Bei Fehler: Klartext-Reason (siehe Klartext-Hinweise unten) + Retry-Funktion
|
||
- Bei Erfolg: Übergang in Files-Browser oder direkt in Detail-View (User-Wahl)
|
||
|
||
### Upload-API-Verlauf (logisch)
|
||
|
||
1. Client ruft Init-Endpoint auf mit `original_filename`, `total_size_bytes`, `mime_type`, optional `target_file_id` für Versions-Upload, optional Verknüpfungs-Vorgaben
|
||
2. Server legt `FileUploadProgress` an, gibt `upload_id` und Chunk-Größe zurück
|
||
3. Client streamt Chunks mit `(upload_id, chunk_index, chunk_data)`
|
||
4. Server validiert Chunk-Checksum, persistiert in temporären Storage-Bereich, inkrementiert `received_chunks`
|
||
5. Bei Letztem Chunk: Server baut die Datei zusammen (Server-side-Concat oder Multi-Part-Upload bei Scaleway), validiert Gesamt-Checksum, legt `File` (oder neue `FileVersion`) an, löscht temporäre Chunks, setzt `FileUploadProgress.status = completed`
|
||
6. Server triggert Preview-Generation-Job (siehe Block G)
|
||
7. Client erhält finale `file_id` und ggf. URL
|
||
|
||
### Edge-Cases
|
||
|
||
- Upload-Abbruch durch User: `FileUploadProgress.status = cancelled`, temporäre Chunks werden vom Cleanup-Job entfernt
|
||
- Upload-Expiry (24h ohne Aktivität): `expired`, Chunks gelöscht
|
||
- Server-Fehler bei Concat: `failed` mit `failure_reason`, User kann Re-Upload starten (komplett neu, nicht resume)
|
||
- Duplikat-Check (per Checksum): bei exaktem Match einer existierenden, nicht-archivierten File des gleichen Tenants Klartext-Hinweis: *„Diese Datei existiert bereits als ‚{display_name}'. Möchtest du eine neue Version anlegen, eine Verknüpfung hinzufügen oder trotzdem als neue Datei speichern?"*
|
||
|
||
---
|
||
|
||
## Block F — Versionierung
|
||
|
||
### Trigger für neue Version
|
||
|
||
- **Automatisch beim Upload mit gleichem `display_name`** an dieselbe File-ID (z.B. über „Neue Version hochladen"-Funktion in der Detail-View)
|
||
- **Vorschlag bei Upload mit gleichem Display-Name** in einem Entity-Kontext: *„Es gibt bereits eine Datei ‚angebot.pdf' in diesem Projekt. Möchtest du eine neue Version anlegen oder eine separate Datei?"*
|
||
- **Manuell** über „Neue Version hochladen" in File-Detail-View (Display-Name kann abweichen, Versionierung wird trotzdem fortgeführt)
|
||
|
||
### Anforderungen
|
||
|
||
- Versionsnummern sind fortlaufend (1, 2, 3, ...) und nicht editierbar
|
||
- Beim Anlegen einer neuen Version: optional Change-Note, sonst Default-Klartext (z.B. „Version hochgeladen am {Datum}")
|
||
- Vorherige Versionen bleiben in Storage und Datenbank
|
||
- Hard-Delete der File entfernt **alle** Versionen
|
||
- Storage-Pfad-Konvention: `tenants/{tenantId}/files/{fileId}/v{versionNumber}/original`
|
||
- Preview wird pro Version separat generiert
|
||
|
||
### Rollback
|
||
|
||
- „Als aktuelle Version setzen" auf einer alten Version legt **neue** Version mit Inhalt der gewählten alten Version an
|
||
- Kein In-Place-Rollback (Audit-Trail-Integrität)
|
||
|
||
### Klartext-Hinweise
|
||
|
||
- Beim Versions-Upload: *„Datei wird als Version {n} gespeichert. Vorherige Versionen bleiben verfügbar."*
|
||
- Beim Rollback: *„Inhalt von Version {n} wird als neue Version {m} gespeichert. Vorherige Versionen bleiben unverändert."*
|
||
|
||
---
|
||
|
||
## Block G — Preview-Generation
|
||
|
||
### Unterstützte Typen (Phase 1)
|
||
|
||
- **PDF:** direkt
|
||
- **Bilder:** JPEG, PNG, GIF, WebP, HEIC (HEIC-Konvertierung nach JPEG für Browser-Kompatibilität)
|
||
- **Office:** DOCX, XLSX, PPTX, ODT, ODS, ODP — Konvertierung nach PDF (LibreOffice-Headless oder vergleichbar; Server-side Worker)
|
||
- **Video:** Thumbnail (erster Frame oder konfigurierbar) + Browser-natives Playback im Detail-View
|
||
- **Audio:** keine Vorschau, nur Player
|
||
- **Plain-Text / Markdown:** direkte Anzeige
|
||
- **Sonstige:** `not_supported` → nur Download-Funktion
|
||
|
||
### Anforderungen
|
||
|
||
- Preview-Generation als asynchroner Worker-Job (Modul 17 / interne Worker-Queue)
|
||
- Status-Spalte `preview_status` mit Werten `pending | generating | ready | failed | not_supported`
|
||
- Bei `failed`: manueller Re-Trigger über Detail-View (Permission `files.write`)
|
||
- Preview-Output landet in `tenants/{tenantId}/files/{fileId}/v{versionNumber}/preview.{ext}` (PDF für Office, JPEG für Bilder/Video-Thumbnail)
|
||
- Thumbnail-Generation für Listen-Grid (kleinere Auflösung, separater Storage-Pfad)
|
||
- Maximaler Worker-Timeout pro Job (z.B. 5 Min); bei Überschreitung `failed`
|
||
|
||
### Klartext-Hinweise
|
||
|
||
- `pending` / `generating`: *„Vorschau wird erstellt — kann einen Moment dauern."*
|
||
- `failed`: *„Vorschau konnte nicht erstellt werden. Datei kann heruntergeladen und lokal geöffnet werden. [Erneut versuchen]"*
|
||
- `not_supported`: *„Für diesen Dateityp ist keine Vorschau verfügbar. [Herunterladen]"*
|
||
|
||
---
|
||
|
||
## Block H — Verknüpfungen an Entitäten
|
||
|
||
### Unterstützte Entitäts-Typen (Phase 1)
|
||
|
||
- `contact` (Modul 1)
|
||
- `company` (Modul 1)
|
||
- `lead` (Modul 1, 2)
|
||
- `deal` (Modul 3)
|
||
- `project` (Modul 4)
|
||
- `order` (Modul 4 / KWP-Sync)
|
||
- `user` (Modul 27 — z.B. HR-Dokumente am Mitarbeiter; Permissions besonders, siehe HR-Hub Modul 14)
|
||
- `form_submission` (Modul 5 — bei File-Upload-Feldern)
|
||
- `task` (Modul 26)
|
||
- `appointment` (Modul 6 / 25)
|
||
|
||
### Anforderungen
|
||
|
||
- Verknüpfungen sind M:N (siehe Datenmodell `FileEntityLink`)
|
||
- Pro Verknüpfung optional `link_role` (Freitext)
|
||
- Verknüpfungen werden im Activity-Stream der Ziel-Entity gespiegelt (Activity-Typ `file_uploaded` mit `metadata.entity_type` und `link_role`)
|
||
- Hinzufügen einer Verknüpfung erfordert `files.write` **und** Lese-Permission auf die Ziel-Entity
|
||
- Entfernen einer Verknüpfung erfordert `files.write`
|
||
|
||
### Verknüpfung über Customer-Portal-Upload
|
||
|
||
- Endkunden-Uploads (Modul 15) landen automatisch in Files
|
||
- `source = customer_portal`
|
||
- Auto-Verknüpfung mit dem `Project`/`Deal`/`Order`, in dessen Kontext der Upload erfolgt
|
||
- `created_by_user_id` ist NULL (Upload kommt von `PortalUser`, separate User-Klasse); zusätzlich `created_by_portal_user_id` (Pflicht-Feld in diesem Fall — für Audit-Trail; nicht in Datenmodell oben aufgeführt um Spec klein zu halten, ist aber bei Implementierung zu ergänzen)
|
||
- Klartext-Hinweis im Files-Browser: Quelle als „Customer-Portal" + Name des hochladenden Endkunden
|
||
|
||
### Verknüpfung über Form-Submission
|
||
|
||
- Form-Builder (Modul 5) hat File-Upload-Felder
|
||
- Bei Submission landen Files in dieser Modul-Struktur
|
||
- Auto-Verknüpfung mit der `FormSubmission`
|
||
- `source = form_submission`
|
||
|
||
---
|
||
|
||
## Block I — Activity-Stream-Integration
|
||
|
||
Files erzeugen Activities im zentralen Activity-Stream (Modul 1, Block E):
|
||
|
||
- `file_uploaded` (subject = die Ziel-Entity; metadata enthält `file_id`, `display_name`, `link_role`)
|
||
- `file_version_added` (subject = die File; ggf. zusätzlich gespiegelt an verknüpfte Entities)
|
||
- `file_link_added` / `file_link_removed`
|
||
- `file_archived` / `file_restored`
|
||
- `file_renamed` (Display-Name)
|
||
- `file_deleted` (Hard-Delete; subject = NULL nach Delete, aber Activity bleibt mit `metadata.deleted_file_name`)
|
||
- `file_downloaded` (Phase 2 — optional Tracking; nicht in Phase 1 wegen Audit-Last)
|
||
|
||
**`summary_text`-Beispiele (Klartext-DE):**
|
||
- „Max Mustermann hat ‚angebot.pdf' an Deal ‚Heizungstausch Schmidt' angehängt."
|
||
- „Sandra Müller hat Version 3 von ‚wartungsvertrag.pdf' hochgeladen."
|
||
- „Anna Becker (Customer-Portal) hat ‚foto-zaehler.jpg' an Projekt ‚Heizung Schmidt' hochgeladen."
|
||
|
||
---
|
||
|
||
## Block J — Permissions-Anwendung
|
||
|
||
### Permission-IDs
|
||
|
||
| Permission | Erlaubt |
|
||
|---|---|
|
||
| `files.read_own` | Files sehen, bei denen User = `created_by_user_id` ODER `assigned_to_user_id` ODER über Entity-Verknüpfung indirekt sichtbar (z.B. eigenes Projekt) |
|
||
| `files.read_all` | Alle Files des Tenants sehen |
|
||
| `files.write` | Hochladen, neue Version, umbenennen, taggen, verknüpfen, archivieren |
|
||
| `files.delete` | Hard-Delete |
|
||
| `files.admin` | Storage-Limits ändern (Phase 2), alle Files (auch ohne Owner-Match) verwalten, DSGVO-Export beliebiger Files |
|
||
|
||
### Bundle-Mapping (Variante 2)
|
||
|
||
| Bundle | Atomare Permissions |
|
||
|---|---|
|
||
| `files.none` | (keine) |
|
||
| `files.read_own` | `files.read_own` |
|
||
| `files.read_all` | `files.read_own` + `files.read_all` |
|
||
| `files.write` | `files.read_all` + `files.write` |
|
||
| `files.admin` | `files.read_all` + `files.write` + `files.delete` + `files.admin` |
|
||
|
||
### Anwendung in Routes
|
||
|
||
- `/{tenant}/files` → `files.read_own` oder `files.read_all`
|
||
- `/{tenant}/files/upload` → `files.write`
|
||
- `/{tenant}/files/:id` → `files.read_own` (mit Owner-/Entity-Sichtbarkeits-Check) oder `files.read_all`
|
||
- `/{tenant}/files/:id/versions` → analog
|
||
- `/{tenant}/admin/files/` → `files.admin` oder `tenant.admin`
|
||
|
||
### Anwendung in Action-Funktionen
|
||
|
||
- Upload / neue Version / Umbenennen / Verknüpfen: `files.write`
|
||
- Hard-Delete: `files.delete`
|
||
- DSGVO-Export einzelner File: `files.admin` (außer eigene Files: `files.read_own` reicht)
|
||
|
||
### Owner-Check-Logik bei `files.read_own`
|
||
|
||
User sieht eine File wenn **eine** der folgenden Bedingungen erfüllt ist:
|
||
|
||
1. `File.created_by_user_id = self`
|
||
2. `File.assigned_to_user_id = self`
|
||
3. Es existiert ein `FileEntityLink` zu einer Entity, auf die der User Lese-Zugriff hat (transitive Sichtbarkeit über Modul-Permissions: z.B. wenn User `projects.read_own` hat und das verlinkte Projekt ihm gehört → File sichtbar)
|
||
|
||
**Implementierungs-Hinweis:** Transitive Sichtbarkeit ist Performance-relevant. Index auf `FileEntityLink (tenant_id, entity_type, entity_id)` und Materialized View / Cache pro User erwägen.
|
||
|
||
### HR-Sonderfall
|
||
|
||
Files an `user`-Entity (HR-Dokumente, z.B. Lohnabrechnungen) folgen HR-Hub-Permissions (Modul 14, separate Spec). Default: nur User selbst + `hr.admin` sehen die Datei, auch mit `files.read_all`.
|
||
|
||
---
|
||
|
||
## Block K — Storage-Architektur
|
||
|
||
### Anforderungen
|
||
|
||
- **Provider:** Scaleway Object Storage (EU, DSGVO-konform; LP-13)
|
||
- **Bucket-Strategie:** ein Bucket pro Region, Pfad-Präfix `tenants/{tenantId}/...` für Isolation
|
||
- **Verschlüsselung:** Server-side Encryption (Scaleway-managed Keys in Phase 1; KMS-Customer-Keys Phase 2)
|
||
- **Zugriff:** keine Public-URLs; signierte URLs mit kurzer Lebenszeit (z.B. 5 Min) für Browser-Download/Preview
|
||
- **Tenant-Isolation:** App-Code prüft, dass `storage_key` zu `tenant_id` aus dem aktuellen Request passt; zusätzliche Schutz-Schicht zur RLS in der DB
|
||
- **Backup:** Scaleway-Multi-Zone-Replikation; tägliche Snapshots
|
||
- **Lifecycle:** Hard-Delete der File löscht alle Versionen + Previews + Thumbnails aus Storage (Cleanup-Job, asynchron, mit Audit-Eintrag)
|
||
- **Storage-Verbrauch pro Tenant:** wird pro Upload aktualisiert, in Tenant-Admin-View sichtbar (Phase 2: Limits pro Subscription-Plan, siehe Modul 28)
|
||
|
||
### Cleanup-Jobs
|
||
|
||
- Temporäre Chunks von expired/cancelled/failed `FileUploadProgress`: täglich
|
||
- Hard-gelöschte Files: sofortiger Trigger + Verifikation in nachgelagertem Job (24h später)
|
||
- Verwaiste Storage-Objekte (kein DB-Eintrag): wöchentlicher Reconciliation-Job mit Klartext-Report
|
||
|
||
---
|
||
|
||
## Klartext-Hinweise / Fehler-Cases (LP-10)
|
||
|
||
- **Upload-Abbruch (Netzwerk):** *„Verbindung unterbrochen. Bereits hochgeladene Daten bleiben — Upload wird fortgesetzt sobald du wieder online bist."*
|
||
- **Upload zu groß:** *„Datei ist {size} groß. Maximale Dateigröße in diesem Workspace: {max}. Frag deinen Workspace-Admin, wenn du größere Dateien hochladen musst."*
|
||
- **Mime-Typ blockiert (z.B. ausführbare Dateien):** *„Dateityp ‚{mime}' ist aus Sicherheitsgründen nicht erlaubt."*
|
||
- **Storage-Limit erreicht (Phase 2):** *„Speicher-Limit dieses Workspace ist erreicht. Bitte alte Dateien archivieren oder Plan upgraden."*
|
||
- **Preview fehlgeschlagen:** *„Vorschau konnte nicht erstellt werden. Datei kann heruntergeladen und lokal geöffnet werden. [Erneut versuchen]"*
|
||
- **Duplikat-Match:** *„Diese Datei existiert bereits als ‚{name}' in diesem Workspace. [Neue Version anlegen] [Verknüpfung hinzufügen] [Trotzdem neu speichern]"*
|
||
- **Hard-Delete-Warnung:** *„Diese Datei hat {n} Versionen und ist mit {m} Einträgen verknüpft. Beim Löschen gehen alle Versionen und Verknüpfungen verloren. Stattdessen archivieren? [Archivieren] [Endgültig löschen]"*
|
||
- **Permission-Block beim Anhängen an Entity:** *„Du hast keinen Zugriff auf {entity_name}. Bitte einen Kollegen mit Zugriff bitten, die Verknüpfung hinzuzufügen."*
|
||
- **Customer-Portal-Upload erkannt:** *„Diese Datei wurde von {endkunde_name} über das Kunden-Portal hochgeladen am {datum}."*
|
||
|
||
---
|
||
|
||
## Phase 2 / spätere Features
|
||
|
||
- **OCR** für PDF/Bilder, Volltext-Index der OCR-Ergebnisse für globale Suche (Modul 24)
|
||
- **KI-Auto-Tagging** (Mistral/Scaleway) — schlägt Tags und Verknüpfungen basierend auf Inhalt vor
|
||
- **Storage-Limits** pro Subscription-Plan (Modul 28); UI-Banner bei Annäherung
|
||
- **Archivierungs-Workflow:** automatisches Archivieren von Files nach X Monaten ohne Zugriff (konfigurierbar)
|
||
- **Public-Share-Links** (z.B. Angebot per Link an Kunden) — separat von Customer-Portal
|
||
- **Watermarking** für PDFs (z.B. Empfänger-Name)
|
||
- **Versions-Vergleich** (Diff-View für PDFs/Office)
|
||
- **Folder-Strukturen** (in Phase 1 bewusst NICHT — Tags + Entity-Verknüpfungen + Filter ersetzen Folder)
|
||
- **Datei-Locking** beim parallelen Editieren (für Office-Online-Integration)
|
||
- **KMS-Customer-Keys** (Enterprise)
|
||
|
||
---
|
||
|
||
## Architektur-Vorschriften (Querschnitt)
|
||
|
||
- **LP-10, AV #1:** Klartext-Diagnostik überall (Upload-Fehler, Preview-Fehler, Permission-Blocks)
|
||
- **LP-13, AV #12:** EU-Stack — Scaleway-Storage, EU-Verschlüsselung, kein US-CDN
|
||
- **AV #5:** Permissions-aware-Default in Listen und transitiver Sichtbarkeit
|
||
- **AV #6:** Audit-Trail-Default für alle schreibenden Aktionen (Upload, Verknüpfung, Delete)
|
||
- **LP-1:** Tenant-Isolation strikt (RLS + Storage-Pfad)
|
||
- **LP-8:** Offline-Modus für Foto-Upload auf Baustelle (IndexedDB-Queue, Sync-on-Reconnect)
|
||
- **LP-9:** Requirements-pur Spec ohne UI-Layout
|
||
|
||
---
|
||
|
||
## Detail-Spec-Status: DRAFT
|
||
|
||
Erste vollständige Detail-Spec für Modul 23. **Vor Bau:** Verifizierung mit Noah (zusammen mit Pflichtenheft-Sweep) und Abgleich mit Modul 36 (Mobile-Offline-Queue) und Modul 15 (Customer-Portal-Upload-Flow).
|
||
|
||
**Offene Detail-Punkte (nicht-blockierend):**
|
||
|
||
- Konkrete Chunk-Größe und Parallel-Anzahl mit Mobile-Bandbreiten-Tests verifizieren
|
||
- Office-Preview-Worker: LibreOffice-Headless vs. SaaS-Konverter — Trade-off Self-Hosting vs. Skalierung
|
||
- HEIC-Konvertierungs-Library finalisieren (libheif vs. ImageMagick mit HEIC-Plugin)
|
||
- Storage-Limits pro Subscription-Plan in Phase 2 konkret definieren (zusammen mit Modul 28)
|
||
- HR-Hub-Permissions-Sonderfall in Modul 14 konsolidieren (Files an `user`-Entity)
|
||
- Transitive Sichtbarkeit: Performance-Tests mit großen Tenants (10.000+ Files)
|