feat(intake): upload a request and enqueue processing atomically

[Fluory]

Warum

Fixes #5 · Teil von Epic #2 · gestapelt auf #31 (Basis claude/feat-identity-tenancy-4).

Arbeitsstand

• Ziel: Upload von .eml/.msg/.pdf/.xlsx/.docx speichert die Originale privat und legt Anfrage (NEW), Dokumente, Audit-Ereignis und pg-boss-Job in einer Transaktion an; exakte Duplikate werden markiert.
• Nicht-Ziele: Postfach-Import, Near-Duplicate-Hinweise, die Verarbeitung selbst (feat(jobs,extraction): process requests in the worker with retries and visible errors #7).
• Erledigt: alle Akzeptanzkriterien mit Tests; frischer Review + Security-Review eingearbeitet (Kommentar); pnpm verify lokal grün; Migrationen auf frischer Datenbank getestet.
• Offen: menschliche Freigabe; Entscheidungen in feat(intake): upload a request and enqueue processing atomically #5 (decision-needed).
• Annahmen: siehe Impact Manifest.
• Nächster kleinster Schritt: Review durch den Orchestrator nach dem Merge von feat(identity,tenancy): invite-only login, companies and forced RLS #31.

Was ist passiert (Klartext)

Sachbearbeiter:innen können jetzt unter /requests eine Anfrage hochladen – eine E-Mail oder lose Dateien. Das System prüft jede Datei streng: erlaubte Endung und passender Inhalt (eine umbenannte Programmdatei oder eine Excel-Datei mit Makros wird abgelehnt), Größe und Anzahl sind begrenzt. Die Originale landen in einem privaten Speicher; herunterladen kann sie nur, wer zur selben Firma gehört.

Anfrage, Dokumente, Protokolleintrag und der Verarbeitungsauftrag entstehen in einem einzigen Schritt: Geht irgendetwas schief, gibt es nichts davon – auch keine halb angelegte Anfrage und keine verwaiste Datei. Doppelte Anfragen (gleiche E-Mail-Kennung oder genau dieselben Dateien) werden erkannt, markiert und mit dem Original verknüpft, aber nie verworfen. Das Protokoll kann von der Anwendung nur ergänzt, nie geändert oder gelöscht werden.

Plan-Pflicht (SYSTEM.md §4)

• Kein Auslöser – keine Modulgrenze, öffentliche API, Migration, Auth/Rechte, kein Zahlungs-/Daten-/Infrapfad, höchstens zwei Module, keine Architekturvarianten, umkehrbar
• Auslöser zutreffend – Impact Manifest ausgefüllt (Plan vor Code)

Impact Manifest

• Betroffene Module: intake (Validierung inkl. OOXML-Struktur, Fingerprint, Mail-Header, submitUpload), documents, storage (put/get/stream/delete), audit (recordAudit), jobs (Queue-Definitionen, transaktionales Enqueue), requests (Intake-Spalten, Duplikatsuche mit Lock), db (Migrationen 0003–0005, job-queue.ts, job-queue-client.ts), app (Routen, Seiten /requests, /requests/:id), config (Upload-Limits).
• Schnittstellen / Datenänderungen: POST /api/requests (multipart files), GET /api/documents/:id (Vertrag in docs/technical/api.md); Tabellen app.documents, app.audit_events (FORCE RLS; Audit append-only per Grants); app.requests + Intake-Spalten; Composite-FKs (…, company_id); Schema pgboss (Deploy-Schritt als app_owner, app_rw mit engen Rechten).
• Akzeptanzkriterien: alle aus feat(intake): upload a request and enqueue processing atomically #5 (Nachweis unten).
• Testplan: Unit test-first (Typ + Signatur + OOXML-Struktur, Größe, Dateiname, Fingerprint, Mail-Header); Integration gegen echtes Postgres + SeaweedFS + pg-boss.
• Verifizierte Fakten: pg-boss 12.33.6 (MIT): send(…, { db: fromDrizzle(tx, sql) }) schreibt den Job über die übergebene Transaktion (Test zählt ihn darin); Policy exclusive + singletonKey = höchstens ein wartender/aktiver Job pro Anfrage; Installation als app_owner, Senden als app_rw funktioniert mit den engen Grants.
• Offene Annahmen: Upload-Limits (20 MiB/Datei, 10 Dateien, 40 MiB/Request) – Kundenwert offen.
• Nicht-Ziele: Postfach, Near-Duplicates, Verarbeitung.
• Risiken und Rollback: Datei-Upload ist Angriffsfläche → Allow-List + Inhaltsprüfung, Body-Grenze vor dem Lesen, bereinigte Dateinamen, Download nur als Attachment mit nosniff; zwei akzeptierte Restrisiken im Ausnahmenregister (siehe feat(intake): upload a request and enqueue processing atomically #5); Migrationen additiv; Rollback per Revert.

Akzeptanzkriterien → Nachweis

Kriterium	Test
Upload .eml/.msg/.pdf/.xlsx/.docx bis zur Größe; andere Typen klar abgelehnt	files.test.ts, ooxml.test.ts (Unit); upload-routes.test.ts (422 mit Meldung, 411, 413, zu viele Dateien)
Originale unter {companyId}/{requestId}/{documentId} privat; Download nur authentifiziert mit Tenant-Prüfung	intake.test.ts (Schlüssel, Objekt vorhanden); upload-routes.test.ts (eigene Firma 200, fremde 404, anonym 401)
Anfrage, Dokumente und pg-boss-Job in einer Transaktion – Fehler nach dem Insert rollt alles zurück	intake.test.ts: Job-Zeile innerhalb der Transaktion sichtbar (1), danach 0; Anfrage, Dokumente, Audit weg; gespeicherte Objekte gelöscht
Gleiche Message-ID oder gleiches SHA-256-Set in der Firma → mögliches Duplikat	fingerprint.test.ts (Unit); intake.test.ts (Message-ID, Datei-Set in anderer Reihenfolge, nur innerhalb der Firma). .msg-Message-ID: bekannte Grenze (api.md, #23)
Upload als Audit-Ereignis	intake.test.ts (request.uploaded mit Akteur); append-only per Grants getestet

Geändert

• src/features/intake/ (files.ts, ooxml.ts, fingerprint.ts, mail-headers.ts, submit.ts, Tests, zip-fixture.ts), src/features/documents/, src/features/audit/, src/features/jobs/, src/features/requests/repository.ts, src/features/storage/s3-blob-store.ts.
• src/db/schema/app.ts, Migrationen 0003_intake.sql, 0004_intake_force_rls_audit.sql, 0005_intake_same_company_fks.sql; src/db/job-queue.ts (Enqueue in Transaktion), src/db/job-queue-client.ts (Pool-Fabrik + Installation mit engen Grants).
• src/app/api/requests/route.ts, src/app/api/documents/[id]/route.ts, src/app/requests/*, src/app/_server/runtime.ts, Startseite; src/setup.ts installiert die Queues.
• .dependency-cruiser.cjs: Regeln pg-boss-client-only-in-db, Pool-Fabrik unter no-db-connection-in-features (+ Fixture).
• src/config/env.ts, .env.example: UPLOAD_MAX_FILE_BYTES, UPLOAD_MAX_FILES, UPLOAD_MAX_REQUEST_BYTES.
• Tests: tests/integration/{intake,upload-routes}.test.ts; Helper mit zufälligen IPv6-Adressen (kein Rate-Limit-Übertrag).
• Doku: data-model.md, api.md, Architekturkarte (Status, zwei Ausnahmen), CHANGELOG.

Nachweis (SYSTEM.md §11)

• verify:changed: grün
• verify: grün – lokal: lint, typecheck, 48 Unit + 44 Integrationstests (PostgreSQL 17, SeaweedFS 4.47, pg-boss), depcruise 0 Verstöße, build, audit 0 high; alle Migrationen zusätzlich auf frischer Datenbank (requestflow_fresh) angewandt, 44/44 grün. CI check + compose-smoke: siehe Checks dieses PRs.
• verify:full / E2E-Spec: nicht betroffen
• Manueller Prüfnachweis: Routen im Integrationstest über die echte Web-Runtime (Session → Akteur → Tenant); Seite /requests im Build.
• Frischer Review (P1 vor Ready-for-review; Architektur/API/DB immer): feat(intake): upload a request and enqueue processing atomically #32 (comment) – alle Important behoben oder als Ausnahme zur Entscheidung vorgelegt

Doku-Entscheidung (genau eine)

• Keine langlebige Doku betroffen – Begründung: –
• Doku betroffen und im selben PR aktualisiert:
  • Produktdoku (P0: README): –
  • Technische Doku: docs/technical/data-model.md, docs/technical/api.md
  • Architekturkarte: docs/technical/architecture.md (Status, Ausnahmenregister)
  • ADR: –
  • CHANGELOG [Unreleased] (sichtbares Feature oder Verhalten – im selben PR, nie „später")

Entferntes oder Umbenanntes: nichts entfernt

Dateigrößen und neue Bausteine (SYSTEM.md §7)

Dateien über 500 Zeilen im Diff (Ausnahmen: generierter Code, Lockfiles, Fixtures, Migrationen, Schemas, Ressourcen, Doku, Konfiguration):

• keine
• bewusst belassen – Begründung: –
• im selben PR nach fachlicher Verantwortung geteilt
• Folge-Issue –

Über 800 Zeilen mit neuer Fachlogik oder über 1000 Zeilen (P1/P2): nicht betroffen

Neue Shared-Komponente, Utility-Datei, Adapter oder fachlicher Service:

• nein
• ja – gesucht nach: vorhandenem Upload-/Hash-/Audit-/Queue-Code in src/; gefunden: nichts – Module intake, documents, audit, jobs sind Skelette aus chore(app): TS app skeleton, docker compose and verify commands #3; storage wird erweitert statt dupliziert

Subagent-Einsätze

• Frischer Review + Security-Review: unabhängiger Subagent (read-only) – 5 Important, 3 Notes, alle bearbeitet.

Risiken / offene Punkte

• decision-needed in feat(intake): upload a request and enqueue processing atomically #5: kein Pro-Nutzer-Rate-Limit beim Upload; .msg nur per Signatur geprüft.
• Hook-Ausnahme: ein drizzle-kit generate lief im separaten Worktree mit FLUORY_NO_CHECKPOINT=1, weil der Checkpoint-Guard das Session-Verzeichnis prüft (dort lag ein anderer Branch mit unfertigen Dateien); der Worktree war committet.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01DJ5vaKvTYiMvdngT4d3xo1

[Fluory]

Frischer Review + Security-Review (unabhängiger Subagent) – Befunde und Auflösung

Review nach review-pr + .claude/rules/security.md, read-only. Auflösung in den Commits „fix(intake): address the fresh security review of PR #32" und „test: rate-limit assertion …".

#	Befund	Auflösung
Important (security)	413 vertraute Content-Length; fehlend/ungültig → durchgelassen, ganzer Body im Speicher	behoben – ohne numerische Länge 411, Gesamtobergrenze UPLOAD_MAX_REQUEST_BYTES (Default 40 MiB) vor dem Lesen (Node erzwingt die deklarierte Länge); Tests 411/413/zu viele Dateien. Kein Pro-Nutzer-Rate-Limit im Pilot → Ausnahmenregister (nur angemeldetes Personal, bis #19)
Important (security)	.xlsx/.docx akzeptierten jedes ZIP, .msg jedes OLE	behoben für OOXML – Zentralverzeichnis wird gelesen (nichts entpackt): [Content_Types].xml + Hauptteil nötig, vbaProject.bin/Makrosheets/ActiveX abgelehnt, Entry-Zahl und deklarierte Größe begrenzt (Zip-Bomben); 5 Unit-Tests. .msg weiter nur Signatur → Ausnahmenregister bis #23, Kommentar in files.ts korrigiert
Important (security/architecture)	jobs öffnete eigenen pg-boss-Pool und vergab breite Grants	behoben – pg-boss-Client, sendInTransaction und Queue-Installation liegen in src/db/job-queue.ts; jobs nutzt nur einen injizierten JobSender; neue depcruise-Regel pg-boss-client-only-in-db; Grants auf das Nötige verengt (Job-Tabellen DML, queue SELECT/UPDATE, version/schedule/subscription SELECT)
Important	Message-ID nur aus .eml; .msg-Duplikate kaum erkennbar	als bekannte Grenze in api.md dokumentiert; .msg-Parsing kommt mit #23, Duplikat-UI mit #27
Important	PR-Beschreibung veraltet	behoben (diese Aktualisierung)
Note	Rollback-Test bewies den Job-Insert nicht; Audit nicht geprüft; null-Job-ID ignoriert	behoben – der Test zählt die Job-Zeile innerhalb der Transaktion (1) und danach (0), Audit leer; sendInTransaction wirft bei null
Note	Composite-FKs nur in handgeschriebener SQL, Schema-Drift	behoben – unique()/foreignKey() im Drizzle-Schema, Migration 0005 (Reihenfolge korrigiert: UNIQUE vor den FKs), auf frischer Datenbank getestet
Note	500-Log ohne Fehlerklasse; Aufräumfehler still; Race bei gleichzeitigen Duplikaten; Download puffert	behoben – Log mit Fehlerklasse/Code + IDs; verwaiste Objekte werden mit Schlüssel geloggt; Advisory-Lock pro Firma für die Duplikatprüfung; Download streamt

Beim Nachtest gefunden und behoben: der Test-Helper vergab Fake-IPs pro Testdatei neu → Rate-Limit-Übertrag zwischen Dateien (429). Jetzt zufällige IPv6-/64-Präfixe pro Aufruf.

Hinweis Hook: drizzle-kit generate lief im separaten Worktree mit FLUORY_NO_CHECKPOINT=1, weil der Checkpoint-Guard das Session-Verzeichnis (anderer Branch mit unfertigen Dateien) prüft; der Worktree selbst war committet.

Verdict des Reviewers: nach Behebung mergebar, menschliche Freigabe nötig (Security, Migration, öffentliche API).

---

Generated by Claude Code