Betrieb

Betrieb in einem Satz

Ein Scan-Durchgang läuft von Kamera-Auslösen bis zur fertig benannten Datei vollautomatisch — der Nutzer wählt nur Vorlage und Partitur; alles andere entscheidet die Pipeline.

Dieses Kapitel beschreibt den Tagesbetrieb: Buchscan und Einzelblatt-Scan von Anfang bis Ende, mit allen Zwischenzuständen, Rückmeldungen und Nachbearbeitungsschritten, die der Nutzer sieht oder auslösen kann.

1 Gesamtablauf im Überblick

flowchart TD
    phone["iPhone CameraService\n(48 MP + LiDAR)"] --> lock["DocumentDetector lock\nstage1→stage2"]
    lock --> shutter["pageCaptured\n+ Tiefensnapshot"]
    shutter --> link["ReproLink TCP 8765\nFrame-Transfer"]
    link --> backstage["BackstageController\nEmpfang + Dispatch"]
    backstage --> pipeline["PDAIBackendPipeline\nRektifizierung + Ton + OCR"]
    pipeline --> geo["PageGeometry\nGutterFinder + Quality-Gates"]
    geo --> tone["ArchivalToneEngine\nFlat-Field + S-Kurve"]
    tone --> vision["OCRService Vision\nTranskript lokal"]
    vision --> store["Documents/Scans\nmaster NNN.heic + page NNN/"]
    store --> batch["PartiturClient\nasync Batch 5401"]
    batch --> xml["ext.xml + receipt.json\nbzw. page.json"]
    xml --> rename["renamePageArtefacts\nnur Einzelblatt"]

Der Gesamtfluss endet im Buchmode mit einem benannten Ordner und XML je Seite; im Einzelblatt-Modus zusätzlich mit Ordner- und Dateiumbenennung nach [klasse]-Firma-Datum-Betrag-Währung.

2 Buchscan — Schritt für Schritt

2.1 1. Vorbereitung (einmalig je Sitzung)

Im rechten Inspektor:

Vorlage: Buch
Ausrichtung: topOnRight (Standard, iPhone quer mit Oberkante rechts)
Buchtyp-Overlay wählen, falls für dieses Buch bereits einer existiert (z. B. „Hevelius”)
Batch-OCR-Toggle: Ein (Standard) für Gemini-Batch mit 50-%-Kostenrabatt; Aus für sofortigen Sync-Pfad (Ollama/local)

Capture-Settings werden nach jeder Aufnahme automatisch persistiert und bei der nächsten Sitzung wiederhergestellt (CaptureSettingsStore).

2.2 2. Aufnehmen

iPhone über dem Buch, App öffnen → Kamera wird gestartet. Sobald der Rahmen stabil erkannt und die Lock-Bedingungen erfüllt sind (stage2Locked), leuchtet der Sucher-Rand grün auf.

Auslösen: Leertaste am Mac (Fernauslöser), Volume-Taste am iPhone, oder Tap auf den Shutter-Button. Die App löst nur aus, wenn der Rahmen gesperrt ist.

Nach dem Auslösen: - Der Master (HEIC, 48 MP) wird per ReproLink an den Mac übertragen. - Backstage zeigt sofort einen Platzhalter-Thumb in der Seitenleiste (Busy-Zustand, keine Wartezeit für den Nutzer). - Die Pipeline startet im Hintergrund: Geometrie → Tonwert → Vision-OCR. - Sobald Vision-OCR abgeschlossen ist, erscheint das verarbeitete Seitenbild im Thumb.

2.3 3. Qualitäts-Chip „Nachbessern”

Jede Spreite bekommt nach dem Verarbeiten ein Qualitäts-Gate-Ergebnis:

Chip	Bedeutung
(kein Chip)	Alle Quality-Gates bestanden
Nachbessern (gelb)	Residualneigung > 0,15° oder Scale-Mismatch > 6 %
Neu aufnehmen (rot)	Paper-Coverage < 35 % oder Score-Gate fehlgeschlagen

