Skip to content

feat(review): original PDF page beside the values with the cited passage highlighted - #97

Draft
Fluory wants to merge 4 commits into
mainfrom
claude/feat-pdf-source-view-74
Draft

feat(review): original PDF page beside the values with the cited passage highlighted#97
Fluory wants to merge 4 commits into
mainfrom
claude/feat-pdf-source-view-74

Conversation

@Fluory

@Fluory Fluory commented Sep 28, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

Warum

Fixes #74 · Showcase-Review 2026-09-27, P1 Punkt 2 (Epic #19) · Entscheidung pdf.js: ADR-0002

Arbeitsstand

  • Ziel: Eine Besucherin versteht in einer Minute: „Ich muss der KI nicht blind glauben – ich sehe jeden Wert im Original.“ Die Prüfseite zeigt die Original-PDF-Seite mit markierter Fundstelle neben den Werten; unsichere, fehlende und nicht bestätigte Werte sagen im Klartext, warum.
  • Nicht-Ziele: Werte auf der gerenderten Seite bearbeiten, OCR neu anstoßen, PDFs innerhalb von Outlook-Nachrichten rendern (die Route liefert die .msg, nicht den Anhang).
  • Erledigt: Abhängigkeit pdfjs-dist + ADR-0002; region (Seite + Box) in der Quellansicht; Überlagerung Box → Prozent; Klartext-Gründe; Client-Komponente mit vergrößertem Ausschnitt um die Fundstelle, „Ganze Seite“, Lade- und Fehlerzustand; Musterfall werk-ost = Mail + synthetische PDF-Positionsliste (mehrere Dateien je Musterfall, Aufzeichnung je Datei); Integrations- und E2E-Erwartungen; Architekturkarte, CHANGELOG.
  • Offen / blockiert: Aufzeichnung werk-ost.recording.json + werk-ost-positionen.recording.json fehlt. Zwei Läufe von pnpm samples:record werk-ost gegen den Showcase-KI-Dienst scheiterten (16 Versuche): Gemini Free Tier antwortete erst 503 (überlastet), dann 429 (Rate-Limit). Vermutlich Tageskontingent erschöpft – weitere Versuche verbrennen nur Kontingent. Bis dahin sind samples.test.ts (Unit) und damit verify rot. Danach: frischer Review.
  • Annahmen: docling liefert Boxen im Raum der angezeigten Seite (bei /Rotate 90 bereits gedreht) – geprüft mit einer gedrehten Test-PDF, siehe ADR-0002.
  • Nächster kleinster Schritt: Nach Reset des Kontingents einmal AI_SERVICE_URL=… AI_SERVICE_TOKEN=… pnpm samples:record werk-ost, Ergebnis prüfen (Liefertermin uncertain aus der PDF, Positionen aus der PDF), Tests anpassen, CI.

Was ist passiert (Klartext)

