PagoMovilOCR
npm-Bibliothek, die venezolanische Pago-Móvil-Belege per OCR extrahiert, normalisiert und validiert.
Das Problem
In Venezuela bedeutet die Bestätigung einer Pago-Móvil-Zahlung meist, den Kunden um einen Screenshot zu bitten und Betrag, Referenz, Datum und Bank von Hand abzulesen — langsam, fehleranfällig und für ein Geschäft mit vielen täglichen Zahlungen nicht skalierbar.
Die Lösung
PagoMovilOCR automatisiert genau das: Es nimmt ein Bild des Belegs entgegen und liefert strukturierte Daten samt einer Reihe von Konsistenzprüfungen — ganz ohne eigenes Backend und ohne das Bild jemals an einen Server zu senden.
Architektur / Engineering
- Pipeline mit 4 unabhängig testbaren Stufen entworfen: OCR → Normalisierung → Parsing → Validierung.
- Austauschbare OCR-Engine implementiert (standardmäßig Tesseract.js, läuft zu 100 % clientseitig/lokal via WebAssembly).
- Registrierbares Bankprofil-System (`registerBankProfile`) gebaut, um das Format jeder Bank zu erkennen und, wenn sicher möglich, zu parsen.
- USD/VES-Konvertierungsmodul mit offiziellem BCV-Kurs (über pydolarve.org) entwickelt, mit konfigurierbarem In-Memory-Cache und explizitem `stale`-Handling.
- Gesamte Logik mit Unit- und Integrationstests in Vitest abgedeckt: Normalisierung, Parser, einzelne Validatoren, das Währungsmodul mit simulierten Providern und `verifyPayment` end-to-end mit simuliertem OCR.
Wichtigste Funktionen
- `verifyPayment()`: vollständige Pipeline von Bild zu strukturiertem Ergebnis mit Validierungen.
- Validierung von Betrag, Referenz, Datum, Uhrzeit und Bank gegen optionale Erwartungswerte.
- USD/VES-Umrechnung auf Abruf mit offiziellem BCV-Kurs und konfigurierbarem Cache.
- Erweiterbares Bankprofil-System, ohne den Kern der Bibliothek anzufassen.
- Funktioniert im Browser (OCR via WASM, Bild verlässt nie den Client) und in Node.js 18+.
- Ausgeliefert als ESM, CJS und IIFE für CDNs (unpkg/jsDelivr), inklusive TypeScript-Typen.
Technische Herausforderungen
- Ehrliche Validierungen entwerfen: Die Bibliothek erzeugt nie ein Feld `fraud: true` und verspricht keine bankseitige Verifizierung — sie meldet nur im extrahierten Text beobachtbare Unstimmigkeiten, die Entscheidung liegt beim Menschen.
- Ausführungsfehler (beschädigtes Bild, Netzwerkausfall) von Belegvalidierungsfehlern trennen, damit ein ungültiger Beleg nie als Programmfehler behandelt wird.
- Extraktion und Validierung deterministisch und mit Vitest testbar halten, ohne in CI auf eine echte OCR-Engine angewiesen zu sein.
Ergebnis / Aktueller Stand
Vollständige Pipeline end-to-end lauffähig, mit einer Vitest-Testsuite für Normalisierung, Parsing, Validatoren und den `verifyPayment`-Orchestrator. Dokumentiert mit vollständigem README, ausführbaren Beispielen und Schichtenarchitektur.
Bekannte Einschränkung
Bankprofile (außer dem generischen) bieten nur Erkennung per Namen; ein bankspezifisches `parse` wurde nicht aufgenommen, da sich für keine Bank zuverlässig ein einheitliches, stabiles Layout verifizieren ließ — der generische Parser deckt das gängige Format ab.