Bon Dossier: drei Versionen, ein System zur lokalen Belegauswertung

„Bon Dossier“ wurde nicht wegen einer komplizierten Benutzeroberfläche anspruchsvoll. Die Schwierigkeit liegt darin, dass die reale Welt selten saubere Daten liefert. Kassenbons sind schmal, gewölbt, verblasst, gefaltet oder schlecht beleuchtet fotografiert. Sie enthalten viele Sprachen, Steuerübersichten, Treueprogramminformationen, Terminaldaten, Rabatte, Erstattungen, barcodeähnliche Nummern und Summen, die sich manchmal über mehrere Zeilen verteilen. Eine einfache OCR-Demo kann Text erkennen. Eine produktionsreife App muss entscheiden, welche Angaben tatsächlich zutreffen.

Das Projekt entwickelte sich deshalb in drei praktischen Versionen. Dabei geht es nicht bloß um Vermarktungsstufen, sondern um technische Entwicklungsphasen: zuerst das Fundament, dann die Erkennungs-Engine und schließlich die produktionsreife Plattform. Jede Version löste eine andere Art von Problem und machte die nächste Komplexitätsebene sichtbar.

Version 1

Das Fundament

Ein Swift-Paket, ein Fachmodell, ein Parser, eine Exportschicht und eine SwiftUI-Oberfläche machten Belege testbar, noch bevor Kamera- und Synchronisierungsschichten existierten.

Version 2

Die Erkennungs-Engine

Vision OCR, Core-ML-Klassifikatoren, Layoutzonen nach YOLO-Vorbild, das Zusammenführen von Artikelzeilen, verbindliche Validierung und lokales Lernen ersetzten einfache Auswertungsregeln.

Version 3

Die produktionsreife Plattform

Core Data, CloudKit, Backups, Teilen-Erweiterungen, Exporte, Archivmetadaten, macOS, Audits und Trainingsanwendungen machten aus der Erkennung ein Produkt.

Die Ausgangsvorgabe: privat, lokal und überprüfbar

Die wichtigste Architekturentscheidung fiel noch vor der Entwicklung des Scanners: ReceiptVault musste nützlich sein, ohne persönliche Finanzdokumente auf einen Server hochzuladen. Damit schied der einfache Weg aus, Bilder an einen Online-OCR- oder Sprachmodelldienst zu senden. Die fertige App sollte Apple Vision, VisionKit, Core ML, Swift-Parser und deterministische Validierung nutzen — vollständig lokal. iCloud durfte das private Archiv des Benutzers synchronisieren, aber ein eigenes „Bon Dossier“-Backend sollte es nicht geben.

Diese Datenschutzvorgabe prägte alle späteren Abläufe. Trainingsdaten wurden als lokales Projektmaterial behandelt. Korrekturen aus Prüfungen wurden als lokale Beispiele gespeichert. Neue Modellkandidaten wurden erst nach Berichten und Regressionstests übernommen. Selbst die Apple-Foundation-Models-Schicht wurde als optionale lokale Nachprüfung mit strenger JSON-Schemavalidierung und Rückfall auf das mitgelieferte Belegmodell ausgelegt.

Version 1: das Grundgerüst vor der Kamera entwickeln

Die erste Version war bewusst unspektakulär. Statt mit einer Kameraansicht zu beginnen und darauf zu hoffen, dass der Rest nachfolgt, startete das Projekt mit einem testbaren Swift-Paket namens ReceiptVaultCore. Es enthielt das Fachmodell, den Belegparser, die Kategorisierung, Duplikaterkennung, Exportcode und später den Großteil der Erkennungs- und Speicherlogik. Das erste Ziel war einfach: Das Belegdatenmodell sollte ausführbar und testbar sein, ohne vom Simulator, Kameraberechtigungen oder laufender OCR abzuhängen.

Das Kernmodell entstand rund um ParsedReceipt: Händler, Adresse, Kaufdatum, Währung, Gesamtbetrag, Zwischensumme, Steuer, Zahlungsart, Belegnummer, OCR-Text, Notizen, Artikelpositionen, Scandateien und Prüfstatus. Darauf folgten TSV- und Excel-Export, Duplikatgruppierung, automatische Kategoriezuordnung, Fristerinnerungen und Qualitätsprüfung. Die Oberfläche konnte Belege damit als echte Datensätze behandeln statt als lose OCR-Zeichenketten.