Ein Klick auf den Chip öffnet die Spreite mit Diagnose im Detailbereich. Dort ist auch ein direktes Reshoot möglich.

2.4 4. Ergebnis und Ablage

Für jede Doppelseite entstehen in ~/Documents/Scans/<Dokumentname>/:

masters/
  master_NNN.heic         — 48-MP-Kamerabild
page_NNN/                 — Linke Seite
  page_NNN.jpg            — Verarbeitetes Seitenbild
  page_NNN.json           — GeometryReport + ToneReport + OCRResult
  page_NNN.txt            — Flachtext-Transkript (Vision-OCR)
  page_NNN.ext.xml        — Extended-OCR-Ergebnis (DTD-konformes Buch-XML)
  page_NNN.ext.txt        — Flachtext aus ext.xml
page_NNN+1/               — Rechte Seite (analog)
metadata/
  page_selection.json     — Pagenum-Overrides, Reihenfolge-Korrekturen (nie direkt in XML)
document.json             — Dokumentregister, Partitur-Status

2.5 5. Extended OCR und Partitur

Extended OCR läuft asynchron über den Orchestrator:

PartiturClient sendet alle Seitenbilder als Batch an den repro_extended_ocr_agent.
Gemini-Batch (gemini-3.8-flash) verarbeitet mit 50-%-Kostenrabatt; typische Queue-Zeit: 3–10 Min.
Nach Rückgabe schreibt der Client page_NNN.ext.xml und page_NNN.ext.txt.
Der XML-Tab in PageDetailView zeigt das formatierte Buchblatt-XML (Warm-Papier-Stil).

„Partitur anwenden” löst einen separaten Lauf für Buch-Bibliographie (repro_book_agent) oder Buchtyp-Klassifizierung (repro_booktype_agent) aus.

⌘⇧T startet OCR für alle Seiten neu, ohne die verarbeiteten Seitenbilder zu verändern.

3 Einzelblatt-Scan — Schritt für Schritt

3.1 1. Vorlage wählen

Im Inspektor: Vorlage → Einzelblatt. Der Rahmen-Erkennungsmodus wechselt auf Belegsuche: Die App erkennt das weiße Rechteck auf dem schwarzen Untergrund und zoomt darauf, statt eine A4-Buchspreite zu erwarten.

3.2 2. Aufnehmen

Beleg auf schwarzem Untergrund, ausreichend Abstand wählen (kleine Belege wie Bustickets können bis 8 cm herangehen). Sucher-Rand leuchtet grün bei stabiler Erkennung.

Nach dem Auslösen erscheint der Beleg sofort im Kontaktbogen. Die Vision-OCR läuft on-device in ≤ 3 s.

3.3 3. Sofortige Benennung aus Transkript

ReceiptClassifier extrahiert aus dem Vision-OCR-Transkript: - Händlername (bereinigt, max. 20 Zeichen) - Datum (TT-MM-JJJJ) - Gesamtbetrag (2 Dezimalstellen) - Währung (EUR, CHF, …) - Klasse (Taxi, parking, pharma, usw. — oder leer für offene Klasse)

Der Ordner wird sofort umbenannt: [klasse]-Firma-Datum-Betrag-Währung (z. B. [parking]-Schadowstrasse-15-08-2026-3.50-EUR).

Erfolgs-Feedback: Wenn Extraktion und Umbenennung erfolgreich sind, ertönt ein kurzer heller Ton.

Fehler-Feedback: Scheitert die Strukturextraktion (kein erkennbarer Betrag, kein Datum), ertönt ein dunkles Brummen — Signal zum Wiederholen der Aufnahme.

3.4 4. Dubletten erkennen und aufräumen

Wenn zwei Aufnahmen denselben Datei-Stem (Firma + Datum + Betrag) ergeben, erscheint ein 🔁-Icon auf beiden Thumbs in der Seitenleiste. Klick darauf öffnet DuplicateSelectionView: beide Seiten nebeneinander, „Behalten” / „Archivieren” je Seite. Archivierte Seiten landen in <Dokumentordner>/archive/.

3.5 5. Extended OCR (Beleg-XML und JSON)

