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

412 lines
32 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** | 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"**.