Die SwiftUI-Oberfläche folgte demselben Prinzip. Auf dem iPhone gab es Tabs für Archiv, Scannen, Auswertungen und Einstellungen. Das iPad nutzte eine Seitenleiste und geteilte Navigation. Die Ansichten verwendeten Systemcontainer wie TabView, NavigationStack, NavigationSplitView, List und Section statt eines eigenen UI-Frameworks. So blieb die App nativ, zugänglich und überprüfbar.

Die erste wichtige Prozessentscheidung: Die App sollte aus kleinen, überprüfbaren Schichten entstehen. Tests des Fachmodells kamen vor der Kameraintegration. Das Verhalten des Parsers wurde durch feste Testdaten abgesichert. Skripte erzeugten und schützten das Xcode-Projekt. Build- und Testbefehle wurden dokumentiert, damit sich das Projekt reproduzieren ließ, statt manuell in Xcode betreut werden zu müssen.

Werkzeuge in Version 1

• Swift 6 und SwiftPM für das gemeinsame Kernmodul.
• Erzeugung des Xcode-Projekts durch Ruby-Skripte, einschließlich Schutzmechanismen für die Quellcodesynchronisierung.
• XCTest für Regressionstests von Parser, Export, Archiv und Quellcode.
• Build-Skripte für Simulatorprüfungen auf iPhone und iPad.
• Feste Belegbilder und rekonstruierte Texte als Testdaten, um Parseränderungen messbar zu machen.
• Eine laufend gepflegte Statusdokumentation für abgeschlossene, laufende und blockierte Arbeiten.

Eine frühe Infrastrukturhürde waren auseinanderlaufende Werkzeugversionen: Das über die Kommandozeile installierte Swift passte nicht immer zum Xcode-SDK. Die Lösung war ausdrücklich festgelegt und wiederholbar: Paketbefehle mit xcrun swift test und der von Xcode ausgewählten Werkzeugkette ausführen. Das klingt unscheinbar, verhinderte aber, dass Umgebungsfehler fälschlich als Regressionen der App erschienen.

Version 2: vom OCR-Text zum Verständnis des Belegs

Die zweite Version begann mit der Erkenntnis, dass OCR allein noch kein Produkt ist. Apple Vision kann viele Zeilen eines Kassenbons lesen, weiß aber nicht, welche Zahl der Endbetrag ist, welche Zeile eine Umsatzsteuer-Bemessungsgrundlage enthält, welcher Betrag ein Rabatt ist, welches Datum vom Zahlungsterminal stammt oder wo die Artikelaufstellung beginnt. „Bon Dossier“ brauchte eine Engine zur inhaltlichen Belegauswertung.

Für die Dokumentaufnahme auf iPhone und iPad kam VisionKit zum Einsatz. Originalscans blieben als Dateien erhalten, während OCR und Verarbeitung beschnittene oder gedrehte Versionen nutzen konnten. OCR-Ergebnisse wurden als Eingabe behandelt, nicht als feststehende Wahrheit. Erkannte Zeilen, ihre Begrenzungsrahmen, Konfidenzwerte und später Informationen zur Dokumentstruktur gingen in eine hybride Verarbeitungskette ein: Lokale Core-ML-Modelle schlugen Rollen und Bereiche vor, Swift-Parser stellten Kandidaten zusammen, und deterministische Prüfungen entschieden, welche Kandidaten akzeptabel waren.

Damit wurde aus einer App mit Auswertungsregeln ein Offline-System für maschinelles Lernen. Die Codebasis erhielt Skripte für erste automatische Annotationen, das Training von Zeilenklassifikatoren, Detektor- und Lokalisierungsmodellen, die Vorbereitung von YOLO-Datensätzen, die Bewertung unbekannter Layouts, die Erzeugung von Negativbeispielen ohne Belege, die Prüfung von Annotationsstrukturen, die Ableitung spezialisierter Datensätze und Kontrollen nach dem Training. Die produktive App blieb lokal und deterministisch. Der Entwicklungsablauf wurde jedoch zu einem Kreislauf aus Messen, Eingrenzen, Annotieren, Trainieren, Vergleichen und Freigeben.

