Files
HiveGrid-Wireframes/hivegrid-cloud/.planning/ticket-docs/AK-P4a.md
T

32 KiB
Raw Blame History

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 geplant

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

  • Chunked Upload (TUS) + RLS auf Storage-Pfaden (Hetzner Object Storage, S3-kompatibel)
  • Preview PDF→PNG / Bild→WebP / HEIC→JPG (Pflicht!) mit Status-Maschine + Klartext-Fallback
  • ClamAV-Scan beim Upload
  • Permissions/Sharing + Tags + Archiv-Flag + Bulk-ZIP
  • Auth-Proxy-Route für Medien-Auslieferung (AD-23) — privater Bucket, publicUrl → Proxy, kein public-read
  • FileEntityLink (polymorph) an jede Entität + Rollen-Label; Customer-Portal-Upload vorbereitet
  • Files-Browser server-side-Filter (Entität/MIME-Gruppe/Tags/Verantwortlicher), Tabelle/Grid-Umschalter
  • (→ v2) Versionierung/Office-/Video-Previews/Resume-Upload/OCR ausgeschlossen

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 nutzen bereits signierte URLs (unverändert).
  • 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 · PHASE-SOURCES.md → Phase 4 (M052/M053/M054 gedünnt/M055 gedünnt)
  • designer-briefs/P04-files-tasks.md
  • _bmad-output/specs/M23-files.md · Infra: ADR-009 (Hetzner Object Storage)
  • 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)

  • Files-Browser/Detail an Davids UI angepasst
  • REQUIREMENTS/PHASE-SOURCES 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 @toolctrl/storage test → 76 passed).
  • §4 Queue-Plumbing — neue Queue toolctrl.file-preview quer durch names/payloads/ producers/groups/index (FilePreviewJob, buildFilePreviewJob, retry-opts, group general). Proof: pnpm -F @toolctrl/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 @toolctrl/worker. ClamAV (§5) ist Reuse (enqueueFileScan bereits vorhanden). Proof: pnpm -F @toolctrl/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 @toolctrl/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 @toolctrl/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 @toolctrl/storage. Keys via @toolctrl/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 @toolctrl/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 @toolctrl/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 @toolctrl/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 @toolctrl/<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 @toolctrl/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 @toolctrl/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 (@toolctrl/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 @toolctrl/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; @toolctrl/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.
  • Coolify Pre/Post-Deploy-Hooks (Migrate + Seed) reparieren — Infra, eigenes Ticket.
  • 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".