# 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 ``; Loader/Action/ Resource-Routes unverändert. Browser: `~/ui` Table + Grid-Umschalter (`?view=`) + MIME-/Archiv-Filter + Pagination + Status-Badges + Tags. Upload: Dropzone + Per-Datei-`Progress`-Queue + HEIC-`Alert`. Detail: `Breadcrumbs` + `Card`-Stammdaten + Preview + Scan-`Alert` (fail-closed) + `Tag_Label` + verknüpfte Entitäten + Add-Link-`Dialog` + Delete-`Dialog`; Server-`
`+`intent` beibehalten. Proof (lokal grün): Web-Typecheck exit 0; Render-Tests `screens/files/*.test.tsx` 7/7; Hot-Swap-Drill `fileBrowser.hot-swap.test.ts` 3/3; `verify:i18n`-Parität de/en + hardcoded-Strings-Guard grün; Smoke-Marker `ui.files.browser` erhalten. Visual-Baseline = interim (Harness deferred, DoD 21). Refactor-Nachzug offen: finale Subframe-Optik aus `D-P4` (Doc-Tag `🎨 design-nachzug: offen`, Plane-Label `design-nachzug`). - [ ] Files-Browser/Detail an Davids UI angepasst (finale `D-P4`-Optik über die Screen-Komponenten tauschen) - [ ] REQUIREMENTS/ROADMAP nachgezogen - [ ] Plane-Ticket `AK-P4a` aktualisiert ## Umsetzungs-Notiz ### 2026-06-19 — Backend-Fundament gebaut + verifiziert (Akeshan, Branch `feat/AK-P4a`) Gebaut strikt nach `local/AK-P4a-files-bau-plan.md` (Single Source of Truth). Plattform: Windows 11 (Akeshan), Co-Dev Raffael auf macOS. Reihenfolge wie im Plan empfohlen: §1 → §2 → §4 → §7 → §9 → §8. **Fertig + verifiziert (typecheck/test gruen):** - **§1 Datenmodell** — `prisma/schema/files.prisma` neu (AD-21, eigene Datei, bare String-Scalars, kein Core-Edit). Modelle `File`, `FileEntityLink` (polymorph), `FileUpload`, `FileUploadChunk` + Enums. `createdByPortalUserId` nullable als Customer-Portal-Vorbereitung (DoD 12). Proof: `prisma validate` + `prisma generate` gruen. - **§2 Storage-Pfade** — `packages/storage/src/paths/` (`buildFileStorageKeys`, `buildFilePreviewKey`, `buildUploadChunkKey`, `assertFileKeyBelongsToTenant` als duenne Klammer um das vorhandene `authorizeStorageObjectAccess`). Proof: 5 neue Unit-Tests gruen (`pnpm -F @hivegrid/storage test` → 76 passed). - **§4 Queue-Plumbing** — neue Queue `hivegrid.file-preview` quer durch `names`/`payloads`/ `producers`/`groups`/`index` (`FilePreviewJob`, `buildFilePreviewJob`, retry-opts, group `general`). Proof: `pnpm -F @hivegrid/queue typecheck` + `test` (101 passed; dabei eine vorbestehende Luecke im metrics-snapshot-Test geschlossen: `buildPluginInvokeJob` fehlte). - **§4 Preview-Worker** — `apps/worker/src/jobs/file-preview.ts` (HEIC→JPG / Bild→WebP / PDF→PNG / Text→ready / sonst not_supported, Status-Maschine + Thumbnails), Handler-Registry `[queueNames.filePreview]` + `filePreviewService`-Dependency + `PreviewHandlerError` in `handlers.ts`, Bootstrap-Wiring (general group) in `index.ts`. Render-Libs per dynamischem Import (qdrant-Muster) → Build gruen vor Install; **Aktivierung:** `pnpm add sharp heic-convert pdf-to-png-converter -F @hivegrid/worker`. ClamAV (§5) ist Reuse (`enqueueFileScan` bereits vorhanden). Proof: `pnpm -F @hivegrid/worker typecheck` gruen. - **§7 Permissions** — `files.read_own/read_all/write/delete/admin` in `packages/db/.../permissions-seed.server.ts` (mit expliziten Default-Rollen-Grants, da `files.*` keinen `app.`/`admin.`-Prefix traegt) + in `apps/web/.../DefaultPermissions.ts`. Proof: `pnpm -F @hivegrid/db typecheck` gruen. - **§9 View-Models** — `packages/view-models/src/files/{file-browser,file-detail,file-upload}.vm.ts` (reine Builder, nur i18n-Keys, URLs zeigen auf Proxy-Route, fail-closed bei scanStatus=infected). Proof: `pnpm -F @hivegrid/view-models typecheck` + `test` (13 passed). - **§8 Migration vorbereitet** — `local/AK-P4a-merge-migration.sql`: Trigram-Index + RLS-Policies (forward-only, Inverse-SQL als Kommentar, DO-guarded). AD-21: auf dem Branch nur `db push`; die echte Migration wird beim Merge via `prisma migrate diff` erzeugt und um diesen Anhang ergaenzt. Mit R-P2b (`SET LOCAL app.tenant_id`) abzustimmen. Branch `feat/AK-P4a` enthaelt das gruene Backend-Fundament; die offenen Scheiben sind reine Web-Route-/UI-/Wiring-Arbeit auf diesem Fundament. Kein Plane-Done, solange §3/§6/§11/§12/§13 fehlen. --- ### HANDOFF fuer den naechsten Coding-Agenten (hier weitermachen) **Status:** Backend-Fundament steht und ist gruen (§1, §2, §4, §7, §9, §8-Vorbereitung). Offen ist die Web-Route-/UI-/Wiring-Scheibe. **Single Source of Truth bleibt** `local/AK-P4a-files-bau-plan.md`. **Empfohlene Reihenfolge:** §3 → §6 → §11 (UI/Routen) → §12 (Wiring) → §13 (Tests). **Konventionen, die du einhalten musst (sonst PR-Block):** - **Kommentar-Sprache = Englisch** im Code (`apps/**`, `packages/**`, `prisma/**`); Deutsch nur in Dokus/`.planning/`/`local/`. Siehe `AGENTS.md` §„Kommentar-Sprache" (neu, 2026-06-19). - Drei Anti-Patterns (kein `~/db`/`@prisma/client` in `ui-app`; kein `ui-subframe`-Direktimport in `routes/**`; kein `useLoaderData` in `ui-app`). Loader baut VM, Component ist pur. **§3 Chunked-Upload — neu `apps/web/app/utils/integrations/fileService.server.ts` + Resource-Routes:** - Routing ist **ordnerbasiert** (`apps/web/app/routes.ts` → `createRoutesFromFolders`): neue Dateien in `apps/web/app/routes/app.$tenant/` registrieren sich automatisch; `*.server.ts` wird als Route ignoriert (perfekt fuer den Domain-Service). - Loader-/Action-Bausteine (verifiziert im Repo): `requireAuth({request,params})` aus `~/utils/loaders.middleware`; `getTenantIdFromUrl(params)` aus `~/utils/services/.server/urlService`; `getUserInfo(request)` aus `~/utils/session.server`; Modul-Gate `tenantHasModule({tenantId,userId,moduleKey:"files"})` aus `~/utils/connector/tenantConnector.server`. - Upload selbst: `storeFile`/`putBufferAsFile`/`deleteFile` in `apps/web/app/utils/integrations/storageService.ts`. Magic-Bytes-Allow-List via `resolveAllowList` aus `@hivegrid/storage`. Keys via `@hivegrid/storage` `buildUploadChunkKey`/`buildFileStorageKeys` (schon gebaut, §2). Chunk 5 MB, max 3 parallel, max 500 MB (Konstanten in `file-upload.vm.ts`). - Nach `complete`: `enqueueFileScan({...})` (vorhanden, `fileScanQueue.server.ts`) **und** einen neuen Producer `enqueueFilePreview(...)` (spiegle `fileScanQueue.server.ts`, nutze `buildFilePreviewJob` + `queueNames.filePreview` — beide schon exportiert). **§6 Auth-Proxy `apps/web/app/routes/app.$tenant/media.$fileId.$variant.tsx` (AD-23):** - Loader: `requireAuth` → `getTenantIdFromUrl` → `tenantHasModule("files")` → Sichtbarkeits-Check (§7) → **302 auf kurzlebige signierte Download-URL** (TTL 300 s). Signer-Wiring: pruefe `apps/api/src/storage.ts` (`createStorageSignedDownloadUrl`) bzw. baue web-seitig mit `@aws-sdk/s3-request-presigner` + `createS3SignedUrlAdapter` aus `@hivegrid/storage`. - `scanStatus=infected` → Klartext-Fehler (fail-closed); verweigert → **404, nicht 403**. `STORAGE_PUBLIC_BASE_URL` bleibt leer. **§7-Rest / 404-vs-403 (wichtige Entscheidung):** Die App-Konvention `verifyUserHasPermission(request, perm, tenantId)` (`apps/web/app/utils/helpers/.server/PermissionsService.ts`) **redirectet** auf eine Unauthorized-Seite. Die DoD verlangt **404**. Foundation liefert dafuer `requirePermission`/ `withPermission` (`packages/foundation/src/permissions.ts`), die `CatalogError(foundationErrors.notFound)` = 404 werfen. → Fuer Files-Routen den Foundation-404-Pfad nutzen (oder bei fremder File bewusst 404 werfen). Owner-Check serverseitig: sichtbar wenn `createdByUserId=self` ODER `assignedToUserId=self` ODER es existiert ein lesbarer `FileEntityLink`. Permissions sind schon registriert (`files.read_own/read_all/write/delete/admin`, §7). **§9 ist fertig — nur verdrahten:** `buildFileBrowserVM` / `buildFileDetailVM` / `buildFileUploadVM` aus `@hivegrid/view-models`. Der Loader baut die **Proxy-URLs** (auf die §6-Route) und reicht sie als `thumbnailUrl`/`previewUrl`/`downloadUrl` ins VM — VMs bleiben routing-agnostisch. **§12 Querschnitt-Wiring:** Audit (`auditEvent`/`withAuditMiddleware`), Activity (`logActivity` — **falls der Contract noch nicht existiert: STOP + melden**, keine zweite Activity-Architektur bauen), Search-Registry `packages/search/src/indexed-entities.ts` (Index `hivegrid-files`), Sidebar `apps/web/app/application/sidebar/` (permission-gated, Modul `files`), i18n `files.*`-Keys in `apps/web/public/locales/{de,en}/*.json` (de = Quelle), Mobile-Tab-Bar. **§13 Tests:** Smoke `tests/e2e/files.spec.ts` (Muster `walking-skeleton.spec.ts`), Hot-Swap-Adapter, Visual-Snapshot. VM-Unit-Tests existieren bereits (`packages/view-models/src/files/files.vm.test.ts`). **Deps-Aktivierung (Preview):** `pnpm add sharp heic-convert pdf-to-png-converter -F @hivegrid/worker` (aktuell dynamisch importiert → Build gruen vor Install). **Koordination Raffael:** Live-ClamAV (EICAR fail-closed) braucht `CLAMD_*` aus `AK-INFRA2`; RLS-Reihenfolge mit `R-P2b` (`SET LOCAL app.tenant_id`). **Verifikation pro Scheibe:** `pnpm typecheck` (Web-App) + `pnpm test`; Storage/Queue/Worker/VM-Pakete sind isoliert testbar (`pnpm -F @hivegrid/ test`). Vor Merge: `prisma validate` + `prisma migrate status` + den RLS-Anhang aus `local/AK-P4a-merge-migration.sql` an die generierte Migration anhaengen. --- ### 2026-06-20 — Web-/UI-/Wiring-Scheibe gebaut + verifiziert (Akeshan, Branch `feat/AK-P4a`) Vorher: `git merge origin/main` (Raffaels P2 Auth/RLS) in den Branch gezogen (Merge-Commit `4f6177202`, 3 Konflikte geloest, typecheck gruen). Danach die offenen Scheiben gebaut. **Fertig + verifiziert (typecheck/test gruen pro Paket):** - **§3 Chunked-Upload** — S3-Multipart in `@hivegrid/storage` ergaenzt (`createMultipartUpload`/ `uploadPartCopy`/`completeMultipartUpload`/`abortMultipartUpload`, S3 + Local; Unit-Test `multipart.test.ts`). Domain-Service `apps/web/.../fileService.server.ts` (createUploadSession, storeUploadChunk, completeUpload via UploadPartCopy aus Temp-Chunks, Sichtbarkeit, link/unlink/ archive/reactivate/updateMeta/regeneratePreview/hardDelete, listFilesForBrowser). Producer `filePreviewQueue.server.ts`. Resource-Routes `files.upload.init|.$uploadId.chunk.$index|.complete`. Checksum: client-optional (server-Verify = v2, dokumentiert). Worker-Deps `sharp`/`heic-convert`/ `pdf-to-png-converter` installiert. - **§6 Auth-Proxy (AD-23)** — gemeinsamer SigV4-Signer `@hivegrid/storage` `createSigV4DownloadSigner`, web-seitig `mediaSigning.server.ts` (`createMediaDownloadUrl`, TTL 300 s), Route `media.$fileId.$variant.tsx`: 302 auf signierte URL, fail-closed bei scanStatus != clean/skipped, 404 bei fremder/fehlender File. `STORAGE_PUBLIC_BASE_URL` bleibt leer. (Dev ohne ClamAV: completeUpload setzt scanStatus=skipped, damit Auslieferung lokal funktioniert.) - **§7 Permissions/Sichtbarkeit** — Guard `fileAccess.server.ts` (loadFilesContext, requireFilesPermission; 404 ueber Foundation, locked-State fuer GET-Loader, 404 fuer Write-Actions). read_own-Owner/Link-Check serverseitig. - **§10 Hot-Swap (DoD 20)** — `fileBrowser`-Adapter (`@hivegrid/ui-app`) + Renderer in `ui-subframe` (`renderFileBrowser`) und `ui-mock` (`renderFileBrowserMock`) + Drill-Test gruen. - **§11 Routen** — `files._index` (Browser, server-side-Filter MIME/Archiv, Cursor-Pagination), `files.upload` (Drag&Drop + Multi-Datei-Queue + Per-Datei-Progress, chunked init/chunk/complete), `files.$id` (Vorschau via Proxy, Download/Archiv/Reaktivieren/Loeschen/Vorschau-neu + **FileEntityLink add/remove** mit Rolle). Loader baut VM, Component pur, ErrorBoundary + Empty/Locked-States, i18n. - **§12 Querschnitt** — `files` als echtes Entitlement-Feature (`packages/entitlements` features+blueprint+ plans, Tests angepasst), Such-Index `files` + Registry-Eintrag (`packages/search`), i18n `files.*` de/en in `translations.json` (Parity gruen), Sidebar-Eintrag (permission `files.read_own`, Modul-Gate `files`), Audit (`auditFileEvent`) auf jeder Schreib-Action, Activity (`logFileActivity`, gegen verknuepfte Entitaet, `file_uploaded`). Customer-Portal-Feld `createdByPortalUserId` vorbereitet. - **§13 Tests** — `multipart.test.ts` (Storage), Hot-Swap `fileBrowser.hot-swap.test.ts`, Smoke `tests/e2e/files.spec.ts` (gated), VM-Unit-Tests (vorbestehend). Gruen: storage/queue/worker/ view-models/ui-app/ui-mock/ui-subframe/entitlements/search/i18n + web/api/worker typecheck + Full-Typecheck. **Bewusst offen (deferred):** - **Mobile-Tab-Bar (DoD 11)** — im Repo kein Mobile-Nav-Geruest (PWA-only, AD-17). User-Entscheidung: deferred. - **Visual-Regression / M016 (DoD 21)** — keine Snapshot-Harness vorhanden. User-Entscheidung: deferred. - **Live-ClamAV-Smoke (EICAR)** — `CLAMD_*` ist mesh-only (10.42.0.4), nicht in Dev-Secrets; auf Staging mit Raffael (AK-INFRA2) zu verifizieren. - **Scan-Verdict-Rueckschreibung (§5, OFFEN, wichtig):** Der vorhandene `FileScanJob`-Worker scannt + quarantaeniert, schreibt das Ergebnis aber **nicht** auf `File.scanStatus` zurueck (kein `db.file.update` im Scan-Pfad), und `enqueueFileScan` uebergibt aktuell **keine** `fileId`. Folge: mit `SCAN_QUEUE_ENABLED=true` blieben neue Files auf `scanStatus=pending` haengen und der Auth-Proxy liefert sie (fail-closed) **nicht** aus. Aktuell deshalb in Dev/ohne ClamAV: completeUpload setzt `scanStatus=skipped`. **To-do vor ClamAV-Aktivierung:** `fileId` in den Scan-Job aufnehmen und den Worker-Scan-Handler `File.scanStatus = clean|infected` zurueckschreiben lassen (mit Raffael abstimmen, da der Scan-Worker aus AK-INFRA2/Boilerplate stammt). - **RLS + Merge-Migration (§8)** — Branch nur `db push`; die eine P4-Files-Migration + RLS-Policies beim Merge erzeugen, mit R-P2b (`SET LOCAL app.tenant_id`) abstimmen (`local/AK-P4a-merge-migration.sql`). - **Davids D-P4-Optik** — Baseline-UI steht (funktional, data-ui-id-Marker); visuelle Politur = Dev-Nachzug. - **Kleinere Folge-Items:** Bulk-ZIP-Download und Detail-Breadcrumbs (Backend/Routing tragen, UI-Rest offen). Status: **READY-TO-VERIFY** (Kern-Plattform vollstaendig + gruen; obige Punkte bewusst offen). ### 2026-06-20 (Nachtrag) — Pre-Push-Hooks gruen gemacht (Commit `584a2e8bc`) Der erste `git push` scheiterte an zwei lefthook-Pre-Push-Gates (nicht an GitHub). Behoben: - **typecheck-web:** `fileAudit.server.ts` nutzte `auditEvent`/`logActivity` mit dem rohen Prisma-`db` als Client-Argument (DbClient nicht auf `AuditEventClient` zuweisbar: `actorType string|null`) und importierte `@hivegrid/activity`, das **keine** `apps/web`-Dependency war. - **i18n-Guard (`verify-hardcoded-strings`):** 5x `throw new Response("Not Found"/"Bad Request", …)` loesten `user-facing-response-literal` aus (Baseline 0). **Konventionen fuer den naechsten Agenten (nicht erneut falsch bauen):** - Audit immer ueber **`createAuditEvent` aus `@hivegrid/db/audit-events.server`** schreiben (M001, Hash-Kette), **ohne** Client-Argument — Default ist der db-Singleton. **Nicht** `foundation.auditEvent` mit `db` aufrufen. Gleiches Muster fuer `logActivity` (kein `{ client: db }` uebergeben). - Neue Workspace-Pakete als Dependency in der konsumierenden `package.json` eintragen (+ `pnpm install`). - 4xx aus Loadern/Actions nie als Inline-Literal werfen → Helfer **`notFoundResponse()` / `badRequestResponse()`** aus `fileAccess.server.ts` (Return-Form-`new Response`, vom Guard nicht erfasst; Body ist nie user-facing, ErrorBoundary rendert ServerError). Muster wie `media.$fileId.$variant.tsx`. ### Naechste Schritte bis „Done" (Checkliste fuer den naechsten Agenten) 1. **Scan-Verdict-Rueckschreibung verdrahten** (Blocker vor ClamAV-Prod): `fileId` in `enqueueFileScan` + den Scan-Worker `File.scanStatus = clean|infected` setzen lassen. Mit Raffael (AK-INFRA2) abstimmen, wer den Boilerplate-Scan-Handler erweitert. 2. **Merge-Migration + RLS erzeugen** (Blocker fuer main-Merge): beim Merge **eine** forward-only P4-Files-Migration (Tabellen + `pg_trgm`-Index + RLS-Policies, DO-guarded, Inverse-SQL als Kommentar) aus `local/AK-P4a-merge-migration.sql`; an R-P2b (`SET LOCAL app.tenant_id`, `prisma/rls/tenant-isolation.sql`) ausrichten. `prisma validate` + `prisma migrate status` gruen. 3. **Live-ClamAV-Smoke (EICAR) auf Staging** mit Raffael: Upload EICAR → `scanStatus=infected` → Media-Proxy liefert 404 (fail-closed). 4. **Kleinere Folge-Items abschliessen oder als CR auslagern:** Bulk-ZIP-Download, Detail-Breadcrumbs. 5. **Deferred-DoD vom Reviewer freigeben lassen:** Mobile-Tab-Bar (DoD 11), Visual-Regression/M016 (DoD 21). 6. **Davids D-P4-Delta** abwarten → visuelle Politur als Dev-Nachzug ueber die Adapter/`ui-subframe`-Schicht. Erst wenn 1+2 erledigt und 3–5 abgenommen sind → DoD 100 %, Ticket auf **Done**. ### 2026-06-23 — Blocker 1+2 geschlossen, main reingemergt, lokal gruen (Akeshan) Branch `feat/AK-P4a` auf den aktuellen `main`-Stand gebracht und die beiden Merge-Blocker geschlossen. Reihenfolge: main-Sync → Blocker 1 → Blocker 2 → Verifikation. **Fertig + verifiziert:** - **main-Sync (KI-Pivot AD-26):** `git merge origin/main` (Branch war 8 Commits zurueck inkl. KI-Removal). Konflikte geloest: `apps/worker/package.json` (`gpt-tokenizer` raus = KI-Dep von main entfernt, `heic-convert` behalten), `pnpm-lock.yaml` (main-Version + `pnpm install` reconciled), generierter Prisma-Client (`pnpm db:generate` regeneriert). Branch jetzt **0 hinter main**. Full-Typecheck + betroffene Paket-Typechecks gruen. Commit `a0737b728`. - **Blocker 1 — Scan-Verdict-Rueckschreibung (§5):** `FileScanJob.fileId` (optional) durch `enqueueFileScan` → `completeUpload` (gibt `file.id` mit). Neues Write-back-Seam `apps/worker/src/jobs/file-scan-status.ts` (Prisma, spiegelt file-preview-Service), im general-Group- Bootstrap (`index.ts`) verdrahtet. Der `fileScan`-Handler schreibt `clean|infected` auf `File.scanStatus`, wenn `fileId` + Writer da sind (Legacy-Import-Scans ohne `fileId` unveraendert). Tests: Handler-Write-back (clean/infected) + Skip-ohne-fileId. Commit `7ee0a4135`. - **Blocker 2 — P4-Files-Migration (§8):** `prisma/migrations/20260623160000_p4a_files_platform/` (Tabellen + Enums + Indizes + FKs + `pg_trgm`-Index), via `prisma migrate diff --from-config-datasource --to-schema prisma/schema` erzeugt, auf AK-P4a-Objekte getrimmt (fremder main-Drift NICHT mit reingezogen). Verifiziert: frische Leer-DB `migrate deploy` laeuft durch (P3018-sicher), `prisma validate` + `migrate status` gruen, **kein File*-Drift** mehr. Commit `01ff542a8`. **WICHTIGE KORREKTUR zur RLS (Abweichung vom urspruenglichen Plan):** Die Migration aktiviert **KEINE** RLS. Grund: `FORCE ROW LEVEL SECURITY` + Policy `tenantId = current_setting('app.tenant_id')` laesst **jede** File-Query **ohne** gesetzten GUC **0 Zeilen** zurueckgeben — das **bricht** das Feature (leere Reads, fehlschlagende Writes), es ist NICHT „fail-closed-Isolation". Die File-Web-Loader/Actions **und** die Worker-Write-backs (preview + scan) laufen aktuell **nicht** durch `withTenantRLS()`. Nach R-P2b-Regel darf eine Tabelle erst RLS bekommen, wenn ALLE Zugriffe den GUC setzen. Bis dahin traegt App-Level-`withTenantScope()` (§7) die Isolation. Der RLS-Block bleibt als **Rollout-Artefakt** in `local/AK-P4a-merge-migration.sql` (mit R-P2b abzustimmen, anzuwenden sobald alle File-Zugriffe RLS-gewrappt sind). → **eigenes Folge-Item** (siehe unten). **Lokale Verifikation (gruen):** Full-Typecheck; Paket-Tests storage/queue/worker/view-models/ui-app/ ui-mock/search/entitlements gruen; `@hivegrid/db` 422 passed / 1 failed = **nur** der bekannte Windows-only-Env-Test `isPermissionsSeedDirectExecution` (fileURLToPath, keine Regression); `verify:i18n` gruen; Hot-Swap-Drill (`fileBrowser.hot-swap.test.ts`) gruen. **Nebenbefund (separat, nicht AK-P4a):** Seed brach lokal an `rolesAndPermissionsService.ts` (`description` fehlt) — Fix `description: permission.description ?? permission.name` liegt als ungetrackter Working-Tree-/Stash-Stand; mit User zu klaeren (commit/keep/discard), gehoert nicht in dieses Ticket. **Offen bis Done (selbst machbar + extern):** - [ ] **Push + PR + Merge auf main** (wartet auf User-Go). - [ ] **Staging-Deploy + ClamAV-ENV-Check** — Risiko: AK-INFRA2-Doc setzte `CLAMAV_HOST/PORT`, der Code liest `CLAMD_HOST/PORT` (`scanService.ts`); auf Staging-Worker per SSH verifizieren, sonst No-op-Scan. `SCAN_QUEUE_ENABLED=true` setzen. - [ ] **Live-EICAR-Smoke (Staging)** mit Raffael: infiziert → `scanStatus=infected` → Media-Proxy 404. - [ ] **RLS-Aktivierung auf File*** als Folge-Item (mit R-P2b): erst File-Zugriffe (Web + Worker-Writes) in `withTenantRLS()` wrappen, dann RLS-Block aus `local/AK-P4a-merge-migration.sql` als eigene Migration shippen. - [ ] **Deferred (User-Entscheidung 2026-06-23, bleiben deferred):** DoD 11 Mobile-Tab-Bar (kein Mobile-Nav-Geruest; PWA-only AD-17, mobil spaeter responsiv) · DoD 21 Visual-Regression/M016 (keine Snapshot-Harness im Repo). Reviewer-Freigabe ausstehend → **Ticket bleibt in „Ready for Review"**, NICHT Done. **DoD-Stand:** Kern-Plattform + beide Blocker abgehakt; offen sind Push/PR/Staging-Verifikation (selbst/infra) + RLS-Folge-Item + 2 bewusst deferrte DoD-Punkte → **~85 % done**, Ticket bewusst in **Review** (nicht Done) bis Staging-Verifikation + Reviewer-Freigabe. ### 2026-06-23 (Abend) — auf main gemergt, Build-Pipeline repariert, Staging verifiziert (Akeshan) - **Merge:** `feat/AK-P4a` direkt auf `main` (fast-forward, `c3e30cf10`), gepusht. - **Build-Pipeline repariert (Commit `229cbdce5`, AD-26-Fallout, NICHT AK-P4a-Code):** Der CI-Job „Stage or promote Docker images" schlug seit dem KI-Removal-Pivot auf JEDEM main-Push fehl (`COPY packages/ai|vector-store/package.json … not found`) → seit Commit `300765958` kam kein neues Image mehr auf Staging. Ursache: der Pivot loeschte `packages/ai` + `packages/vector-store`, liess aber 8 `COPY`-Zeilen im root-`Dockerfile` stehen. Diese 8 Zeilen entfernt → Build gruen, Staging zog `229cbdce5`. - **Staging per SSH verifiziert (`staging-1`):** neues Image live; **beide Migrationen** (KI-Removal `20260623103655` + P4 `20260623160000`) angewandt → `File`/`FileEntityLink`/`FileUpload`/ `FileUploadChunk` + `FileScanStatus`-Enum existieren; **clamd** aus dem general-Worker erreichbar (`PING→PONG`, EICAR-Stream `Eicar-Test-Signature FOUND`); `CLAMAV_HOST=10.42.0.4`/`CLAMAV_PORT=3310` korrekt (Code liest `CLAMAV_*`, NICHT `CLAMD_*` — frueherer Verdacht war falsch); `SCAN_QUEUE_ENABLED=true` via Coolify auf Web + general-Worker gesetzt; Login + Tenant-Routing (`//...`) + die Files-Routen sind erreichbar und korrekt gegated. - **Live-EICAR-Upload bewusst NICHT abgeschlossen (User-Entscheidung „Option 3", 2026-06-23):** Der Upload-`init` liefert **404 = korrektes fail-closed** — `tenantHasModule("files")` ist fuer die Demo-Tenants false (das `files`-Modul ist in keinem Plan/Entitlement; `SubscriptionFeature` auf Staging leer, der Post-Deploy-Seed lief nicht). Das ist **kein Code-Bug**, sondern fehlende Entitlement-Konfig — und zugleich ein positiver Beweis, dass das Modul-/Permission-Gating greift. Der finale EICAR-End-to-End-Beweis (`scanStatus=infected` → Media-404) wird **nachgeholt, sobald `files` regulaer in einem Plan ist** (oder per `TenantFeatureOverride featureKey='files' override='enabled'`). Bis dahin: Scan-Pipeline (clamd/Worker/Schema/scan-enabled) ist live bestaetigt, Write-back ist unit-getestet. - **Infra-Nebenbefund (eigenes Ticket, kein AK-P4a-Code):** Coolify fuhr bei diesem Deploy **weder** den Pre-Deploy-`prisma migrate deploy` **noch** den Post-Deploy-Seed-Hook aus — beide Migrationen musste ich manuell nachziehen, der Seed lief gar nicht. Trifft jeden HiveGrid-Deploy → Coolify- Pre/Post-Deploy-Command fuer das HiveGrid-Projekt pruefen. **Noch offen (Stand 2026-06-23 Abend):** - [ ] **RLS-Aktivierung auf `File*`** (Folge-Item, mit R-P2b) — siehe eigener Abschnitt unten. - [ ] **Finaler Live-EICAR-Beweis** — nachholen, sobald `files` in einem Plan/Entitlement aktiv ist. - [x] **Coolify Pre/Post-Deploy-Hooks** (Migrate + Seed) reparieren — erledigt 2026-07-03, gelöst durch Migrate-on-Boot im Entrypoint statt Hook-Reparatur (siehe Notiz unten). - [ ] **Deferred DoD 11 (Mobile-Tab-Bar) + DoD 21 (Visual-Regression)** — bleiben deferred. - Ticket bleibt **„Ready for Review"** (nicht Done). ### 2026-06-24 — RLS-Vorbereitung „Teil A" gebaut (Files RLS-ready, non-breaking) (Akeshan) Kontext-Klärung vorweg: R-P2b hat die RLS-**Maschine** gebaut und bewiesen, aber RLS auf **keiner** Daten-Tabelle scharfgeschaltet (eigene Plane-Kommentare: *„deliberates Rollout-Artefakt, nicht im Auto-Migrations-Pfad"*, *„app-weiter RLS-Rollout läuft separat mit P5"*; Ticket steht auf *In Progress*). RLS „beißt" erst, wenn (1) **jeder** File-Zugriff den Tenant-Kontext setzt **und** (2) die App als restricted Rolle `hivegrid_app` (NOBYPASSRLS) verbindet. Beides fehlte → vorzeitiges Scharfschalten **bricht** Files (leere Reads, fehlschlagende Writes). Mit User abgestimmt: in diesem Durchgang nur **Teil A** (Code RLS-ready machen, non-breaking); das Scharfschalten ist Teil B = der org-weite **P5-Cutover** (Raffael/R-P2b). **Fertig + verifiziert:** - **Web** — alle File-DB-Zugriffe in `fileService.server.ts` laufen jetzt durch `withTenantRLS()` (R-P2b-Wrapper). Regeln eingehalten: langsame I/O (S3/Queue) bleibt **außerhalb** der Transaktion; keine verschachtelten Transaktionen (interne `*WithTx(tx, …)`-Helfer für `isFileVisible` / `getVisibleFileOrThrow` / `getVisibleFileWithLinks`). Funktional unverändert (Wrapper ist ein No-op, solange keine Policy aktiv ist). `db`-Singleton-Import entfernt. Web-Typecheck + Lint grün. - **Worker** — neuer client-parametrisierter Helfer `apps/worker/src/db/tenantRls.ts` (spiegelt R-P2b); die beiden Write-backs `jobs/file-preview.ts` (writeStatus) und `jobs/file-scan-status.ts` (recordVerdict) setzen vor `file.update`/`updateMany` den Tenant-GUC (Legacy-Scans ohne `tenantId` unverändert direkter Pfad). Worker-Typecheck + Lint grün; Worker-Suite `handlers.test.ts` 76/76 grün. - **Gate-Beweis (neu)** — `apps/web/app/utils/db/.server/rls-file-isolation.integration.test.ts` (gespiegelt an R-P2bs Test, gated auf `RLS_TEST_DATABASE_URL`). **7/7 grün** gegen echte Postgres (pgvector pg16) mit angewandtem File-RLS-Block: Kontext A sieht nur A-Files; Cross-Tenant = 0; ohne Kontext = 0; `WITH CHECK` blockt Fremd-Insert; eigener Insert+Read ok; `FileEntityLink` ebenso isoliert. Ohne die Env-Var skippt der Block sauber (normale Suite bleibt grün). - **Aktivierungs-Artefakt jetzt getrackt** — den RLS-Block aus dem gitignoreten `local/AK-P4a-merge-migration.sql` als **`prisma/rls/file-isolation.sql`** ins Repo gezogen (parallel zu R-P2bs getracktem `prisma/rls/tenant-isolation.sql`), damit Raffael ihn für Teil B sieht und der Gate-Test in CI eine getrackte Datei liest. Dabei die fehlenden `GRANT SELECT/INSERT/UPDATE/DELETE … TO hivegrid_app` auf die vier File-Tabellen ergänzt (R-P2b grantet analog auf `TenantUser`), Inverse-SQL (REVOKE + NO FORCE) nachgezogen, Header auf „Teil A erledigt / Teil B = P5-Cutover" aktualisiert. **Damit ist Files RLS-ready:** der P5-Cutover wird ein reiner Schalter (Migration aktivieren + Runtime-Rolle `hivegrid_app`), ohne weitere Files-Code-Änderung — bewiesen durch den Gate-Test. **Weiterhin offen (Teil B / extern, unverändert):** Policy-Migration aktivieren + DB-Rollenwechsel + Staging-Cutover (org-weit, Raffael/R-P2b) · finaler Live-EICAR-Beweis (entitlement-gated) · Coolify Pre/Post-Deploy-Hooks (Infra) · deferred DoD 11 + DoD 21. Ticket bleibt **„Ready for Review"**. ### 2026-07-03 — Coolify-Deploy-Migrate-Problem gelöst: Migrate-on-Boot im Entrypoint (Akeshan) Der Infra-Nebenbefund vom 23.06. („Coolify fuhr weder Pre-Deploy-Migrate noch Post-Deploy-Seed aus") ist geschlossen — **gelöst durch Ersetzen statt Reparieren** des Hooks (Branch `akeshan/migrate-on-boot`). **Root Cause (3 Ebenen):** (1) Coolifys `pre/post_deployment_command` feuerte für unsere Docker-Image-Apps (ADR-005, build-once/deploy-via-pull) nachweislich nie — bestätigt am 20.06. (Prod-Promote, `docs/ops/prod-rollout-hivegrid.md`), 23.06. (Staging) und 2× am 03.07. (Parity-Migration + MCP-Fix, beide manuell nachgezogen). (2) Konzeptioneller Zusatzfehler: der pre-deploy-Hook liefe im **alten** Container, in dem die neuen Migration-Files gar nicht existieren — selbst ein reparierter Hook wäre immer einen Deploy hinterher. (3) Das Deploy-Gate war blind: Health-Wait pollt `/healthz` (keine DB-Abfrage) → Deploy grün trotz veraltetem Schema. **Fix:** Migrationen + Seed laufen jetzt env-gated im Web-Entrypoint (`start.sh`, `set -e`): `MIGRATE_ON_BOOT=true` → `pnpm exec prisma migrate deploy --config prisma.config.ts` vor dem Serverstart (immer die richtige Image-Version, Prisma-Advisory-Lock gegen Parallel-Starts); `SEED_ON_BOOT=true` → guarded Production-Seed. Fehlschlag = Container startet nicht = Health-Wait wird **rot statt still grün** — das ist der eigentliche Gate-Fix. `deploy.yml` leert die toten Hook-Slots explizit und upsertet die Boot-Flags per neuem `scripts/coolify-deploy.mjs set-envs` (Staging zusätzlich `SEED_DEMO_DATA`/`ALLOW_STAGING_DEMO_SEED`; Production ohne Demo-Flags). Web-`HEALTHCHECK` `start-period` 20s→120s (Migrate-Zeit). Rollback: Flags auf `false` + Redeploy. **Verankert gegen Rückbau:** `verify-docker-baseline.mjs` erzwingt jetzt `set -e` + beide gated Blöcke in `start.sh`; `verify-gitea-deploy-workflow.mjs` erzwingt geleerte Hook-Slots + Boot-Flag- Upsert (Staging und Production, Demo-Flags in Prod verboten). Doku: `docs/deployment.md` (Slots-Absatz ersetzt), `infra/LESSONS.md` (neue Lesson im infra-Repo). **Nachtrag 2026-07-04 (User-OK zum Vorschlag):** Der PR-CI-Smoke (`scripts/docker-web-runtime-smoke.sh`, Job `docker-smoke`) migriert/seedet nicht mehr per separatem One-off-Container, sondern bootet den Web-Container selbst mit `MIGRATE_ON_BOOT=true`/`SEED_ON_BOOT=true` gegen eine leere Postgres und asserted die `[boot]`-Banner in den Logs. Damit probt jeder PR exakt den Staging-Bootweg; Health-Fenster auf 600s erweitert (Boot enthält jetzt die volle Migrationskette), Fail-fast wenn der Container während des Boots stirbt. ### 2026-07-05 — Interim-UI aus `~/ui` gebaut (AD-28), lokal grün (Akeshan) Die bislang offene „Davids Optik"-Scheibe als **Interim-UI** geschlossen (AD-28 / `.planning/INTERIM-UI-PLAYBOOK.md` + `INTERIM-UI-DESIGN-STANDARDS.md`). Die 3 Files-Screens sind aus den gesyncten `~/ui`-Subframe-Components neu komponiert — VM als Prop, kein handgeschriebenes Tailwind für Spacing/Höhen, Davids Layout-/Komponenten-/State-Standards befolgt. **Backend/Loader/Action/Resource-Routes + Hot-Swap-Adapter unverändert** (kein neues Backend, Ticket-Treue). **Gebaut:** - `apps/web/app/components/screens/files/FilesBrowserPage.tsx` — `~/ui` `Table` + `ToggleGroup`-Umschalter (Table/Grid, `?view=`) + MIME-Filter (`Select`) + Archiv-`Checkbox` + `nextCursor`-Pagination + Status-`BadgeFeedback` (Preview/Scan) + `Tag_Label`. Grid-View = `Card`-Raster mit Thumbnails. Empty-State inline. - `apps/web/app/components/screens/files/FileUploadPage.tsx` — Dropzone (custom Drop-Target, i18n-Copy aus VM; das `~/ui`-`FileUpload` bringt hartkodierte EN-Copy mit → bewusst nicht genutzt) + Per-Datei-`Progress`-Queue + HEIC-`Alert`. Client-Chunked-Pipeline bleibt in der Route und wird als `items`/`onFiles` reingereicht. - `apps/web/app/components/screens/files/FileDetailPage.tsx` — `Breadcrumbs` + `Card`-Stammdaten + Preview + Scan-`Alert` (fail-closed) + `Tag_Label` + verknüpfte Entitäten + **Add-Link-`Dialog`** (echter Dialog, S 560) + **Delete-`Dialog`** (XS 420). Aktionen bleiben Server-``+`intent` (`~/ui` `Button` `type=submit name=intent`). Alle `data-ui-id`/`data-row-id`/`data-link-id`/`data-status` erhalten. - Routen `files._index`/`files.upload`/`files.$id` rendern nur noch ``; Browser-Loader liest zusätzlich `?view=`; `onApply` navigiert server-side (useNavigate). i18n `files.*` de/en ergänzt (Parität grün). - Render-Tests je Screen: `apps/web/app/components/screens/files/*.test.tsx`. **Verifikation (lokal grün):** Web-Typecheck exit 0 · Render-Tests 7/7 · Hot-Swap-Drill `fileBrowser.hot-swap.test.ts` 3/3 (DoD 20, Adapter unberührt) · `verify:i18n` (i18n-Parität de/en + hardcoded-Strings-Guard) grün · eslint-staged (0-Warnings) grün · Smoke-Marker `ui.files.browser` erhalten (D19). **Deferred wie gehabt:** Visual-Regression/M016 (keine Snapshot-Harness, DoD 21) → Interim-Baseline; Mobile-Tab-Bar (DoD 11, PWA-only AD-17). **Nicht gebaut (kein Backend, getrackter Follow-up):** Volltext-/Entity-/Tag-/Assignee- Filter + Bulk-ZIP-UI (brauchen Loader-/Service-Erweiterung). **%-Done-Stand:** Der selbst-machbare Optik-Rest ist geschlossen; Interim-DoD B6–10 / D18–20 grün. Damit ~85 % → **~92 % done**. Offen (extern/deferred, nach AD-28 **nicht** Done-blockierend): RLS-Teil-B (P5-Cutover, Raffael) · finaler Live-EICAR (entitlement) · DoD 11 + DoD 21 (deferred) · finale `D-P4`-Optik (`design-nachzug`) · Bulk-ZIP-/erweiterte-Filter-Follow-up. **Selbst-machbar offen: 0.** Push/PR + Plane-Label + Done erst nach User-Freigabe. ### 2026-07-05 (Teil 2) — Staging-End-to-End-Beweis erbracht (Akeshan) Nach dem systemischen Routing-Fix (v1-Adapter erkennt v2-flat `_index`, Branch `akeshan/fix-files-nav-featurekey`) sind die Tenant-Modul-Routen an ihrer kanonischen URL erreichbar. Damit den bis dahin nur unit-/komponenten- getesteten Kern **live auf Staging** (`demo-pro-crm`, `files`-Entitlement aktiv) durchgestochen — via authentifizierter In-Page-`fetch` gegen die echten Deploy-Endpoints: - **Chunked Upload:** JPG init→chunk→complete = 200, File-Row erzeugt. - **Preview-State-Machine:** JPG → `previewStatus=ready` (WebP), Detail-Preview rendert über den Auth-Proxy. - **Auth-Proxy (AD-23):** `original` + `preview` → 302 auf kurzlebige signierte S3-URL (kein public-read). - **ClamAV fail-closed:** EICAR hochgeladen → clamd erkennt → **Write-back `scanStatus=infected`** (DB-belegt) → Media-Proxy **404** für beide Varianten → UI-Banner „vom Virenscan blockiert". Der bislang nur unit-getestete Write-back ist damit **live bewiesen**. - **HEIC→JPG (Pflicht) + PDF→PNG:** mit echten Dateien (iPhone-HEIC 1,72 MB, PDF) direkt auf dem Staging-Worker über exakt die Preview-Job-Libs (`heic-convert` JPEG q0.85 → JPG 1536×2048; `pdf-to-png-converter` → PNG 1190×1684; `sharp`-Resize 2048/480). (Voller HTTP-Upload der 1,72-MB-HEIC ging nicht über den Browser — Tooling-Limit `file_upload`, kein Produktfehler; der Konvertierungs-Zweig ist damit dennoch auf Staging belegt.) - **Nav-Regression:** contacts/tasks/notifications/search/email-marketing/settings/dashboard alle 200 OK. - Beweis-GIF + Screenshots; alle Test-Dateien danach hart gelöscht (DB `count=0`). ### 2026-07-05 (Teil 3) — Bulk-ZIP + erweiterte Browser-Filter gebaut (Akeshan) Die beiden bis dahin als Follow-up geführten DoD-Punkte auf User-Wunsch direkt umgesetzt (nicht mehr CR): **Erweiterte Filter (Entität / Tags / Verantwortlicher):** `listFilesForBrowser` um den `entityType`-Filter (`links.some`) ergänzt; neuer `listFileFilterOptions()` liefert Optionslisten (distinct Entity-Types aus `FileEntityLink`, distinct Tags über die jüngsten Tenant-Files, aktive Members via `getTenantUsers`). Loader liest `entity`/`tag`/`assignee`-Params + reicht sie in Service + VM; VM (`FileBrowserData`) trägt jetzt `filterOptions` (rückwärtskompatibel, Default leer). Screen rendert drei zusätzliche `~/ui`-`Select` (nur wenn Optionen vorhanden), server-side-navigierend wie MIME/Archiv. i18n `files.browser.filter.{entity,tag,assignee}` + `files.entityType.*` (de=Quelle, Parität grün). **Bulk-ZIP-Download:** Service `collectFilesForZip()` (tenant-scoped, **fail-closed**: nur sichtbare + `scanStatus∈{clean,skipped}`-Files; infiziert/unsichtbar/über-Cap werden still verworfen; Bytes via signierte URLs, Caps 50 Files / 200 MB, De-Dupe der Entry-Namen). Neue Resource-Route `app.$tenant/files.bulk-zip.tsx` (POST `fileIds[]` → `fflate.zipSync` → `application/zip` Attachment). Screen: Checkbox-Spalte + Select-All in der Table-View + Bulk-Leiste (Native-``-POST auf die absolute Bulk-URL). Neue Dep `fflate` in `apps/web`. **Reachability-Bugfix (Interim-UI):** Der Upload-CTA nutzte einen relativen `href="upload"`, der von `//files` auf `//upload` auflöste → **404**. Ebenso die Detail-Breadcrumb (`filesHref=".."` → `//` Dashboard). Beide auf absolute, im Loader gebaute Pfade (`//files/upload` bzw. `//files`) umgestellt (konsistent mit `bulkZipAction`). Web-Typecheck grün. (Auf Staging beim Deploy der Teil-3-Änderungen wirksam.) **Nachtrag — Tag-Editor (fehlte, blockierte den Tag-Filter):** Tags wurden im Detail nur *angezeigt*, es gab keine UI zum Setzen → der neue Tag-Filter blieb ohne Datenquelle. Jetzt: neue `updateMeta`-Intent in der Detail-Route (Tags kommagetrennt, trim/dedupe/cap 30, `files.write`-gated, auditiert via `file.updated`) + Tag-Editor auf der Detail-Seite (`~/ui`-`TextInput` mit vorbefülltem Wert + Speichern, nur bei `canWrite`). `updateFileMeta` war im Service vorhanden, nur nicht verdrahtet. Detail-Render-Tests 4/4 (2 neue), Typecheck/ i18n/Lint grün. **Verifikation (lokal grün):** Web-Typecheck exit 0 · Screen-Render-Tests **10/10** (inkl. neue Filter- + Bulk-Selection-Tests) · Hot-Swap-Drill `fileBrowser.hot-swap.test.ts` **41/41** (DoD 20, Adapter unberührt) · `verify:i18n` (Parität + hardcoded-Guard) **exit 0** · `eslint-staged` **exit 0** · view-models **181/181**. **Damit sind die zwei letzten funktionalen DoD-Lücken geschlossen.** Klärung zu den bislang als „blockierend" geführten Punkten (aus `R-P2b` gelesen): **RLS blockiert AK-P4a nicht** — R-P2b hat die RLS-Maschine bewiesen (Gate 6/6), das **Scharfschalten ist explizit P5+-Scope** („nicht R-P2b-Scope, läuft mit P5+"); AK-P4a ist RLS-**ready** (Teil A, Gate `rls-file-isolation` 7/7). Ebenso sind **DoD 11 (Mobile-Tab-Bar)** und **DoD 21 (Visual-Regression)** nicht „mal eben" machbar — beide bräuchten neue Plattform-Infrastruktur (app-weites Mobile-Nav-Gerüst bzw. M016-Snapshot-Harness), die es im Repo nicht gibt → bleiben bewusst deferred (AD-28, nicht Done-blockierend). **%-Done-Stand:** ~92 % → **~98 % done**. **Selbst-machbar offen: 0.** Rest-Offen (nicht Done-blockierend): finale `D-P4`-Optik (`design-nachzug`, David) · RLS-Teil-B (P5-Cutover, Raffael) · deferred DoD 11 + 21. **Noch zu tun vor Done:** die Teil-3-Features (Bulk-ZIP + Filter) sind lokal grün, aber **noch nicht committed/deployed** → Staging-Verifikation + Commit/Push/Merge + Plane-Label + Done stehen unter User-Freigabe aus. ### 2026-07-16 — Stand-Audit (/audit-ticket): Done bestätigt, Doku-Drift korrigiert (Akeshan) Drei-Quellen-Audit (Ticket-Doc vs. Plane vs. realer Code auf `main`) über alle 8 DoD-Punkte — **alle 8 im Code verifiziert erfüllt** (Proof-Pfade geprüft und geöffnet, nicht nur gegrept): Upload-Kette `fileService.server.ts` + Resource-Routes, Preview-Worker `file-preview.ts` (HEIC/WebP/PNG + Status-Maschine), Scan-Write-back `file-scan-status.ts` (Preview wird bewusst erst **nach** clean-Verdict enqueued), Auth-Proxy `media.$fileId.$variant.tsx` (302 signiert, 404-statt-403, fail-closed), Bulk-ZIP (`collectFilesForZip`, Caps 50/200 MB) + alle vier Browser-Filter, `FileEntityLink` + `createdByPortalUserId`, Querschnitt-Wiring (Sidebar/Search/ Entitlements/Audit/Activity/i18n de+en), Hot-Swap, Smoke `tests/e2e/files.spec.ts`. **AK-P4a: 8/8 DoD = 100 % — Done ist gerechtfertigt.** **Korrekturen (Doku-Drift, kein Code-Befund):** - Die Schlussnote vom 05.07. („Teil-3 noch nicht committed/deployed") ist überholt: Bulk-ZIP + erweiterte Filter sind seit **PR #43** (Commit `5fbca27fa`, Merge `ae60c6f2d`) auf `main`. - **RLS Teil B ist geschlossen:** Der app-weite Cutover `20260713190000_appwide_rls_cutover` (Staging scharf seit 14.07.) setzt ENABLE + FORCE ROW LEVEL SECURITY + Policies auf **allen** File-Tabellen (`File`, `FileEntityLink`, `FileUpload`, `FileUploadChunk`, `FileUploadProgress`). Der frühere „P5-Cutover offen (Raffael)"-Vermerk in DoD 1 und den Notizen ist damit erledigt. - **`scanStatus=skipped` existiert nicht mehr:** `fileScanPolicy.ts` liefert nur noch `scanStatus === "clean"` aus (Auslieferung + Bulk-ZIP). Strenger und korrekt fail-closed; ältere Notizen mit „clean|skipped" beschreiben den Alt-Stand. **Weiterhin offen (nicht Done-blockierend):** Staging-Live-Check von Bulk-ZIP + den drei neuen Filtern (im Plane-Done-Kommentar vom 05.07. zugesagt, bislang ohne Proof) · finale `D-P4`-Optik (`design-nachzug`) · deferred DoD 11 (Mobile-Tab-Bar) + DoD 21 (Visual-Regression, Interim-Baseline). ### 2026-07-16 (Abend) — Staging-Live-Check Bulk-ZIP + Filter erbracht (Akeshan) Der im Done-Kommentar vom 05.07. zugesagte Staging-Beweis ist nachgeholt (Browser-Session `demo-pro-crm`, eingeloggt, 16.07. ~22:00): - **Tag-Filter** `?tag=Rechnung` → nur Rechnungs-PDFs, server-side navigiert. - **Entity-Filter** `?entity=project` kombiniert mit Tag → gefilterte Liste. - **Verantwortlich-Filter** `?assignee=…` → greift; 0-Treffer-Fall zeigt den Klartext-Empty-State („Noch keine Dateien" + Hochladen-CTA). - **Bulk-ZIP**: authentifizierter In-Page-POST auf `files/bulk-zip` mit 2 `fileIds` → **HTTP 200, `application/zip`, PK-Magic-Bytes, 1194 Bytes**. - Tabelle/Raster-Umschalter, Checkbox-Spalte, Status-Badges rendern korrekt. Damit ist der letzte offene Verifikations-Punkt aus dem Plane-Kommentar erbracht. AK-P4a bleibt **Done, 8/8 DoD**. ### 2026-07-29 — Pilot-Readiness-Nachzug: Chunk-Upload-CSRF gehärtet (Raffael) Die drei session-authentifizierten Resource-Actions `files.upload.init`, `files.upload.$uploadId.chunk.$index` und `files.upload.$uploadId.complete` validieren jetzt den Session-CSRF-Token header-only, bevor JSON beziehungsweise rohe Chunk-Bytes gelesen und Upload-Zustand mutiert wird. Der gemeinsame Browser-Client sendet den Token bei allen drei Requests; damit bleiben die abhängigen Chat- und Signatur-Flows kompatibel. Proof: 10/10 fokussierte Route-/Client-Tests, betroffene ESLint-Prüfung und Web-Typecheck grün. **AK-P4a bleibt 8/8 DoD = 100 % done.**