breakpilot-lehrer/docs-src/services/klausur-service/OCR-Kombi-Pipeline.md

OCR Kombi Pipeline - Modulare 11-Schritt-Architektur

Version: 1.0.0 Status: Phase 1 implementiert (Grundgeruest + DB) URL: https://macmini:3002/ai/ocr-kombi

Uebersicht

Die OCR Kombi Pipeline ist der Nachfolger des OCR-Overlay-Monolithen (/ai/ocr-overlay). Sie zerlegt den OCR-Prozess in 11 modulare Schritte mit je einer eigenen Komponente pro Frontend- und Backend-Datei. Ziel: schnelles Debugging, klare Verantwortlichkeiten, Multi-Page-Dokument-Unterstuetzung.

Primaerer Modus: Kombi (PaddleOCR + Tesseract) — der einzige Modus, den der User nutzt.

Warum ein Refactor?

Problem (alt)	Loesung (neu)
page.tsx = 751-Zeilen-Monolith mit 3 Modi	page.tsx = ~140-Zeilen-Orchestrator, je 1 Datei pro Step
Upload, Orientierung und Page-Split in einem Step	3 separate Steps mit eigener Logik
Keine Multi-Page-Dokument-Unterstuetzung	document_group_id + page_number auf DB-Ebene
OCR intransparent (eine Blackbox)	3-Phasen-Fortschritt + Engine-Attribution pro Wort (geplant)
grid_editor_api.py = 1801 Zeilen	4 Module + Orchestrator (geplant)

---

Pipeline-Schritte

#	Step	Frontend	Backend	Beschreibung
1	Upload	StepUpload.tsx	step_upload.py	Bild/PDF hochladen, Titel, Kategorie. Multi-Page-PDF → N Sessions
2	Orientierung	StepOrientation.tsx	(shared)	Rotation 90/180/270 erkennen + korrigieren
3	Seitentrennung	StepPageSplit.tsx	(shared)	Doppelseiten erkennen + splitten
4	Begradigung	StepDeskew.tsx	(shared)	Hough Lines + Word Alignment
5	Entzerrung	StepDewarp.tsx	(shared)	Shear-Korrektur (Vertikalkanten-Drift)
6	Zuschneiden	StepContentCrop.tsx	(shared)	Scanner-Raender entfernen (nach Begradigung!)
7	OCR	StepOcr.tsx	(shared)	Tesseract + PaddleOCR + Merge
8	Strukturerkennung	StepStructure.tsx	(shared)	Boxen, Zonen, Farben, Grafiken
9	Grid-Aufbau	StepGridBuild.tsx	(shared)	Strukturiertes Grid aus OCR + Struktur
10	Grid-Review	StepGridReview.tsx	(shared)	Excel-Editor, IPA, Silben, Korrekturen
11	Ground Truth	StepGroundTruth.tsx	(shared)	Validierung + GT-Markierung

!!! note "Crop nach Dewarp" Seitentrennung (Step 3) passiert vor Begradigung — richtig, weil jede Haelfte unabhaengig begradigt wird. Der Content-Crop (Step 6) bleibt nach Dewarp, weil content-basierter Crop auf geradem Bild besser funktioniert.

---

Multi-Page-Dokument-Gruppierung

Problem

Ein Lehrer scannt 10 Vokabelseiten als eine PDF-Datei. Im Endnutzer-Frontend soll das ein zusammenhaengendes Dokument sein. Alle Seiten muessen spaeter zu gemeinsamen Lern-Units verarbeitet werden koennen.

Loesung: document_group_id + page_number

Zwei neue Felder auf ocr_pipeline_sessions (Migration 009_add_document_group.sql):

ALTER TABLE ocr_pipeline_sessions
    ADD COLUMN IF NOT EXISTS document_group_id UUID,
    ADD COLUMN IF NOT EXISTS page_number INT;

Upload-Typ	document_group_id	page_number
Einzelbild	neues UUID	1
Multi-Page-PDF (10 Seiten)	gleiches UUID fuer alle 10	1..10
Doppelseiten-Split von S. 3	gleiches UUID	neue S. 3 + S. 4, Rest umkontiert

