# AK-P4a · P4 Files (chunked Upload, HEIC→JPG, ClamAV)
| | |
|---|---|
| **Typ** | Dev (Code) |
| **Owner** | Akeshan |
| **Phase** | P4 — Files & Tasks |
| **Cycle/Fenster** | W1 — Fundament & Identität · fällig 2026-06-19 · Gate W1 |
| **Status** | Done (2026-07-05) — Dev-DoD 100 %; design-nachzug offen (nicht Done-blockierend, AD-28) |
**🎨 design-nachzug: offen** (seit 2026-07-05) — Interim-UI aus `~/ui` steht; finale Subframe-Optik aus `D-P4` ausstehend.
## Abhängigkeiten & Parallelität
- **Blocked by:** `AK-INFRA2` (ClamAV per ENV), `EXT-06` (Hetzner-S3 + Token + DEK-Master-Key)
- **Blocks:** `AK-P4b` (Tasks + EntityLink), `R-P6` (File-Links am CRM)
- **Läuft parallel zu:** Raffaels `R-P2a`/`R-P2b` (Auth/RLS) — **erstes echtes Code-Paar P2‖P4.** Disjunkte Domänen, eigene `prisma/schema/files.prisma` → **kein Schema-Konflikt** (AD-21). Files braucht RLS-Kontext aus P2 (nutzt das `app.tenant_id`-Muster, aber baut keine Identitäts-Tabellen).
- **Konflikt-Risiko:** keines auf Schema-Ebene; nur Sidebar additiv.
> **EXT-06-Stand (2026-06-17):** Staging-S3 steht schon — Bucket `hivegrid-staging-media`
> (Hetzner `fsn1`, **privat**) + `STORAGE_*` auf web/api/worker gesetzt, DEK via `CRYPTO_SECRET`.
> Du kannst direkt gegen den Staging-Bucket testen. Prod-Bucket folgt (Owner Raffael, Limit erhöht).
> **Media-Auslieferung ist auf Weg B entschieden → siehe AD-23 / DoD / Technische Bausteine unten.**
## Was wir bauen
Das **Files-Plattform-Primitive**: chunked Upload (TUS) mit **RLS auf Storage-Pfaden** (Hetzner S3-kompatibel, ADR-009), Preview-Generierung (PDF→PNG, Bild→WebP, **HEIC→JPG — Pflicht** für iPhone-Monteur-Fotos) mit Status (pending/generating/ready/failed/not_supported) + Klartext-Fallback, **ClamAV-Virenscan**, Permissions/Sharing, Tags, Archiv-Flag, Bulk-ZIP, und das Anhängen an jede Entität über `FileEntityLink` (polymorph). Customer-Portal-Upload ist vorbereitet.
## Benötigte Screens (Backend bedient — Design liefert `D-P4` aus `D-D0a`/`D-D0b`)
| Screen [Route] | Kern-Inhalt | Liefert (Design) |
|---|---|---|
| Files-Browser [`/files`] | Tabelle/Grid-Umschalter, Filter (Entität/MIME/Tags/Verantwortlicher), Bulk (Tag/Verknüpfen/Archiv/ZIP), Inline-Schnell-Vorschau, Archiviert-Toggle | `D-P4` (A2) |
| Upload-View + Dropzone [`/files/upload`] | Drag&Drop, Multi-Datei-Queue mit Per-Datei-Fortschritt, Fehler+Retry, HEIC-Klartext-Hinweis | `D-P4` (A4) |
| File-Detail [`/files/:id`] | Stammdaten, Vorschau (Bild-Zoom/PDF; HEIC→JPG) + not_supported-Fallback, Tags, Notizen, verknüpfte Entitäten mit Rolle, Activity, Download/Ersetzen/Archiv | `D-P4` (A3) |
*Eingebettet: Files-Browser vorgefiltert in Entity-Detail-Views (R-P6 ff.). Davids P4-Screens über `D-P4` (Compose aus D0).*
## Definition of Done
- [x] **Chunked Upload (TUS)** (Staging-e2e bewiesen) + **RLS auf Storage-Pfaden** — Code RLS-ready (Teil A, Gate 7/7); Teil B **erledigt** durch app-weiten Cutover `20260713190000_appwide_rls_cutover` (scharf seit 14.07., alle File*-Tabellen)
- [x] **Preview** PDF→PNG / Bild→WebP / **HEIC→JPG (Pflicht!)** mit Status-Maschine + Klartext-Fallback — alle drei Zweige auf Staging mit echten Dateien bewiesen (2026-07-05)
- [x] **ClamAV-Scan** beim Upload — Live-EICAR fail-closed auf Staging bewiesen (`scanStatus=infected` → Media-404)
- [x] Permissions/Sharing + Tags + Archiv-Flag + **Bulk-ZIP** (Bulk-ZIP 2026-07-05 gebaut, lokal grün)
- [x] **Auth-Proxy-Route für Medien-Auslieferung** (AD-23) — privater Bucket, `publicUrl` → Proxy, **kein public-read** (Staging: 302 auf signierte URL)
- [x] **`FileEntityLink`** (polymorph) an jede Entität + Rollen-Label; Customer-Portal-Upload vorbereitet
- [x] Files-Browser server-side-Filter (**Entität/MIME-Gruppe/Tags/Verantwortlicher** — alle vier, 2026-07-05), Tabelle/Grid-Umschalter
- [x] *(→ v2)* Versionierung/Office-/Video-Previews/Resume-Upload/OCR ausgeschlossen (korrekt out-of-scope)
## Technische Bausteine
- **Entities** (eigene `prisma/schema/files.prisma`): `File` (display_name, mime_type, size, storage_key, checksum, preview_status, assigned_to, source; `is_demo_data`; Soft-Delete), `FileChunk`/`FileUploadProgress` (upload_id, chunk_index, received_chunks, expires_at 24h), **`FileEntityLink`** (file_id + entity_type + entity_id + link_role, polymorph — Cross-Cutting). `FileVersion` = **v2** (nicht bauen). `core.prisma` nur für Tenant/User-Relationen berühren (AD-21).
- **RLS** auf `File`/`FileEntityLink` + Storage-Pfad-Scoping (tenant-isoliert).
- **Konnektor** `tenantHasModule('files')` (Sidebar + Routes + Actions gated).
- ClamAV + S3 per ENV (aus AK-INFRA2 / EXT-06).
- **Media-Auslieferung (AD-23, beschlossen 2026-06-17):** Bucket bleibt **privat**, **kein public-read**. Medien werden über eine **authentifizierte Proxy-Route** ausgeliefert (Session + `withTenantScope()` + `withPermission()`), die aus dem privaten Bucket streamt bzw. auf eine kurzlebige signierte Download-URL redirected. Der `publicUrl`-Pfad in `RowHelper`/`MediaHelper`/`ApiHelper` (`publicUrl ?? file`) muss auf diese Route zeigen, **nicht** auf eine public-S3-URL; `STORAGE_PUBLIC_BASE_URL` bleibt leer. Genuin öffentliche Assets (E-Mail-Bilder, öffentliche Formular-/Booking-/Portal-Seiten, Branding-Logos) → signierte URLs mit TTL **oder** separater `public/`-Prefix mit eng begrenztem public-read (pro Asset-Typ entscheiden). **DSGVO-Export-Artefakte** folgen seit 2026-07-20 dem strengeren SSE-C-Vertrag: authentifizierter `200`-App-Proxy, kein signierter Redirect und kein direkter Zugriff ohne Customer-Key.
- `is_demo_data` auf seedbaren Demo-Files (Onboarding-Provisioning).
## Quellen (granular)
- `ENTITY-MODEL.md` → **Domäne 3: Files & Tasks** (File, FileChunk, FileUploadProgress, **FileEntityLink** polymorph) + Cross-Cutting-Tabelle
- `REQUIREMENTS.md` → `REQ-files-datenmodell`, `REQ-files-upload-preview`
- `ROADMAP.md` → Phase 4 · Milestones: (M052/M053/M054 gedünnt/M055 gedünnt)
- `designer-briefs/P04-files-tasks.md`
- `docs/ARCHITECTURE-DECISIONS.md` → **AD-23** (Media-Auslieferung: privater Bucket + Auth-Proxy, kein public-read) · AD-8 (Verschlüsselung)
## Dev-Nachzug (nach Davids `D-P4`-Delta)
**Interim-UI (Vorschau, Stand 2026-07-05):** Die 3 Screens sind aus `~/ui` neu gebaut (AD-28,
`.planning/INTERIM-UI-PLAYBOOK.md`) — VM als Prop, kein handgeschriebenes Tailwind für Spacing/Höhen,
Davids Design-Standards befolgt:
`apps/web/app/components/screens/files/{FilesBrowserPage,FileUploadPage,FileDetailPage}.tsx`.
Die Routen (`files._index`/`files.upload`/`files.$id`) rendern nur noch `