feat(ai-service): XLSX, DOCX, MSG and scanned PDFs

[Fluory]

Warum

Fixes #23 · Epic #17 · gestapelt auf #39 (Basis claude/feat-ai-full-fields-22).

Arbeitsstand

• Ziel: Alle vom Kunden genannten Formate werden in Segmente mit stabilen Fundstellen zerlegt – XLSX, DOCX, Outlook-MSG (inkl. Anhänge, rekursiv) und gescannte PDFs (OCR).
• Nicht-Ziele: Positions-UI (feat(review): line items and all formats in the review UI #25), Eval-Gate (feat(evals): eval runner, 15 weighted synthetic cases and CI gate #24).
• Erledigt: AI-Service (Parser, Grenzen gegen feindliche Dokumente inkl. OLE-Bomben-Schutz und Budget je Dokument, OCR mit Deckel „höchstens unsicher" und Seitenbegrenzung mit Warnung, Teilfehler bei Anhängen, Messungen); TS-Seite (Vertragstypen, Client-Validierung, Worker sendet die neuen Formate, fehlgeschlagene Anhänge werden gespeichert und in der Prüfansicht angezeigt); Doku; Security-Review inkl. Fixes.
• Offen: Merge durch den Orchestrator nach feat(ai-service): full field set including line items #39; decision-needed (OCR-Modelle/Host, siehe feat(ai-service): XLSX, DOCX, MSG and scanned PDFs #23).
• Annahmen: siehe Impact Manifest.
• Nächster kleinster Schritt: Review durch den Orchestrator.

Was ist passiert (Klartext)

Die KI liest jetzt auch Excel-Tabellen (zeilenweise), Word-Dokumente (Absätze und Tabellenzellen) und Outlook-Nachrichten mit ihren Anhängen. Jede Fundstelle zeigt genau, wo ein Wert steht. Gescannte PDFs können per Texterkennung gelesen werden – solche Werte gelten höchstens als „unsicher"; bei sehr langen Scans werden die ersten 10 Seiten gelesen und der Rest mit Hinweis übersprungen. Ein kaputter Anhang bringt nicht mehr die ganze Anfrage zum Scheitern – die Prüfansicht zeigt, welcher Anhang nicht gelesen werden konnte. Sicherheitsfund unterwegs: Eine präparierte 2-KB-Outlook-Datei konnte den Dienst minutenlang mit Gigabytes Speicher blockieren; das ist jetzt abgefangen (sofortige Ablehnung), zusammen mit weiteren Grenzen für übergroße Dateien.

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: AI-Service (parsing/: document, xlsx, docx, msg, ooxml, budget; pdf OCR; Verifier-Deckel; API/Schemas), Vertrag contracts/ai-service.openapi.yaml (generiert), extraction (Client-Validierung, Speichern der Anhangsfehler), jobs (Worker sendet XLSX/DOCX/MSG), review (Anzeige je Dokument).
• Schnittstellen / Datenänderungen: Vertrag additiv: documentKind + xlsx, docx, msg; Locator xlsx (sheet, row, cellRange), docx (part, paragraph/table, row, cell), msg (Kopf/Text wie E-Mail; Anhänge attachment + inner); pdf.ocr; Reason ocr_only; Warnungen attachment_failed, ocr_pages_skipped; attachments[] mit Fehlercodes inkl. budget_exceeded. Keine Migration (Anhangsfehler im bestehenden JSON extraction_runs.documents).
• Akzeptanzkriterien: alle aus feat(ai-service): XLSX, DOCX, MSG and scanned PDFs #23 – siehe Nachweis.
• Testplan: pytest je Format mit per Skript erzeugten synthetischen Fixtures, Teilfehler, OCR-Deckel, Zip-/Teil-/Verschachtelungsgrenzen, OLE-Bombe, Budget, HTTP-Ebene, Logs ohne Inhalt; Vitest/Integration: Worker verarbeitet XLSX, Anhangsfehler in der Prüfansicht.
• Verifizierte Fakten: openpyxl 3.1.5, python-docx 1.2.0, python-oxmsg 0.0.2 (MIT), olefile 0.47 (BSD) – bereits über docling installiert, direkt gepinnt; extract-msg (GPL) nicht verwendet. Messung (4 vCPU): OCR 8–9 s/Seite, Modelle 164 MB (Hugging Face) + ~31 MB (modelscope.cn).
• Offene Annahmen: decision-needed (feat(ai-service): XLSX, DOCX, MSG and scanned PDFs #23): opt-in PREFETCH_OCR_MODELS im Dockerfile (Infra, Image nicht gebaut) und Host modelscope.cn; OCR standardmäßig aus. Strenger olefile-Modus könnte echte, leicht fehlerhafte .msg ablehnen (keine echte Probe vorhanden).
• Nicht-Ziele: siehe oben.
• Risiken und Rollback: feindliche Dokumente → feste Grenzen + Regressionstests; keine Migration; Rollback per Revert.

Geändert

• services/ai/** (Parser, Budget, Pipeline, Verifier, API, Tests, Fixtures, README, Dockerfile, pyproject.toml/uv.lock), contracts/ai-service.openapi.yaml
• src/features/extraction/{ai-client,ai-service.contract,repository}.ts, src/features/jobs/process-request.ts, src/features/review/review.ts, src/app/requests/[id]/page.tsx
• Tests: tests/integration/{processing,review}.test.ts
• Doku: docs/technical/{architecture,operations}.md, CHANGELOG.md

Nachweis (SYSTEM.md §11)

• verify:changed: AI-Service ruff/format/pyright grün, pytest 387 passed / 2 skipped (brauchen heruntergeladene Modelle)
• verify: lokal grün (Exit 0, Node 24) – Unit 135/135, Integration 98/98, depcruise ohne Verstöße, Build, Audit; CI check: siehe Checks
• verify:full / E2E-Spec: Stapelende (feat(observability): correlated structured logs and full health #45) mit diesem PR: verify:full lokal grün (siehe dort)
• Akzeptanzkriterien feat(ai-service): XLSX, DOCX, MSG and scanned PDFs #23: XLSX mit Zeilen-Locator (dokumentierte Wahl: Zeile) → pytest xlsx; DOCX Absatz/Zelle → pytest docx; MSG Text + Anhänge rekursiv → pytest msg; Scan-PDF OCR, ocr: true, nur-OCR-Beleg höchstens unsicher → pytest OCR-Deckel (auch in Anhängen/Positionen); fehlender Anhang ohne Gesamtfehler, Fehler gespeichert und angezeigt → pytest Teilfehler + Integration „keeps failed attachments…"; Modell-Downloads und CPU-Latenz gemessen → oben und in operations.md
• Manueller Prüfnachweis: –
• Frischer Review (P1 vor Ready-for-review; Architektur/API/DB immer): unabhängiger Security-Review mit Probe-Dokumenten – 1 Blocker (OLE-Bombe), 4 should-fix, 4 nits – alle behoben/begründet (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/operations.md, services/ai/README.md
  • Architekturkarte: docs/technical/architecture.md
  • ADR: –
  • CHANGELOG [Unreleased] (sichtbares Feature oder Verhalten – im selben PR, nie „später")

Entferntes oder Umbenanntes: Test test_outlook_msg_is_rejected_for_now durch MSG-Tests ersetzt; test_ocr_page_cap durch „erste 10 Seiten + Warnung" ersetzt (bewusste Verhaltensänderung aus dem Review)

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: src/features/extraction/ai-service.contract.ts (592 Zeilen) ist von openpyxl-unabhängig generiert (pnpm contract:types aus dem OpenAPI-Vertrag) und wird nie von Hand bearbeitet; der Drift-Test sichert die Übereinstimmung.
• 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: docling-Readern für XLSX/DOCX/Mail; gefunden: liefern keine Zell-/Absatz-/Zeilenpositionen → eigene Parser auf openpyxl/python-docx/python-oxmsg

Subagent-Einsätze

• AI-Service-Teil in eigenem Worktree (Subagent), Security-Review (read-only, Probes), Security-Fixes (Subagent auf diesem Branch) – vom Hauptagenten zusammengeführt und geprüft.

Risiken / offene Punkte

• decision-needed: PREFETCH_OCR_MODELS (Dockerfile) und Host modelscope.cn.
• Echte .msg-Dateien ungetestet (nur synthetische); RTF-only-Bodies liefern keine Textsegmente.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01DJ5vaKvTYiMvdngT4d3xo1

[Fluory]

Frischer Security-Review (unabhängiger Subagent, read-only, mit Probe-Dokumenten)

Ergebnis: 1 Blocker · 4 should-fix · 4 nits – alle behoben bzw. begründet. Bestätigt per Probe: XXE/Entity-Expansion in DOCX/XLSX sauber abgelehnt (0,01 s, nichts gelesen), Zip-Grenzen vor der Dekompression, keine Makros, Formeln nur gespeicherte Werte, Logs nur Klassen/Codes, Anhangsnamen nur als Text, OCR-Deckel rekursiv (auch Anhänge, Positionen), Segment-IDs eindeutig, Vertrag additiv.

#	Schwere	Befund	Auflösung
1	blocker	OLE-Stream-Bombe: 2-KB-.msg mit Riesen-Stream + FAT-Schleife → 3,4 GB RSS / 54 s, „geparst"	Vor jedem Stream-Lesen: olefile mit DEFECT_INCORRECT, Ablehnung (422 document_unparseable) wenn ein Stream, der Mini-Stream oder die Summe mehr Bytes deklariert als die Datei hat, plus Plausibilität der Sektorzahlen im Header (fing eine zweite Hängevariante). Probe jetzt in 0,0 s abgelehnt. Anhänge über der Grenze werden nicht mehr dekodiert. Regressionstest
2	should-fix	60-MB-document.xml (8,8 MB gezippt) innerhalb der Grenzen → 37 s / 1,3 GB	Einzelteile > 16 MiB unkomprimiert werden aus dem Zip-Index abgelehnt; DOCX zählt jeden Absatz/jede Zelle (auch leere) gegen 100.000. Test
3	should-fix	kein Gesamtbudget je Dokument (viele gescannte Anhänge → Minuten)	gemeinsames Budget je Dokument (parsing/budget.py): 100 Anhänge, 128 MiB entpackt, 100 PDF-Seiten, 10 OCR-Seiten; Überziehende Anhänge → budget_exceeded, Rest wird geliefert. Test
4	should-fix	> 10 Seiten ohne Text ließ das ganze PDF scheitern	erste 10 werden per OCR gelesen, der Rest übersprungen mit Warnung ocr_pages_skipped (Test ersetzt, Verhalten bewusst geändert)
5	should-fix	Anhangsfehler wurden verworfen, nirgends angezeigt	TS: fehlgeschlagene Anhänge (Name, Code) und die OCR-Warnung werden je Dokument gespeichert und in der Prüfansicht angezeigt („⚠ Anhang „…" konnte nicht gelesen werden – bitte im Original prüfen"). Integrationstest
nits	–	python-oxmsg _storage, doppeltes Öffnen, modelscope-Checksums, fehlende Probe-Tests	Pin + Kommentar; doppeltes Öffnen bleibt (Bibliotheken brauchen Rohbytes); Modell-Host in decision-needed #23; Probe-Fälle als Regressionstests

Danach: AI-Service ruff/format/pyright grün, pytest 387 passed / 2 skipped; pnpm verify lokal grün (Unit 135/135, Integration 98/98). Restrisiko: der strengere olefile-Modus könnte echte, leicht fehlerhafte Outlook-Dateien ablehnen – ohne echte Probe ungetestet (README).

---

Generated by Claude Code