repro_receipt_ocr_agent verarbeitet sowohl Bild als auch Transkript: - Schreibt <stem>.ext.xml (DTD repro_receipt.dtd) mit vollem Beleg-Schema: Händler, Adresse, Positionen, Steuern, Zahlung, TSE, Reise-/Treibstoff-/Parkdaten. - Schreibt <stem>.receipt.json — Flat-Contract aller DTD-Attribute für Mac-App-Konsum. - DTD-Validierungsstatus und eventuelle Fehler stehen in den dtd_valid/dtd_errors-Attributen der Wurzel.

Der XML-Tab zeigt das Beleg-XML als stilisierten Thermobon (warm, kompakt, Klasse-Badge), der Daten-Tab zeigt receipt.json als lesbares Key-Value-Layout.

4 Reprocessing und OCR-Neulauf

4.1 „Neu verarbeiten (aus Master)”

Rechtsklick auf eine Spreite im Kontaktbogen → „Neu verarbeiten”. Startet die vollständige Pipeline neu, beginnend mit dem gespeicherten Master, ohne den Master zu verändern.

Mit dem Schraubenschlüssel-Symbol oben in der Backstage startet der Neuverarbeitungs-Sweep für alle Spreiten des Dokuments. Nach dem Sweep läuft automatisch Extended-OCR für alle geänderten Seiten.

4.2 `⌘⇧T` — OCR für alle Seiten erneuern

Startet Extended-OCR für alle Seiten neu, ohne Seitenbilder neu zu erzeugen. Nützlich nach Orchestrator-Update oder Partitur-Änderung.

5 Capture-Settings-Persistenz

Die folgenden Einstellungen werden automatisch nach jeder Änderung persistiert und beim nächsten Start wiederhergestellt:

Einstellung	Schlüssel	Wertebereich
Vorlage	`captureMode`	`book` / `receipt`
Buchausrichtung	`orientation`	`topOnRight` / `topOnLeft` / `topOnTop`
Kopierständer-Modus	`copyStandMode`	Bool
Rahmen-Padding	`framePadding`	0 %–20 %, Standard 8 %
Flat-Field	`flatFieldEnabled`	Bool
Batch-OCR	`batchOCREnabled`	Bool
Orchestrator-URL	`FamulusReproOrchestratorURL`	URL-String

6 Batch-OCR Monitoring

Der linke Seitenleisten-Fußbereich zeigt: - „Batch läuft…“ mit geschätzter ETA (aus historischen Queue-Zeiten) - Fertig-Badge, sobald alle offenen Seiten das Batch-Ergebnis haben

7 Laufende QUITTUNGEN-Sammlung

Als Beispiel für den Alltag: der Scan-Ordner ~/Documents/Scans/QUITTUNGEN/ enthält alle Einzelbelege der laufenden Buchführung. Jeder neue Scan landet dort, wird sofort benannt und der Extended-OCR-Batch-Queue zugestellt. Die OCR-Ergebnisse stehen nach wenigen Minuten als DTD-konformes Beleg-XML und Flat-JSON zur Verfügung.

1 Gesamtablauf im Überblick

2 Buchscan — Schritt für Schritt

2.1 1. Vorbereitung (einmalig je Sitzung)

2.2 2. Aufnehmen

2.3 3. Qualitäts-Chip „Nachbessern”

2.4 4. Ergebnis und Ablage

2.5 5. Extended OCR und Partitur

3 Einzelblatt-Scan — Schritt für Schritt

3.1 1. Vorlage wählen

3.2 2. Aufnehmen

3.3 3. Sofortige Benennung aus Transkript

3.4 4. Dubletten erkennen und aufräumen

3.5 5. Extended OCR (Beleg-XML und JSON)

4 Reprocessing und OCR-Neulauf

4.1 „Neu verarbeiten (aus Master)”

4.2 ⌘⇧T — OCR für alle Seiten erneuern

5 Capture-Settings-Persistenz

6 Batch-OCR Monitoring

7 Laufende QUITTUNGEN-Sammlung

4.2 `⌘⇧T` — OCR für alle Seiten erneuern