Bisher zeigte die Prüfseite die Fundstelle eines Werts nur als Text. Jetzt sieht man bei PDF-Dokumenten die Originalseite selbst, und die Stelle, aus der die KI den Wert gelesen hat, ist farbig umrahmt. Wählt man einen anderen Wert (mit Maus oder Tastatur), springt die Markierung dorthin. Neben unsicheren oder fehlenden Werten steht in einfachen Worten, warum sie geprüft werden müssen, zum Beispiel „Kalenderwoche ohne Datum“. Die PDF wird nur über den bestehenden, geschützten Download geladen – es geht keine Anfrage an fremde Server.

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 (source-view.ts: region), samples (Musterfall mit PDF, Aufzeichnung je Datei), app (Prüfseite: pdf-page.tsx, pdf-overlay.ts, reason-label.ts, CSS). Neue Abhängigkeit pdfjs-dist 6.3.289 (Apache-2.0) – ADR-0002.
  • Schnittstellen / Datenänderungen: keine Schema-, API- oder Routenänderung. SourceView bekommt region: PageRegion | null (öffentlicher Typ des Review-Moduls). Das Original kommt weiter nur über GET /api/documents/:id (Tenant-Prüfung, 404 für fremde Dokumente).
  • Akzeptanzkriterien: die fünf aus feat(review): original PDF page beside the extracted values with the cited passage highlighted #74.
  • Testplan: Unit – region (gültige Box, Mail, PDF in .msg, kaputte Boxen), overlayOf (Prozent, Rand, gedrehte Seite, außerhalb), reasonText (Grund, Rückfall je Status, belegt/korrigiert). Integration – bestehender Test der Download-Route (kein fremdes Dokument) bleibt grün; Musterfall-Seed mit PDF. E2E – Musterfall: Seite gerendert, Markierung sichtbar, Wechsel des Werts per Tastatur verschiebt die Markierung, Klartext-Grund.
  • Verifizierte Fakten: Boxen sind in PDF-Punkten, Ursprung oben links (PdfLocator); textlines-Pipeline liefert eine Box je Textzelle (lokal mit der synthetischen Positionsliste geprüft); pdf.js 6 enthält kein eval/new Function und kennt isEvalSupported nicht mehr.
  • Offene Annahmen: keine.
  • Nicht-Ziele: siehe oben.
  • Risiken und Rollback: Worker-Auflösung im Next-Build (new URL(…, import.meta.url)) – Beweis im CI-Build + E2E; Rendering-Fehler fallen auf die Textansicht zurück. Rollback per Revert.

Geändert

  • package.json, pnpm-lock.yaml: pdfjs-dist 6.3.289
  • docs/decisions/ADR-0002-pdf-page-view.md (neu), INDEX.md
  • src/features/review/source-view.ts (+ Test), index.ts: region, PageRegion
  • src/app/requests/[id]/pdf-page.tsx (neu), pdf-overlay.ts (+ Test, neu), reason-label.ts (+ Test, neu), review-parts.tsx, page.tsx, src/app/review.css
  • src/features/samples/samples.ts (+ Test), seed.ts, index.ts, src/samples-record.ts: Musterfall aus mehreren Dateien, Aufzeichnung je Datei
  • src/features/samples/data/werk-ost.eml (Positionen jetzt im Anhang), werk-ost-positionen.pdf (neu, synthetisch, unkomprimiert – der Inhalt ist im PDF lesbar)
  • tests/integration/samples.test.ts, tests/e2e/sample-smoke.spec.ts
  • docs/technical/architecture.md, CHANGELOG.md