Die Erkennungskette

Die wichtigste technische Veränderung: Validierung erhält das letzte Wort

Ein Modell kann Vorschläge machen, ein Parser Zusammenhänge ableiten. Am Ende muss die Rechnung auf dem Beleg aber aufgehen. „Bon Dossier“ machte deshalb die rechnerische Prüfung zum entscheidenden Kriterium: Die Artikelpositionen müssen zum Endbetrag passen, Umsatzsteuer darf nicht doppelt gezählt werden, Zwischensummen und Steuerbemessungsgrundlagen dürfen nicht an die Stelle des Endbetrags treten, und Zahlungs- oder Kartenmetadaten dürfen nicht als Kaufbeträge übernommen werden.

Diese Regel brachte subtile Fehler ans Licht. Bei europäischen Belegen mit enthaltenen Steuern lautet die richtige Prüfung normalerweise total == sum(items), nicht total == items + tax. Letzteres zählt die Umsatzsteuer doppelt und kann gerade den falschen Gesamtbetrag bestätigen. Die Korrektur dieser einen Regel machte die Ergebnisse für eine große Gruppe von Belegen nicht nur plausibel, sondern rechnerisch korrekt.

Weitere Korrekturen waren ebenso konkret: Rabattübersichten verdrängten den Endbetrag nicht mehr, Spaltenüberschriften wie „Price“ und „Total“ führten nicht länger zur Verwechslung von Artikelpreisen und Belegsumme, Steuerbemessungsgrundlagen erhielten keinen Vorrang vor Zahlungsbeträgen, und getrennte Angaben wie „Total“ mit dem Betrag in der nächsten Zeile wurden gezielt behandelt. Das waren keine kosmetischen Parseränderungen, sondern Korrekturen daran, wie die App die Realität abbildet.

Trainingsdaten, ohne uns selbst etwas vorzumachen

Das Projekt unterschied mehrere Annotationsarten, weil nicht alle Trainingsbelege dieselbe Verlässlichkeit haben. Manuell bestätigte Annotationen erhielten Gold-Status. Aus Vision oder App-Backups gewonnene Beispiele wurden als Bootstrap- oder Silberdaten behandelt. Manuelle Korrekturen wurden nachvollziehbar gespeichert. Der Produktionsprozess vermied ausdrücklich, bestätigte YOLO-Annotationen zu überschreiben. Modellkandidaten sollten gegen festgelegte Validierungs- und Testmengen bewertet werden.

Das war nötig, weil Belegerkennung sehr leicht unbemerkt überangepasst werden kann. Ein dokumentierter Fehler machte das Training zonenspezifischer Modelle wertlos: Die Eingabedaten enthielten ein Annotationsmerkmal, das die gesuchte Antwort praktisch schon verriet. Das Modell erhielt damit eine künstliche Rückmeldung. Die Korrektur entfernte dieses Merkmal aus Trainings- und Laufzeiteingaben, sodass die Spezialmodelle ihre Ergebnisse aus echten Merkmalen ableiten mussten. Eine weitere Bereinigung entfernte fest programmierte Händlerabkürzungen und Sonderzuordnungen für OCR-Schreibfehler. Das machte die Ergebnisse ehrlicher und vorübergehend schmerzhafter, legte die verbleibenden Probleme aber offen, statt sie durch Abkürzungen zu verstecken.

Beispielhafte Qualitätsmesswerte aus der Entwicklung

• Ein aktueller Benchmark direkt auf dem Gerät umfasste 728 Belege und 35.361 OCR-Zeilen.
• Die geprüften Erwartungen an die Auswertung wurden bei 545 von 546 geprüften Belegen erfüllt; eine Abweichung beim Datum blieb sichtbar.
• Für die Zeilenklassifikation wurde eine Genauigkeit von 96,3 Prozent gemessen.
• Die durchschnittliche Auswertungszeit lag bei etwa 47,5 ms, das 95. Perzentil bei rund 81,4 ms in der lokalen Verarbeitung ohne Netzwerkzugriff.
• Das Ziel für die Veröffentlichung blieb höher: Eine Automatisierungsrate nahe 99 Prozent erfordert mehr verifizierte echte Belege und Annotationen der Artikelzeilen.

