Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/AK-P4a.md
T

620 lines
48 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 `<XPage vm={} … />`; 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-`<form method=post>`+`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/<pkg> 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 (`/<tenant>/...`) + 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-`<form method=post>`+`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 `<XPage vm={} … />`; 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-`<form>`-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
`/<tenant>/files` auf `/<tenant>/upload` auflöste → **404**. Ebenso die Detail-Breadcrumb (`filesHref=".."`
→ `/<tenant>/` Dashboard). Beide auf absolute, im Loader gebaute Pfade (`/<tenant>/files/upload` bzw.
`/<tenant>/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.**