Benennung

Upload-Titel "Vokabeln Unit 3" erzeugt:

• "Vokabeln Unit 3 — S. 1"
• "Vokabeln Unit 3 — S. 2"
• ...
• "Vokabeln Unit 3 — S. 10"

Session-Liste im Admin

Gruppierte Anzeige: Ein Dokument-Header ("Vokabeln Unit 3, 10 Seiten") mit aufklappbaren Einzel-Sessions darunter. Jede Session hat eigenen Pipeline-Status.

---

API-Endpoints

Neue Endpoints (OCR Kombi)

Methode	Pfad	Beschreibung
POST	/api/v1/ocr-kombi/upload	Upload: Einzelbild oder Multi-Page-PDF
GET	/api/v1/ocr-kombi/documents/{group_id}	Alle Sessions einer Dokumentgruppe

Bestehende Endpoints (wiederverwendet)

Die Kombi-Pipeline nutzt alle bestehenden Endpoints aus /api/v1/ocr-pipeline/:

Methode	Pfad	Step
POST	/sessions	Upload (Legacy, Einzelbild)
POST	/sessions/{id}/orientation	Orientierung
POST	/sessions/{id}/page-split	Seitentrennung
POST	/sessions/{id}/deskew	Begradigung
POST	/sessions/{id}/dewarp	Entzerrung
POST	/sessions/{id}/crop	Zuschneiden
POST	/sessions/{id}/paddle-kombi	OCR (Kombi)
POST	/sessions/{id}/detect-structure	Strukturerkennung
POST	/sessions/{id}/build-grid	Grid-Aufbau
POST	/sessions/{id}/save-grid	Grid speichern
GET	/sessions/{id}/grid-editor	Grid laden
POST	/sessions/{id}/mark-ground-truth	GT markieren

---

Dateistruktur

Frontend

admin-lehrer/app/(admin)/ai/ocr-kombi/
├── page.tsx                    # ~140 Zeilen, Orchestrator mit Suspense-Boundary
├── types.ts                    # KOMBI_V2_STEPS (11 Steps), DocumentGroup-Types, OCR-Transparenz-Types
└── useKombiPipeline.ts         # Hook: Session-State, Step-Navigation, Dokument-Gruppierung

admin-lehrer/components/ocr-kombi/
├── KombiStepper.tsx            # 11-Step-Indikator (kompakt, scrollbar)
├── SessionList.tsx             # Gruppierte Session-Liste (Dokumentgruppen aufklappbar)
├── SessionHeader.tsx           # Aktive Session: Name + Kategorie + GT-Badge
├── StepUpload.tsx              # Drag-Drop + Titel + Kategorie-Auswahl
├── StepOrientation.tsx         # Wrapper → shared StepOrientation
├── StepPageSplit.tsx           # Doppelseiten-Erkennung + Auto-Advance
├── StepDeskew.tsx              # Wrapper → shared StepDeskew
├── StepDewarp.tsx              # Wrapper → shared StepDewarp
├── StepContentCrop.tsx         # Wrapper → shared StepCrop
├── StepOcr.tsx                 # Wrapper → PaddleDirectStep (kombi endpoint)
├── StepStructure.tsx           # Wrapper → shared StepStructureDetection
├── StepGridBuild.tsx           # Auto-Trigger build-grid + Ergebnis-Anzeige
├── StepGridReview.tsx          # Wrapper → shared StepGridReview (mit saveRef)
└── StepGroundTruth.tsx         # GT-Markierung mit Auto-Save

Backend

klausur-service/backend/ocr_kombi/
├── __init__.py
├── router.py                   # Composite Router (/api/v1/ocr-kombi)
└── step_upload.py              # Multi-Page-PDF → N Sessions + document_group_id

Shared (wiederverwendet)

Die Kombi-Pipeline nutzt alle bestehenden Backend-Module:

