feat(review): review fields beside their source, correct, approve or reject

[Fluory]

Warum

Fixes #8 · Teil von Epic #2 · gestapelt auf #34 (Basis claude/feat-jobs-worker-7).

Arbeitsstand

• Ziel: Sachbearbeitung sieht jedes Feld mit Status und Quelle, korrigiert Werte und gibt frei oder lehnt ab; jede Änderung wird im selben Schritt protokolliert.
• Nicht-Ziele: Sammelaktionen, Rollen-Admin-UI (feat(identity): simple user and role management for admins #30), Near-Duplicate-Hinweise; Positionen (feat(review): line items and all formats in the review UI #25); Export-Handler (feat(export): export approved requests exactly once to the ERP mock #9).
• Erledigt: Schema + Migrationen 0009/0010, Review-Dienst, Seite /requests/:id mit Server Actions, Quellenansicht, Unit-/Integrationstests, Playwright-Smoke in verify:full, CI-Schritt für Chromium, Doku, frischer Review inkl. Fixes.
• Offen: Merge durch den Orchestrator nach feat(jobs,extraction): process requests in the worker with retries and visible errors #34; decision-needed (Quellenansicht als Text).
• Annahmen: siehe Impact Manifest.
• Nächster kleinster Schritt: Review durch den Orchestrator; danach feat(export): export approved requests exactly once to the ERP mock #9 (Export) auf diesem Branch.

Was ist passiert (Klartext)

Die Prüfansicht ist fertig. Jede erkannte Angabe (Firma, Ansprechpartner:in, Liefertermin) steht mit ihrem Status in einer Tabelle; „unsicher" und „nicht bestätigt" sind farbig und mit Warnzeichen markiert. Ein Klick auf „Quelle anzeigen" zeigt die Mail-Zeile bzw. PDF-Seite mit der markierten Fundstelle. Korrekturen speichern alten und neuen Wert, Person und Zeit – im selben Schritt wie der Audit-Eintrag; ein korrigierter Wert heißt danach „korrigiert", nie mehr „belegt". „Freigeben" setzt die Anfrage auf Freigegeben und plant den Export im selben Schritt ein; „Ablehnen" verlangt einen Grund. Andere Firmen sehen und ändern nichts (geprüft). Neu ist ein Browser-Test, der den ganzen Weg Hochladen → Verarbeitung → Prüfen → Korrigieren → Freigeben durchspielt (KI-Dienst dabei als Attrappe). CI-Änderung: Der Schritt verify:full (nur mit Label verify-full) installiert jetzt vorher Chromium – rein additiv.

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: review (Ansicht, Korrektur, Freigabe, Ablehnung), requests (Übergänge REVIEW → APPROVED/REJECTED, Ablehnungsgrund), audit, jobs (Export-Queue-Definition + transaktionales Einstellen; Handler in feat(export): export approved requests exactly once to the ERP mock #9), db (Migrationen 0009/0010), app (Seite /requests/:id mit Server Actions), E2E (Playwright-Smoke in verify:full), CI (Chromium-Installation vor verify:full).
• Schnittstellen / Datenänderungen: Tabelle app.field_corrections (append-only, FORCE RLS); app.requests.rejection_reason; Queue request-export; Server Actions (Rollenprüfung serverseitig, feste Meldungscodes in der URL).
• Akzeptanzkriterien: alle aus feat(review): review fields beside their source, correct, approve or reject #8 – siehe Nachweis.
• Testplan: Unit (Quellenansicht); Integration (Korrektur + Audit in einer Transaktion, Status „korrigiert", Freigabe + Export-Job in einer Transaktion inkl. Rollback, Ablehnung mit Grund, falscher Status, fremde Firma inkl. RLS auf field_corrections, append-only); Playwright-Smoke.
• Verifizierte Fakten: @playwright/test 1.63.0 (Apache-2.0); vorinstalliertes Chromium der Session ist Revision 1194 → lokal per PW_CHROMIUM_PATH, in CI per playwright install --with-deps chromium.
• Offene Annahmen: „PDF-Seite mit Hervorhebung" ist im Pilot eine Textansicht der Seite (Segmente in Lesereihenfolge, Zitat markiert) plus Link aufs Original, kein gerendertes PDF → decision-needed in feat(review): review fields beside their source, correct, approve or reject #8.
• Nicht-Ziele: siehe oben.
• Risiken und Rollback: Rollenprüfung in jeder Server Action und im Modul; kein Dokumentinhalt in Logs; Migrationen additiv; Rollback per Revert.

Geändert

• src/db/schema/app.ts, Migrationen 0009_review.sql, 0010_review_force_rls.sql; src/features/jobs/{queues,boss}.ts (Export-Queue, enqueueRequestExport)
• src/features/review/{review,source-view,index}.ts (+ Unit-Test)
• src/app/requests/[id]/{page,actions,messages}.tsx/ts, src/app/requests/status-labels.ts, src/app/requests/page.tsx (Statusbeschriftung), src/app/globals.css, layout.tsx
• tests/integration/review.test.ts; playwright.config.ts, tests/e2e/{ai-stub.mjs,global-setup.ts,review-smoke.spec.ts}; package.json (e2e, verify:full, @playwright/test)
• .github/workflows/ci.yml (Chromium vor verify:full, gleiche Bedingung)
• Doku: docs/technical/data-model.md, docs/technical/architecture.md, CHANGELOG.md, AGENTS.md (verify:full-Zeile)

Nachweis (SYSTEM.md §11)

• verify:changed: typecheck + lint + vitest review (Unit 5/5, Integration 12/12) grün
• verify: lokal grün (Exit 0) gegen echtes PostgreSQL 17 + SeaweedFS – Unit 105/105, Integration 68/68, depcruise ohne Verstöße, Build, Audit (nur 1 moderate, Schwelle high); CI check: siehe Checks dieses PRs
• verify:full / E2E-Spec: tests/e2e/review-smoke.spec.ts lokal grün (1 passed, 14 s) mit Worker, gebauter App und KI-Stub; in CI per Label verify-full
• Akzeptanzkriterien feat(review): review fields beside their source, correct, approve or reject #8: Felder mit Status + Quelle → Integration „shows every field…" + Unit Quellenansicht + E2E; Korrektur mit Protokoll → Integration „stores a correction…"; Freigabe → Export → Integration „approve…" (inkl. Rollback bei Enqueue-Fehler); Ablehnung mit Grund → Integration „reject…"; nur Rolle mit Recht / eigene Firma → Integration „another company…", „keeps corrections company-private…"
• Manueller Prüfnachweis: Tastatur – alle Aktionen sind native Formulare/Links; Status nie nur über Farbe (Text + ⚠)
• Frischer Review (P1 vor Ready-for-review; Architektur/API/DB immer): unabhängiger Subagent nach review-pr inkl. Security-Regel – 0 Blocker, 3 should-fix + 5 nits; alle should-fix behoben, Ergebnis als PR-Kommentar

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
  • Architekturkarte: docs/technical/architecture.md
  • 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 Review-/Korrektur-Code und Statusbeschriftungen; gefunden: review war ein Skelett aus chore(app): TS app skeleton, docker compose and verify commands #3, Statusbeschriftung nur lokal in der Detailseite → nach status-labels.ts verschoben und in Liste + Detail genutzt

Subagent-Einsätze

• Frischer Review (read-only, review-pr + Security-Regel): Ergebnis und Auflösung als PR-Kommentar.

Risiken / offene Punkte

• Quellenansicht als Textansicht statt gerendertem PDF (decision-needed in feat(review): review fields beside their source, correct, approve or reject #8).
• Datenschutz: korrigierte Werte und Ablehnungsgründe stehen auch im append-only Audit und lassen sich dort nicht pro Anfrage löschen – gehört zur offenen Aufbewahrungsfrage (ADR-0001 offene Punkte), in data-model.md vermerkt.
• Folge für feat(jobs,extraction): process requests in the worker with retries and visible errors #7 (nicht in diesem PR): ein Job mit ungültigen IDs lässt drain() nach dem fail() einmal abbrechen (worker.drain_failed); der Job läuft trotzdem regulär in Retry/Dead-Letter – kein Hänger, aber unschönes Log. Kandidat für einen kleinen Härtungs-Fix.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01DJ5vaKvTYiMvdngT4d3xo1

[Fluory]

Frischer Review (unabhängiger Subagent, read-only, review-pr + Security-Regel)

Ergebnis: 0 Blocker · 3 should-fix · 5 nits. Bestätigt: Tenant-Isolation (jeder Zugriff in withTenant, Firma aus Session), serverseitige Rollenprüfung in Actions und Modul, Freigabe + Export-Job + Audit in einer Transaktion unter Zeilensperre, Quellenansicht rendert nur Textknoten, CSRF über Next-Origin-Check, CI-Änderung rein additiv.

#	Schwere	Befund	Auflösung
1	should-fix	Korrigierter Wert behielt den Status found („belegt") samt altem Zitat – widerspricht „found needs proof" (D8)	reviewStatus = corrected („korrigiert"), Extraktionsstatus separat als „erkannt: …"; Quellenpanel sagt, dass es die Fundstelle des erkannten Werts ist. Integrationstest „shows a corrected value as corrected – never as found"
2	should-fix	?done=/?error= wurden als Freitext in role=status/alert angezeigt (Phishing-Text per Link)	Actions leiten nur feste Codes weiter; messages.ts bildet sie auf Texte ab, unbekannte Codes werden ignoriert. ReviewRefused trägt jetzt einen code
3	should-fix	Kein Nachweis der RLS auf field_corrections	Test „keeps corrections company-private": fremde Firma sieht keine Historie, Insert mit fremder company_id scheitert an row-level security; zusätzlich rejectRequest/correctField aus fremder Firma abgelehnt
4	nit	Ungültige requestId → ZodError → 500	safeParse → notFound()
5	nit	Ablehnungsgrund still auf 1000 Zeichen gekürzt	wird jetzt abgelehnt (reason_too_long), Test ergänzt; DB-Check-Constraint bewusst nicht ergänzt (Modul ist der einzige Schreibpfad)
6	nit	Zitat-Markierung per toLowerCase() kann bei Zeichen wie „İ" verrutschen	exakter Treffer zuerst, case-insensitiver Fallback nur bei gleicher Länge, sonst ganzes Segment markiert; Unit-Test ergänzt
7	nit	corrected_by ohne FK	bewusst (wie audit_events.actor_user_id, Historie überlebt Nutzerentfernung) – in data-model.md dokumentiert
8	nit	Personenbezogene Werte im append-only Audit nicht pro Anfrage löschbar	in data-model.md und PR-Risiken vermerkt, gehört zur offenen Aufbewahrungsfrage (ADR-0001)

Nach den Fixes: Review-Tests Unit 5/5, Integration 12/12, E2E-Smoke grün; pnpm verify läuft erneut.

---

Generated by Claude Code