Version 3: aus der Erkennung ein Produkt machen

Die dritte Version umfasste alles, was eine kluge Engine praktisch nutzbar macht: dauerhafte Speicherung, Synchronisierung, Suche, Dateiimport, Backups, Exporte, Einstellungen, Datenschutzmanifeste, App-Store-Hinweise, Barrierefreiheit, Leistung, Lokalisierung, macOS und Betriebswerkzeuge. Hier scheitern viele Prototypen, denn ein großer Teil der Produktentwicklung bleibt für Benutzer unsichtbar, bis etwas nicht funktioniert.

Die Speicherung begann mit einem lokalen JSON-Archiv, weil es einfach, gut einsehbar und schnell erweiterbar war. Für die frühe Phase war das richtig, für ein privates iPhone-/iPad-Archiv reichte es jedoch nicht. Für den Produktivbetrieb ging die Entwicklung zu einer Repository-Abstraktion mit Core Data als Hauptspeicher und NSPersistentCloudKitContainer für die private iCloud-Synchronisierung über. Originalscans, Prüfsummen, Vorschaubilder und Belegmetadaten wurden dabei ausdrücklich gemeinsam verwaltet — ein Beleg ist mehr als nur eine Tabellenzeile.

Auch das Archiv wurde mehr als eine Liste. Es erhielt eine an Mail angelehnte Organisation: Alle Belege, Ordner, intelligente Ordner, Markierungen, bereichsbezogene Suche, Auswahl, Verschieben, Export und Übergabe an Mail. Der Import wurde auf Dateien, Mail, Bilder, PDFs und Textinhalte erweitert. App Intents und Deep Links konnten Benutzer zu Archiv, Scannen, Auswertungen und Einstellungen führen. Spotlight und die Teilen-Erweiterung machten Belege zu integrierten Systeminhalten statt zu Daten, die in der App gefangen bleiben.

Core Data und CloudKit: Die Schwierigkeiten lagen im Betrieb

Die Entscheidung für Core Data war pragmatisch. SwiftData eignet sich gut für Prototypen, doch ReceiptVault brauchte ausdrückliche Kontrolle über Migrationen, Binärdateien, CloudKit-Diagnose, Konfliktbehandlung und die Weiterentwicklung des Schemas über viele Jahre. Core Data bot diese Möglichkeiten. Die Oberfläche konnte weiterhin eine klare Repository-Schnittstelle verwenden, während die Speicherschicht die Migration aus JSON und die Wiederherstellung fehlender Scandateien übernahm.

Die Betriebsrisiken waren real. Die Initialisierung des CloudKit-Schemas musste programmatisch definierte Entitäten wie Belegdatensätze, Scandateien, Ordner, Markierungen und intelligente Ordner umfassen. Leere Schemata führten zu Teilausfällen. Für Produktions-Builds musste das CloudKit-Schema in die Produktionsumgebung übernommen werden. Die Release-Entitlements mussten für stille Synchronisierungsbenachrichtigungen das produktive APNs verwenden. Diese Themen sind unspektakulär, entscheiden aber darüber, ob die Synchronisierung bei echten Benutzern funktioniert.

Backups, Exporte und der Aufwand für Originalscans

„Bon Dossier“ speichert Finanzunterlagen. Export und Sicherung durften deshalb nicht nachträglich ergänzt werden. Die App erhielt TSV-Export, echten XLSX-Export, den Export gefilterter Archive und ausgewählter Belege, manuelle Sicherung und Wiederherstellung sowie Teilen-Dialoge. Außerdem blieben die Originalscanseiten erhalten, statt die Beweisgrundlage nach der Auswertung zu verwerfen. Das ist die richtige Produktentscheidung, verursacht aber zusätzlichen Speicher- und Leistungsaufwand.