• orientation_crop_api.py — Orientierung, Page-Split, Crop
• ocr_pipeline_api.py — Deskew, Dewarp
• ocr_pipeline_ocr_merge.py — PaddleOCR + Tesseract Merge
• grid_editor_api.py — Grid-Aufbau + Editor
• ocr_pipeline_session_store.py — DB-Layer (erweitert um document_group_id)
• Alle cv_*.py — CV-Algorithmen

Migration

migrations/009_add_document_group.sql  # document_group_id UUID + page_number INT + Index

---

Implementierungsphasen

Phase	Status	Beschreibung
1: Grundgeruest + DB	Implementiert	DB-Migration, Types, Hook, Stepper, SessionList, page.tsx, Navigation, Backend-Router
2: Vorverarbeitungs-Steps	Geplant	Multi-Page-PDF-Upload, Orientierung ohne Upload, Seitentrennung mit document_group_id
3: OCR-Transparenz	Geplant	3-Phasen-Fortschritt, Engine-Attribution pro Wort, Farbkodierung
4: Grid-Pipeline aufteilen	Geplant	grid_editor_api.py → 4 Module + Orchestrator
5: Restliche Steps	Geplant	Structure, GridBuild, GridReview, GroundTruth voll integriert
6: Features migrieren	Spaeter	LLM-Review-Streaming, Labeling-Mode, Bild-Generierung
7: Aufraeumen	Spaeter	/ai/ocr-overlay und /ai/ocr-pipeline loeschen

---

OCR-Transparenz (Phase 3, geplant)

3-Phasen-Fortschritt in Step 7

1. "Tesseract laeuft..." (Fortschrittsbalken)
2. "PaddleOCR laeuft..." (Fortschrittsbalken)
3. "Merge laeuft..." (Fortschrittsbalken)

Engine-Attribution pro Wort

Vergleichsansicht mit Farbkodierung:

Farbe	Bedeutung
Gruen	Beide Engines einig
Blau	Nur PaddleOCR
Orange	Nur Tesseract
Gelb	Konflikt, PaddleOCR gewaehlt
Rot	Konflikt, Tesseract gewaehlt

Geplanter Endpoint

POST /sessions/{id}/ocr-kombi-transparent
→ { raw_tesseract, raw_paddle, merged, engine_source_per_word }

---

Grid-Pipeline-Aufteilung (Phase 4, geplant)

grid_editor_api.py (1801 Zeilen) wird aufgeteilt in:

Modul	Inhalt	~Zeilen
grid_build_filters.py	Margin, Footer, Header, Exclude, Grafik-Filter	~200
grid_build_zones.py	Box-Detect, Page-Zones, Vert-Dividers	~250
grid_build_columns.py	Spalten-Clustering + Union-Merge + Zone-Grids	~300
grid_build_postprocess.py	Row/Cell-Postprocessing, IPA, Farben, Dictionary	~500

grid_editor_api.py wird zum schlanken Orchestrator.

---

Verhaeltnis zu bestehenden Pipelines

Pipeline	Route	Status	Beschreibung
OCR Kombi	/ai/ocr-kombi	Aktiv (neu)	Modulare 11-Schritt-Pipeline
OCR Overlay	/ai/ocr-overlay	Legacy	751-Zeilen-Monolith, 3 Modi
OCR Pipeline	/ai/ocr-pipeline	Legacy	Volle Pipeline mit Spalten
OCR Compare	/ai/ocr-compare	Eigenstaendig	Methoden-Vergleich

Die alte OCR Overlay (/ai/ocr-overlay) bleibt waehrend des gesamten Umbaus parallel nutzbar fuer A/B-Tests. Sobald die Kombi-Pipeline feature-complete ist, werden die alten Pipelines in Phase 7 entfernt.

---

Aenderungshistorie

Datum	Version	Aenderung
2026-03-26	1.0.0	Phase 1: Grundgeruest mit 11-Step-Architektur, DB-Migration (document_group_id, page_number), Backend-Router mit Multi-Page-Upload, Frontend mit SessionList (gruppiert), KombiStepper, 13 Step-Komponenten, useKombiPipeline Hook, Navigation