Nachweis (SYSTEM.md §11)

  • verify:changed: grün – source-view.test.ts 11/11 (die zwei neuen zuerst rot), pdf-overlay.test.ts 4/4, reason-label.test.ts 3/3; tsc, eslint sauber
  • verify: rot, erwartet – Aufzeichnung fehlt (siehe Arbeitsstand). Der erste CI-Lauf ohne Musterfall-Änderung war grün (36451819606: Build mit pdf.js und Worker-Pfad ok, Integration 144/144, E2E 3/3); der Vercel-Web-Preview baute ebenfalls. Der rote Check „Vercel – requestflow-ai“ ist die volle Container-Registry (infra(ai): Vercel container registry is full – AI service builds fail #98), nicht dieser PR.
  • verify:full / E2E-Spec: sample-smoke.spec.ts erweitert (PDF gerendert, Markierung, Klartext-Grund, Wechsel per Tastatur) – läuft nach der Aufzeichnung
  • Manueller Prüfnachweis: Screenshots nach dem Deploy
  • Frischer Review (P1 vor Ready-for-review; Architektur/API/DB immer): folgt

Doku-Entscheidung (genau eine)

Entferntes oder Umbenanntes: docs/ + README gegrept, Treffer bereinigt: 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: vorhandener PDF-/Canvas-Darstellung, Box-Umrechnung und Grund-Texten (source-view.ts, review-parts.tsx, value-label.ts, describe-failure.ts); gefunden: keine Darstellung, Boxen wurden gespeichert, aber nie genutzt (feat(review): review fields beside their source, correct, approve or reject #8); Gründe wurden nirgends angezeigt. Neu nur in der App-Schicht der Prüfseite, keine geteilte Komponente.

Subagent-Einsätze

Keine bisher.

Risiken / offene Punkte

  • Siehe Impact Manifest.

🤖 Generated with Claude Code

Fluory and others added 2 commits September 28, 2026 18:21
@Fluory @claude
build(deps): add pdfjs-dist to show the original PDF page in review (#74
419b784 
)

The review screen shall show the cited PDF page with the stored bounding
box highlighted. pdf.js renders the original in the browser from the
existing tenant-checked document route: no new route, no public URL, no
third-party request, no extra load on the stateless AI service.
Apache-2.0, pinned; loaded lazily only when a PDF source is shown.
Decision and rejected options: ADR-0002.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@Fluory @claude
feat(review): original PDF page beside the values with the cited box …
c355b49 
…highlighted

- source view carries the cited segment's page and box for a PDF document
  itself (not for a PDF inside an Outlook message: the route serves the .msg)
- client component renders that page with pdf.js from the tenant-checked
  document route, magnified around the highlight, "Ganze Seite" toggle;
  falls back to the text view when the page cannot be rendered
- uncertain, missing and unverified values say why in plain language

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@Fluory Fluory added the verify-full Run verify:full (integration + E2E) in CI label Sep 28, 2026
@vercel

vercel Bot commented Sep 28, 2026 •
edited
Loading

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
requestflow Ready Ready Preview Sep 28, 2026 4:36pm UTC
requestflow-ai Error Error Sep 28, 2026 4:36pm UTC

Fluory and others added 2 commits September 28, 2026 18:37
@Fluory @claude
wip(samples): a sample may consist of several files; review sample ge…
869feb2 
…ts a PDF position list (#74)

Recordings follow in the next commit (tests red until then).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@Fluory @claude
test(samples): PDF source on the review sample in integration and E2E…
6ad54dd 
…; docs (#74)

- integration: the review sample has mail + PDF, and its uncertain value
  opens on the PDF page with a region
- E2E: page rendered, highlight visible, plain-language reason; moving to a
  position by keyboard moves the highlight
- architecture map and CHANGELOG

The recordings of werk-ost (mail + PDF) are still missing: the Gemini free
tier answered 503/429 on two recording runs. Sample tests stay red until then.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@vercel

vercel Bot commented Sep 28, 2026

Copy link
Copy Markdown

Deployment failed for project requestflow with the following error:

Resource is limited - try again in 24 hours (more than 100, code: "api-deployments-free-per-day").

Learn More: https://vercel.com/doc-edit?upgradeToPro=build-rate-limit

@vercel

vercel Bot commented Sep 28, 2026

Copy link
Copy Markdown

Deployment failed for project requestflow-ai with the following error:

Resource is limited - try again in 24 hours (more than 100, code: "api-deployments-free-per-day").

Learn More: https://vercel.com/doc-edit?upgradeToPro=build-rate-limit

@Fluory Fluory added the blocked Waiting on a decision or dependency label Sep 28, 2026
This was referenced Sep 28, 2026
Merged
Draft

This branch had an error being deployed

1 failed (outdated) and 1 active (outdated) deployments
Preview – requestflow — c355b493 Deployed Sep 28, 2026 by vercel[bot]
View deployment
Preview – requestflow-ai — c355b493 Deployed Sep 28, 2026 by vercel[bot]
View deployment
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

blocked Waiting on a decision or dependency verify-full Run verify:full (integration + E2E) in CI

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

feat(review): original PDF page beside the extracted values with the cited passage highlighted

1 participant

@Fluory