Eine Produktionsprüfung zeigte die Abwägung deutlich: Werden Scanbilder sowohl im Dateisystem als auch als externe Binärdaten in Core Data gespeichert, verdoppelt sich der lokale Speicherbedarf. Vollständige JSON-Backups mit eingebetteten Scans können den Arbeitsspeicher stark belasten, weil sämtliche Scandaten gleichzeitig geladen werden. Der Lösungsweg war ebenso klar: aufwendige Repository- und Sicherungsarbeiten vom Hauptthread verlagern, große Backups als Datenstrom oder blockweise verarbeiten, Vorschaubilder zwischenspeichern und bewusst festlegen, ob Core Data oder das Dateisystem die maßgebliche Quelle der Scandaten ist.

Die macOS-Version war kein bloßer Betrachter

Der macOS-Plan war bewusst anspruchsvoll: keine Begleit-App nur zum Lesen, sondern ein natives Desktop-ReceiptVault mit demselben privaten iCloud-Archiv und derselben Kernlogik. Die Oberfläche besteht aus drei Bereichen: Seitenleiste, Belegliste und Detailansicht. Das Mac-Target verwendet den gemeinsamen Kern, die OCR-/ML-Verarbeitung sowie Archiv-, Export-, Backup- und Synchronisierungslogik weiter. Darstellung, Befehle, Dateiimport und Kameraaufnahme werden an die macOS-Konventionen angepasst.

Damit kamen weitere Aufgaben hinzu: macOS-Entitlements, App Sandbox, Zugriff auf vom Benutzer gewählte Dateien, Datenschutzhinweise für die Kamera, Menübefehle, Planung für die Integrationskamera, native Importdialoge und die Veröffentlichung auf mehreren Plattformen im App Store. Gleichzeitig zeigte sich der Wert der Trennung von ReceiptVaultCore und den plattformspezifischen Oberflächen. Die Bedienung darf sich unterscheiden; die Belegauswertung sollte es nicht.

Die Entwicklungsprozesse dahinter

Das Projekt gelang, weil es nicht als ein einziger großer Funktionsschub organisiert war. Es nutzte schrittweise Umsetzung in Schichten, Quellcodeprüfungen, lokale Skripte, feste Testdaten, Modellberichte und dokumentierte Freigabekriterien. Zu den wichtigsten Ergebnissen gehörten keine sichtbaren Ansichten, sondern Skripte und Berichte, die die Arbeit messbar machten.

Build und Überprüfung

SwiftPM-Tests, Simulator-Builds, Quellcodeschutztests, Prüfungen des Projektgenerators, Lokalisierungsprüfungen, CI-Skripte und manuelle Screenshot-Kontrollen hielten das Produkt auf Kurs.

Daten- und ML-Prozesse

Die Verarbeitung trennte Gold-, Silber- und Bootstrap-Annotationen, bewahrte Begleitdateien, prüfte YOLO-Strukturen, trainierte lokale Modelle und gab Ergebnisse erst nach einem Vergleich frei.

Absicherung des Produkts

Leistungsprüfungen, ein Datenschutzinventar, App-Store-Hinweise, Barrierefreiheitsprüfungen, Synchronisierungsdiagnosen und Kontrollen auf Veröffentlichungshindernisse machten verborgene Fehlerquellen sichtbar.

Beispielhafte Werkzeuge und Techniken

• Swift und SwiftUI: Oberflächen für iPhone, iPad und macOS mit nativen Listen, geteilten Ansichten, Einstellungen und Teilen-Abläufen.
• SwiftPM: ein gemeinsames Kernmodul und ein ausführbares ML-Werkzeug, damit die Geschäftslogik außerhalb des App-Targets testbar bleibt.
• XCTest: Tests für Parser, Archiv, Backup, Export, Lokalisierung, Quellcodeschutz, App Intents und die Schnittstellenanforderungen der ML-Modelle.
• Apple Vision und VisionKit: Scanaufnahme, OCR, Zeilengeometrie und Erfassung der Dokumentstruktur.
• Core ML und Create ML: Belegdetektor, Lokalisierung, Klassifikation, Bewertung von Feldkandidaten und lokale Modelle für Zeilenrollen.
• YOLO und Ultralytics: Experimente mit Layoutbereichen, Zonenannotation und Modellexporte für Belegpapier und Inhaltsbereiche.
• Python-, Swift- und Ruby-Skripte: Datensatzvorbereitung, Projekterzeugung, Modelltraining, Prüfungen, Berichte und Ressourcensynchronisierung.
• Core Data und CloudKit: privates, synchronisiertes Archiv, Migration aus JSON und Spiegelung von Scandateien.
• CryptoKit: SHA-256-Prüfsummen für die Integrität der Scandateien und eine Grundlage für künftige verschlüsselte Backups.
• Integration in das App-Ökosystem: Teilen-Erweiterung, Dokumentimport, App Intents, Deep Links, Spotlight-Einträge, Export nach Mail-Vorbild und manuelle Sicherungen.

