48 KiB
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, eigeneprisma/schema/files.prisma→ kein Schema-Konflikt (AD-21). Files braucht RLS-Kontext aus P2 (nutzt dasapp.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(Hetznerfsn1, privat) +STORAGE_*auf web/api/worker gesetzt, DEK viaCRYPTO_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
- 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) - 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)
- ClamAV-Scan beim Upload — Live-EICAR fail-closed auf Staging bewiesen (
scanStatus=infected→ Media-404) - Permissions/Sharing + Tags + Archiv-Flag + Bulk-ZIP (Bulk-ZIP 2026-07-05 gebaut, lokal grün)
- Auth-Proxy-Route für Medien-Auslieferung (AD-23) — privater Bucket,
publicUrl→ Proxy, kein public-read (Staging: 302 auf signierte URL) FileEntityLink(polymorph) an jede Entität + Rollen-Label; Customer-Portal-Upload vorbereitet- Files-Browser server-side-Filter (Entität/MIME-Gruppe/Tags/Verantwortlicher — alle vier, 2026-07-05), Tabelle/Grid-Umschalter
- (→ 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.prismanur 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. DerpublicUrl-Pfad inRowHelper/MediaHelper/ApiHelper(publicUrl ?? file) muss auf diese Route zeigen, nicht auf eine public-S3-URL;STORAGE_PUBLIC_BASE_URLbleibt leer. Genuin öffentliche Assets (E-Mail-Bilder, öffentliche Formular-/Booking-/Portal-Seiten, Branding-Logos) → signierte URLs mit TTL oder separaterpublic/-Prefix mit eng begrenztem public-read (pro Asset-Typ entscheiden). DSGVO-Export-Artefakte folgen seit 2026-07-20 dem strengeren SSE-C-Vertrag: authentifizierter200-App-Proxy, kein signierter Redirect und kein direkter Zugriff ohne Customer-Key. is_demo_dataauf seedbaren Demo-Files (Onboarding-Provisioning).
Quellen (granular)
ENTITY-MODEL.md→ Domäne 3: Files & Tasks (File, FileChunk, FileUploadProgress, FileEntityLink polymorph) + Cross-Cutting-TabelleREQUIREMENTS.md→REQ-files-datenmodell,REQ-files-upload-previewROADMAP.md→ Phase 4 · Milestones: (M052/M053/M054 gedünnt/M055 gedünnt)designer-briefs/P04-files-tasks.mddocs/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-P4aaktualisiert
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.prismaneu (AD-21, eigene Datei, bare String-Scalars, kein Core-Edit). ModelleFile,FileEntityLink(polymorph),FileUpload,FileUploadChunk+ Enums.createdByPortalUserIdnullable als Customer-Portal-Vorbereitung (DoD 12). Proof:prisma validate+prisma generategruen. - §2 Storage-Pfade —
packages/storage/src/paths/(buildFileStorageKeys,buildFilePreviewKey,buildUploadChunkKey,assertFileKeyBelongsToTenantals duenne Klammer um das vorhandeneauthorizeStorageObjectAccess). Proof: 5 neue Unit-Tests gruen (pnpm -F @hivegrid/storage test→ 76 passed). - §4 Queue-Plumbing — neue Queue
hivegrid.file-previewquer durchnames/payloads/producers/groups/index(FilePreviewJob,buildFilePreviewJob, retry-opts, groupgeneral). Proof:pnpm -F @hivegrid/queue typecheck+test(101 passed; dabei eine vorbestehende Luecke im metrics-snapshot-Test geschlossen:buildPluginInvokeJobfehlte). - §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 +PreviewHandlerErrorinhandlers.ts, Bootstrap-Wiring (general group) inindex.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 (enqueueFileScanbereits vorhanden). Proof:pnpm -F @hivegrid/worker typecheckgruen. - §7 Permissions —
files.read_own/read_all/write/delete/admininpackages/db/.../permissions-seed.server.ts(mit expliziten Default-Rollen-Grants, dafiles.*keinenapp./admin.-Prefix traegt) + inapps/web/.../DefaultPermissions.ts. Proof:pnpm -F @hivegrid/db typecheckgruen. - §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 nurdb push; die echte Migration wird beim Merge viaprisma migrate differzeugt 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/. SieheAGENTS.md§„Kommentar-Sprache" (neu, 2026-06-19). - Drei Anti-Patterns (kein
~/db/@prisma/clientinui-app; keinui-subframe-Direktimport inroutes/**; keinuseLoaderDatainui-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 inapps/web/app/routes/app.$tenant/registrieren sich automatisch;*.server.tswird 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-GatetenantHasModule({tenantId,userId,moduleKey:"files"})aus~/utils/connector/tenantConnector.server. - Upload selbst:
storeFile/putBufferAsFile/deleteFileinapps/web/app/utils/integrations/storageService.ts. Magic-Bytes-Allow-List viaresolveAllowListaus@hivegrid/storage. Keys via@hivegrid/storagebuildUploadChunkKey/buildFileStorageKeys(schon gebaut, §2). Chunk 5 MB, max 3 parallel, max 500 MB (Konstanten infile-upload.vm.ts). - Nach
complete:enqueueFileScan({...})(vorhanden,fileScanQueue.server.ts) und einen neuen ProducerenqueueFilePreview(...)(spieglefileScanQueue.server.ts, nutzebuildFilePreviewJob+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: pruefeapps/api/src/storage.ts(createStorageSignedDownloadUrl) bzw. baue web-seitig mit@aws-sdk/s3-request-presigner+createS3SignedUrlAdapteraus@hivegrid/storage. scanStatus=infected→ Klartext-Fehler (fail-closed); verweigert → 404, nicht 403.STORAGE_PUBLIC_BASE_URLbleibt 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/storageergaenzt (createMultipartUpload/uploadPartCopy/completeMultipartUpload/abortMultipartUpload, S3 + Local; Unit-Testmultipart.test.ts). Domain-Serviceapps/web/.../fileService.server.ts(createUploadSession, storeUploadChunk, completeUpload via UploadPartCopy aus Temp-Chunks, Sichtbarkeit, link/unlink/ archive/reactivate/updateMeta/regeneratePreview/hardDelete, listFilesForBrowser). ProducerfilePreviewQueue.server.ts. Resource-Routesfiles.upload.init|.$uploadId.chunk.$index|.complete. Checksum: client-optional (server-Verify = v2, dokumentiert). Worker-Depssharp/heic-convert/pdf-to-png-converterinstalliert. - §6 Auth-Proxy (AD-23) — gemeinsamer SigV4-Signer
@hivegrid/storagecreateSigV4DownloadSigner, web-seitigmediaSigning.server.ts(createMediaDownloadUrl, TTL 300 s), Routemedia.$fileId.$variant.tsx: 302 auf signierte URL, fail-closed bei scanStatus != clean/skipped, 404 bei fremder/fehlender File.STORAGE_PUBLIC_BASE_URLbleibt 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 inui-subframe(renderFileBrowser) undui-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 —
filesals echtes Entitlement-Feature (packages/entitlementsfeatures+blueprint+ plans, Tests angepasst), Such-Indexfiles+ Registry-Eintrag (packages/search), i18nfiles.*de/en intranslations.json(Parity gruen), Sidebar-Eintrag (permissionfiles.read_own, Modul-Gatefiles), Audit (auditFileEvent) auf jeder Schreib-Action, Activity (logFileActivity, gegen verknuepfte Entitaet,file_uploaded). Customer-Portal-FeldcreatedByPortalUserIdvorbereitet. - §13 Tests —
multipart.test.ts(Storage), Hot-SwapfileBrowser.hot-swap.test.ts, Smoketests/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 aufFile.scanStatuszurueck (keindb.file.updateim Scan-Pfad), undenqueueFileScanuebergibt aktuell keinefileId. Folge: mitSCAN_QUEUE_ENABLED=trueblieben neue Files aufscanStatus=pendinghaengen und der Auth-Proxy liefert sie (fail-closed) nicht aus. Aktuell deshalb in Dev/ohne ClamAV: completeUpload setztscanStatus=skipped. To-do vor ClamAV-Aktivierung:fileIdin den Scan-Job aufnehmen und den Worker-Scan-HandlerFile.scanStatus = clean|infectedzurueckschreiben 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.tsnutzteauditEvent/logActivitymit dem rohen Prisma-dbals Client-Argument (DbClient nicht aufAuditEventClientzuweisbar:actorType string|null) und importierte@hivegrid/activity, das keineapps/web-Dependency war. - i18n-Guard (
verify-hardcoded-strings): 5xthrow new Response("Not Found"/"Bad Request", …)loestenuser-facing-response-literalaus (Baseline 0).
Konventionen fuer den naechsten Agenten (nicht erneut falsch bauen):
- Audit immer ueber
createAuditEventaus@hivegrid/db/audit-events.serverschreiben (M001, Hash-Kette), ohne Client-Argument — Default ist der db-Singleton. Nichtfoundation.auditEventmitdbaufrufen. Gleiches Muster fuerlogActivity(kein{ client: db }uebergeben). - Neue Workspace-Pakete als Dependency in der konsumierenden
package.jsoneintragen (+pnpm install). - 4xx aus Loadern/Actions nie als Inline-Literal werfen → Helfer
notFoundResponse()/badRequestResponse()ausfileAccess.server.ts(Return-Form-new Response, vom Guard nicht erfasst; Body ist nie user-facing, ErrorBoundary rendert ServerError). Muster wiemedia.$fileId.$variant.tsx.
Naechste Schritte bis „Done" (Checkliste fuer den naechsten Agenten)
- Scan-Verdict-Rueckschreibung verdrahten (Blocker vor ClamAV-Prod):
fileIdinenqueueFileScan- den Scan-Worker
File.scanStatus = clean|infectedsetzen lassen. Mit Raffael (AK-INFRA2) abstimmen, wer den Boilerplate-Scan-Handler erweitert.
- den Scan-Worker
- 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) auslocal/AK-P4a-merge-migration.sql; an R-P2b (SET LOCAL app.tenant_id,prisma/rls/tenant-isolation.sql) ausrichten.prisma validate+prisma migrate statusgruen. - Live-ClamAV-Smoke (EICAR) auf Staging mit Raffael: Upload EICAR →
scanStatus=infected→ Media-Proxy liefert 404 (fail-closed). - Kleinere Folge-Items abschliessen oder als CR auslagern: Bulk-ZIP-Download, Detail-Breadcrumbs.
- Deferred-DoD vom Reviewer freigeben lassen: Mobile-Tab-Bar (DoD 11), Visual-Regression/M016 (DoD 21).
- 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-tokenizerraus = KI-Dep von main entfernt,heic-convertbehalten),pnpm-lock.yaml(main-Version +pnpm installreconciled), generierter Prisma-Client (pnpm db:generateregeneriert). Branch jetzt 0 hinter main. Full-Typecheck + betroffene Paket-Typechecks gruen. Commita0737b728. - Blocker 1 — Scan-Verdict-Rueckschreibung (§5):
FileScanJob.fileId(optional) durchenqueueFileScan→completeUpload(gibtfile.idmit). Neues Write-back-Seamapps/worker/src/jobs/file-scan-status.ts(Prisma, spiegelt file-preview-Service), im general-Group- Bootstrap (index.ts) verdrahtet. DerfileScan-Handler schreibtclean|infectedaufFile.scanStatus, wennfileId+ Writer da sind (Legacy-Import-Scans ohnefileIdunveraendert). Tests: Handler-Write-back (clean/infected) + Skip-ohne-fileId. Commit7ee0a4135. - Blocker 2 — P4-Files-Migration (§8):
prisma/migrations/20260623160000_p4a_files_platform/(Tabellen + Enums + Indizes + FKs +pg_trgm-Index), viaprisma migrate diff --from-config-datasource --to-schema prisma/schemaerzeugt, auf AK-P4a-Objekte getrimmt (fremder main-Drift NICHT mit reingezogen). Verifiziert: frische Leer-DBmigrate deploylaeuft durch (P3018-sicher),prisma validate+migrate statusgruen, kein File-Drift* mehr. Commit01ff542a8.
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 liestCLAMD_HOST/PORT(scanService.ts); auf Staging-Worker per SSH verifizieren, sonst No-op-Scan.SCAN_QUEUE_ENABLED=truesetzen. - 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 auslocal/AK-P4a-merge-migration.sqlals 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-P4adirekt aufmain(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 Commit300765958kam kein neues Image mehr auf Staging. Ursache: der Pivot loeschtepackages/ai+packages/vector-store, liess aber 8COPY-Zeilen im root-Dockerfilestehen. Diese 8 Zeilen entfernt → Build gruen, Staging zog229cbdce5. - Staging per SSH verifiziert (
staging-1): neues Image live; beide Migrationen (KI-Removal20260623103655+ P420260623160000) angewandt →File/FileEntityLink/FileUpload/FileUploadChunk+FileScanStatus-Enum existieren; clamd aus dem general-Worker erreichbar (PING→PONG, EICAR-StreamEicar-Test-Signature FOUND);CLAMAV_HOST=10.42.0.4/CLAMAV_PORT=3310korrekt (Code liestCLAMAV_*, NICHTCLAMD_*— frueherer Verdacht war falsch);SCAN_QUEUE_ENABLED=truevia 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-
initliefert 404 = korrektes fail-closed —tenantHasModule("files")ist fuer die Demo-Tenants false (dasfiles-Modul ist in keinem Plan/Entitlement;SubscriptionFeatureauf 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, sobaldfilesregulaer in einem Plan ist (oder perTenantFeatureOverride 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 deploynoch 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
filesin einem Plan/Entitlement aktiv ist. - 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.tslaufen jetzt durchwithTenantRLS()(R-P2b-Wrapper). Regeln eingehalten: langsame I/O (S3/Queue) bleibt außerhalb der Transaktion; keine verschachtelten Transaktionen (interne*WithTx(tx, …)-Helfer fürisFileVisible/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-backsjobs/file-preview.ts(writeStatus) undjobs/file-scan-status.ts(recordVerdict) setzen vorfile.update/updateManyden Tenant-GUC (Legacy-Scans ohnetenantIdunverändert direkter Pfad). Worker-Typecheck + Lint grün; Worker-Suitehandlers.test.ts76/76 grün. - Gate-Beweis (neu) —
apps/web/app/utils/db/.server/rls-file-isolation.integration.test.ts(gespiegelt an R-P2bs Test, gated aufRLS_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 CHECKblockt Fremd-Insert; eigener Insert+Read ok;FileEntityLinkebenso 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.sqlalsprisma/rls/file-isolation.sqlins Repo gezogen (parallel zu R-P2bs getracktemprisma/rls/tenant-isolation.sql), damit Raffael ihn für Teil B sieht und der Gate-Test in CI eine getrackte Datei liest. Dabei die fehlendenGRANT SELECT/INSERT/UPDATE/DELETE … TO hivegrid_appauf die vier File-Tabellen ergänzt (R-P2b grantet analog aufTenantUser), 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—~/uiTable+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-FileUploadbringt hartkodierte EN-Copy mit → bewusst nicht genutzt) + Per-Datei-Progress-Queue + HEIC-Alert. Client-Chunked-Pipeline bleibt in der Route und wird alsitems/onFilesreingereicht.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(~/uiButtontype=submit name=intent). Alledata-ui-id/data-row-id/data-link-id/data-statuserhalten.- Routen
files._index/files.upload/files.$idrendern nur noch<XPage vm={} … />; Browser-Loader liest zusätzlich?view=;onApplynavigiert server-side (useNavigate). i18nfiles.*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-convertJPEG 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-Limitfile_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, Mergeae60c6f2d) aufmain. - 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=skippedexistiert nicht mehr:fileScanPolicy.tsliefert nur nochscanStatus === "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=projectkombiniert 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-zipmit 2fileIds→ 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.