Die Hürden und ihre Lösungen

Warum dies eine technische Herkulesaufgabe war

Der schwierige Teil war nicht ein einzelner Algorithmus, sondern die Zahl der Übergänge, die gleichzeitig zuverlässig funktionieren mussten. Aus einem Scan musste ein OCR-Ergebnis werden, daraus ein Beleg. Dieser Beleg musste durchsuchbar, exportierbar, synchronisierbar, wiederherstellbar und nachvollziehbar sein. Die Erkennung musste besser werden, ohne private Daten preiszugeben oder von einem Server abzuhängen. Die Oberfläche sollte dabei nativ und ruhig bleiben, während darunter eine Verarbeitung lief, die eher an Dokumentforensik als an einfache Formularauswertung erinnert.

Jede Version ließ die vorherige kleiner erscheinen. Version 1 bewies, dass die App als sauber aufgebautes Swift-Produkt möglich war. Version 2 zeigte, dass Belegverständnis eine echte lokale ML- und Validierungskette benötigt. Version 3 machte deutlich, dass Erkennung erst dann zum Produkt wird, wenn Speicherung, Synchronisierung, Import, Export, Datenschutz, Leistung und Veröffentlichungsprozesse vertrauenswürdig sind.

Die Codebasis bildet diesen Weg inzwischen ab: gemeinsames Kernmodul, App-Oberfläche, Scandienste, Archivansichten, Core-Data-Repositories, CloudKit-Konfiguration, ML-Schnittstellenanforderungen, Modellcaches, Trainingsskripte, Skripte für den Produktionsablauf, App-Store-Dokumentation, Leistungsprüfungen und Dutzende gezielte Tests. Das Ergebnis ist keine dünne Hülle um OCR. Es ist eine Plattform zur Belegauswertung direkt auf dem Gerät, die den Unterschied zwischen Text und belastbaren Angaben lernen musste.

Lehren für ähnliche Projekte

1. Mit einem testbaren Kern beginnen. Kamera und OCR liefern unberechenbare Eingaben. Ein Fachmodell und feste Testdaten geben dem Projekt ein belastbares Fundament.
2. OCR als Hinweis behandeln, nicht als fertiges Ergebnis. Geometrie, Konfidenz, Layout und Belegarithmetik gehören zur Prüfung dazu.
3. Modellvorschläge von der Ergebnisfreigabe trennen. Deterministische Prüfungen sollten entscheiden, ob eine Auswertung gut genug ist.
4. Trainingswerte dürfen keine Show werden. Gegen Datenlecks, fest programmierte Abkürzungen und die Verunreinigung von Validierungsmengen absichern.
5. Dateien früh einplanen. Originalbilder verändern die Architektur von Speicherung, Backup, Synchronisierung und Leistung.
6. Produktionskonfiguration wie Code prüfen. Entitlements, Datenschutzmanifeste und CloudKit-Schemata sind Teil der App.
7. Plattformspezifische Oberflächen schlank halten. Ein gemeinsamer Kern machte iPhone, iPad und macOS möglich, ohne die Beleglogik zu vervielfachen.

Die Entwicklung von Bon Dossier zeigt, dass leistungsfähige lokale Auswertung keine einzelne Funktion ist. Sie besteht aus einer verlässlichen Kette: Aufnahme, OCR, Layout, Klassifikation, Auswertung, Validierung, Speicherung, Synchronisierung, Export und sorgfältige Freigabe. Bricht ein Glied, wirkt für den Benutzer das ganze System fehlerhaft. Wird jedes Glied gestärkt, wird aus einem unübersichtlichen Papierbeleg ein zuverlässiger privater Datensatz.