Version 0.1.0. Diese Seite beschreibt alle Funktionen und Einstellungen der Anwendung und wird mit jeder Erweiterung ergänzt.
Scanmind nimmt Geschäftsbelege als PDF oder Bild entgegen, erkennt den Dokumenttyp, lässt die Felder von einem KI-Anbieter (Mistral oder Claude) auslesen, prüft sie mit festen Regeln und übergibt Belege und Prüfbericht an DocuWare. Die KI liest nur aus – ob ein Vorgang stimmig ist, entscheiden nachvollziehbare Regeln, nie das Sprachmodell. Welcher Anbieter aktiv ist, wird je Mandant zur Laufzeit umgeschaltet; beide liefern dasselbe Ergebnisformat.
Scanmind wird für mehrere Kunden (Mandanten) betrieben. Jeder Job, jede
Einstellung, jeder Dokumenttyp und jede Abrechnung gehört zu genau einem Mandanten; Daten
verschiedener Mandanten sind strikt getrennt. Beim ersten Start wird der Mandant
standard angelegt.
| Rolle | Darf |
|---|---|
betreiber (Itolia) | Mandanten und Preise anlegen, API-Schlüssel der KI-Anbieter eintragen (nur diese Rolle), Betreiber-Einstellungen pflegen, alle Mandanten sehen. |
admin (je Mandant) | Dokumenttypen, Benutzer, Regeln und Eingangskanäle des eigenen Mandanten verwalten; aktiven Anbieter wählen. |
pruefer (je Mandant) | Belege prüfen, korrigieren, freigeben; Kosten lesend einsehen. |
| Funktion | Aufruf | Beschreibung |
|---|---|---|
| Healthcheck | GET /health |
Antwortet mit {"status":"ok","version":…,"db":"ok","worker":"ok|veraltet|unbekannt","worker_letzter_lauf":…}. worker ist der Heartbeat des Hintergrunddienstes (veraltet = letzter Lauf älter als das Dreifache des Takts, mindestens 5 Minuten; Admins sehen dann ein Banner). Ohne Datenbank antwortet der Dienst mit 503. Wird vom Docker-Healthcheck und vom Monitoring genutzt. |
| Hilfe | GET /hilfe | Diese Seite. |
| Schlüssel erzeugen | scanmind keygen |
Erzeugt den Fernet-Schlüssel für APP_SECRET_KEY. Einmal beim Einrichten ausführen, Ergebnis in .env eintragen und sicher aufbewahren. |
| Datenbank einrichten | scanmind db upgrade |
Spielt alle Migrationen ein, legt den Mandanten standard, die eingebauten Dokumenttypen je Mandant und den Betreiber-Benutzer admin an; übernimmt beim allerersten Start die Startwerte aus .env. Beliebig oft wiederholbar. |
| Beleg auslesen | scanmind extract datei.pdf [--mandant standard] [--provider mistral|claude] [--typ RECHNUNG] |
Erkennt den Dokumenttyp (oder nimmt --typ als feste Vorgabe), liest die Felder aus und gibt das Ergebnis als JSON aus: Typ mit Konfidenz und Begründung, Werte je Feld, Anbieter und Modell, Seiten, Token, Dauer, Konfidenz je Pflichtfeld, Plausibilität, Hinweise. Jeder Aufruf legt einen Job, einen Kosteneintrag und die Abrechnungsposten an. |
| Mandant anlegen | scanmind mandant anlegen <schluessel> "<Name>" --preis-seite 0.05 --preis-dokument 0.10 [--waehrung EUR] |
Legt einen Mandanten mit Preisen an und kopiert die eingebauten Dokumenttypen. Schlüssel: klein, a–z, 0–9, Bindestrich. |
| Mandanten anzeigen | scanmind mandant liste | Alle Mandanten mit Preisen als JSON. |
| Monatsabrechnung | scanmind abrechnung --mandant <schluessel> --monat JJJJ-MM [--csv datei] |
Abrechenbare Dokumente, Seiten und Betrag des Monats sowie die Anbieterkosten je Modell, als CSV (Semikolon). |
| Stammdaten importieren | scanmind stammdaten import --mandant <schluessel> --csv datei.csv [--spalte name=Firma …] |
Übernimmt Lieferanten-Stammdaten aus einer CSV (Kopfzeile, Semikolon) in den lokalen Spiegel des Mandanten. Spaltenzuordnung für name, ust_id, iban, lieferanten_nummer, extern_id. Vorhandene Datensätze werden aktualisiert, fehlende deaktiviert. |
| Stammdaten aus DocuWare | scanmind stammdaten sync --mandant <schluessel> [--archiv ID] [--dialog ID] |
Liest das DocuWare-Stammdatenarchiv des Mandanten (Einstellungen DOCUWARE_STAMMDATEN_CABINET_ID, DOCUWARE_STAMMDATEN_DIALOG_ID; Feldzuordnung in config/docuware_mapping.yaml) und spiegelt die Lieferanten. Nur lesend. |
| Stammdaten anzeigen | scanmind stammdaten liste --mandant <schluessel> | Gespiegelte Lieferanten als JSON. |
| DocuWare-Verbindung testen | scanmind docuware test --mandant <schluessel> |
Login über den Identity Service und Archivliste, kein Schreibzugriff. Braucht DOCUWARE_PLATFORM_URL, DOCUWARE_USERNAME, DOCUWARE_PASSWORD beim Mandanten. |
| Regelwerte anzeigen | scanmind regeln zeigen --mandant <schluessel> |
Wirksame Toleranzen und Schwellwerte des Mandanten (Version 0 = config/regeln.yaml; jede Änderung erzeugt eine neue Version mit Audit). |
| Einstellungen anzeigen | scanmind einstellungen zeigen [--mandant <schluessel>] |
Zeigt die Betreiber-Einstellungen oder die wirksamen Einstellungen eines Mandanten als JSON; API-Schlüssel und Passwörter erscheinen nur maskiert (letzte vier Zeichen). |
| Prüfbericht schreiben | scanmind bericht <job-id> [--ziel datei.pdf] |
Schreibt den Prüfbericht eines Jobs als PDF (Standardname PB-<id>.pdf). |
| Beispielberichte | scanmind beispielberichte [ordner] |
Erzeugt acht Beispiel-Prüfberichte (OK, HINWEIS, ABWEICHUNG, PRÜFUNG, je einmal „mit Mistral“ und „mit Claude“) über den echten Validierungsweg mit einem eingebauten Beispielanbieter – ohne API-Aufrufe und Kosten. Abnahmeartefakt der Phase 5, liegt unter docs/beispielberichte/. |
| Schlüsselwechsel | scanmind reencrypt [--pruefen] [--neuer-schluessel …] |
Stellt alle verschlüsselten Einstellungen auf einen neuen APP_SECRET_KEY um (Probelauf mit --pruefen), gibt den neuen Schlüssel aus; danach .env anpassen und Dienste neu starten. Audit nur mit Anzahl, nie mit Werten. |
| Sicherung / Wiederherstellung | deploy/backup.sh, deploy/restore.sh <dump> |
Täglicher Dump der Datenbank plus Kopie der .env nach /opt/backups/scanmind (14 Tage); Wiederherstellung stoppt App und Worker, spielt den Dump ein und startet neu. Einzelheiten in docs/betrieb.md. |
| Ausrollen | deploy/deploy.sh |
Überträgt den aktuellen Commit auf den Server, baut den Stack neu und prüft /health. |
| Testbeleg erzeugen | scanmind testbeleg [ziel.pdf] |
Schreibt den synthetischen Mini-Beleg, den auch der Verbindungstest verwendet. Enthält keine echten Daten. |
| Dienst starten | scanmind serve |
Startet die Weboberfläche. Optionen: --host (Standard 127.0.0.1), --port (Standard 8000), --reload (nur Entwicklung). |
| Fixtures erzeugen | python scripts/generate_fixtures.py |
Erzeugt 20 synthetische Rechnungen und je 5 Gutschriften, Bestellungen, Auftragsbestätigungen und Lieferscheine mit Sollwerten unter tests/fixtures/. |
| Genauigkeit messen | python scripts/evaluate.py --provider mistral --provider claude |
Klassifiziert und liest alle Fixtures mit den gewählten Anbietern aus und berichtet Typerkennung sowie Trefferquote je Feld und Anbieter plus geschätzte Anbieterkosten. Verursacht Kosten beim Anbieter, wird dem Mandanten aber nicht berechnet. |
Alle Seiten außer Anmeldung, Hilfe und /health verlangen eine Anmeldung. Admin-Seiten
sehen nur admin und betreiber; Mandanten verwaltet nur der Betreiber, der
oben rechts zwischen Mandanten wechselt. Nach jeder Aktion erscheint ein Hinweis (grün = erledigt,
rot = Fehler) auf der Folgeseite.
| Seite | Adresse | Was sie tut |
|---|---|---|
| Anmeldung | /login | Benutzername und Passwort. Beim ersten Login (Startpasswort) wird sofort der Passwortwechsel unter /passwort verlangt. Abmelden über den Knopf oben rechts. |
| Dashboard | / | Zähler je Status, die letzten 20 Belege, Fehlerliste mit „Erneut auslesen“, Banner bei Anbieterproblemen (24 Stunden), fehlender DocuWare-Konfiguration und erreichtem Budget. Unten: Beleg hochladen (PDF/PNG/JPEG/WebP bis 50 MB) mit optional festem Dokumenttyp und abweichendem Anbieter. |
| Belegansicht (Prüfung) | /jobs/<id> | Links die Belegvorschau (PDF oder Bild), rechts die ausgelesenen Werte als Korrekturformular mit Konfidenz je Feld: Beträge wie auf dem Beleg (1.234,56), Daten als TT.MM.JJJJ, Listen mit Komma. „Korrekturen speichern und neu prüfen“ übernimmt die Werte, setzt die Konfidenz korrigierter Felder auf 1,0 und lässt alle Regeln erneut laufen; alter und neuer Wert stehen am Beleg und im Audit. Darunter Freigeben (Kommentar optional; gesperrt, solange eine blockierende Regel wie das Duplikat R03 verletzt ist) und Ablehnen (Grund Pflicht). Admins können eine Entscheidung zurücknehmen; der Beleg geht dann zurück in die Prüfung. Außerdem: Prüfergebnisse, Korrekturhistorie, Positionen (nur Anzeige), Erneut auslesen mit Typ- oder Anbieterwahl (zählt erneut), Original öffnen, Prüfbericht. |
| Prüfbericht | /jobs/<id>/bericht | Prüfbericht des Belegs als PDF (Knopf „Prüfbericht (PDF)“ in der Belegansicht und „Bericht“ in der Prüfliste); wird bei jedem Abruf aus dem aktuellen Stand des Jobs erzeugt, Abruf steht im Audit. |
| Prüfliste | /pruefung?ansicht=offen|validiert|freigegeben|abgelehnt|fehler|alle | Belege nach Bearbeitungsstand mit Zählern je Ansicht: Eingang, Datei, Typ, Lieferant, Betrag, Status, Gesamtstatus, Alter in Tagen, verletzte Regeln, Link zum Bericht. |
| Kosten | /kosten, /kosten.csv | Monatsabrechnung des Mandanten (Dokumente, Seiten, Betrag), abrechenbare Mengen je Dokumenttyp und geschätzte Anbieterkosten je Modell; CSV-Download mit allen drei Blöcken. Auch für Prüfer lesbar. |
| Einstellungen | /einstellungen | Übersicht mit Links zu KI-Anbieter, DocuWare, Eingang und Regeln. |
| KI-Anbieter | /einstellungen/anbieter | Je Anbieter: API-Schlüssel (nur Betreiber; verschlüsselt, maskiert, leer lassen = behalten), Modelle, Monatsbudget, Datenschutz-Bestätigung. Darunter: aktiver Anbieter zum Auslesen und für Textaufgaben, Fallback-Schalter, Belegabgleich-Schalter. Verbindung testen schickt den synthetischen Testbeleg und meldet Dauer, Seiten und Token (nicht abrechenbar). Ein Anbieter kann erst aktiviert werden, wenn seine Datenschutzpunkte bestätigt sind. |
| DocuWare | /einstellungen/docuware | Platform-URL, Service-Benutzer, Passwort, Archiv-IDs (Belege, Prüfberichte, Stammdaten, Suchdialog, Briefkorb), Produktivmodus-Schalter; DocuWare testen (Login + Archivliste, nur lesend); Archive laden holt Archive und Briefkörbe, danach werden Beleg-, Berichts-, Stammdatenarchiv und Briefkorb per Auswahl gesetzt; Felder prüfen gleicht die Feldzuordnung mit den Archiven ab und markiert fehlende Zielfelder. |
| DocuWare-Feldzuordnung | /einstellungen/docuware/zuordnung | Editor mit drei Abschnitten (Belegarchiv, Berichtsarchiv, Stammdatenarchiv): links die Scanmind-Felder (alle Felder der aktiven Dokumenttypen plus Dokumenttyp, Vorgangsnummer, Prüfstatus), rechts eine Auswahl der live geladenen Indexfelder des Archivs mit Typ. Vorbelegung aus den Startwerten (config/docuware_mapping.yaml) oder gleichnamigen Feldern; „nicht übertragen“ lässt ein Feld aus. Die Zuordnung wird dauerhaft je Mandant gespeichert (Einstellung DOCUWARE_ZUORDNUNG, Audit) und gilt für Export und Stammdaten-Synchronisation. |
| Eingang und Export | /einstellungen/eingang | Kanäle Scan-Ordner, IMAP-Postfach und DocuWare-Briefkorb ein-/ausschalten, je Kanal einen festen Dokumenttyp zuordnen (hat Vorrang vor der KI-Erkennung), Zugangsdaten pflegen, Schalter für automatischen Export und Löschen im Briefkorb, je Kanal Testen (Ordner beschreibbar, IMAP-Login, Briefkorb erreichbar). |
| Alarme | /einstellungen/alarme | Empfängeradresse je Mandant, SMTP-Versand (nur Betreiber), Test-Mail, Liste der letzten Alarme mit Versandstatus. |
| Regeln | /einstellungen/regeln | Konfidenz-Schwellwerte je Anbieter und für die Typerkennung, Toleranz der Rechenprüfung, je Regel: aktiv, Ergebnis bei Verstoß, blockierend, Parameter (Toleranzen, zulässige USt-Sätze, Namensschwelle). Jede Speicherung erzeugt eine neue Regelwerk-Version mit Audit. |
| Dokumenttypen | /dokumenttypen, /dokumenttypen/neu, /dokumenttypen/<SCHLUESSEL> | Liste mit Aktivieren/Deaktivieren und der Dokumenttyp-Editor: Schlüssel, Name, Erkennungsmerkmale, Felder (Name, Anzeigename, Typ, Pflicht, Beschreibung für die KI, Spalten bei Tabellen). „Feld hinzufügen“ und „Entfernen“ arbeiten ohne JavaScript. Jede Speicherung ist eine neue Version; Versionen werden unten angezeigt. |
| Stammdaten | /stammdaten | Gespiegelte Lieferanten, Synchronisation aus dem DocuWare-Stammdatenarchiv, CSV-Import mit Spaltenzuordnung. |
| Benutzer | /benutzer | Benutzer des Mandanten anlegen (Startpasswort wird einmalig angezeigt), Rolle ändern, deaktivieren, Passwort zurücksetzen. Der Betreiber sieht zusätzlich die Betreiber-Benutzer. |
| Mandanten | /mandanten | Nur Betreiber: Mandanten anlegen (mit eingebauten Typen), Name, Preise je Seite/Dokument, Währung, aktiv/inaktiv. |
| Audit | /audit | Wer hat wann was geändert (Benutzer, Aktion, Zeitraum filterbar); alter und neuer Wert, nie Schlüsselwerte. |
SCANMIND_TMP_DIR (Standard ./data/tmp, im Container /data/tmp) je Mandant und Job, bis zum Export und höchstens TEMP_RETENTION_DAYS. DocuWare ist das Archiv, nicht Scanmind.APP_SECRET_KEY verschlüsselt gespeichert, nur maskiert angezeigt und erscheinen nie in Logs oder im Audit.Jeder Dokumenttyp hat eine Typdefinition: Name, Erkennungsmerkmale für die KI und eine Liste von Feldern. Je Feld: technischer Name, Anzeigename, Datentyp (Text, Zahl, Betrag, Datum, Liste, Ja/Nein, Tabelle mit Spalten), Pflicht ja/nein und eine deutsche Beschreibung, die beiden Anbietern als Anweisung dient. Jede Änderung einer Definition erhält eine neue Versionsnummer; jeder Job speichert, mit welcher Version er ausgelesen wurde.
Eingebaute Typen (werden jedem Mandanten angelegt): BESTELLUNG,
AUFTRAGSBESTAETIGUNG, LIEFERSCHEIN, RECHNUNG,
GUTSCHRIFT. Gemeinsame Felder sind Belegnummer, Belegdatum, Lieferant (Name,
USt-IdNr., Lieferantennummer) und die Positionstabelle; je nach Typ kommen Bestell-/AB-Nummer,
Lieferscheinnummern, Liefertermin, Beträge, USt-Sätze, Zahlungsbedingungen, IBAN und bei der
Gutschrift die Bezugsrechnung hinzu. Pflichtfelder: Belegnummer, Belegdatum, Lieferant; bei
Rechnung und Gutschrift zusätzlich Netto-, USt- und Bruttobetrag; bei der AB die Bestellnummer.
Erkennung: Ohne feste Vorgabe (--typ bzw. später die
Kanal-Zuordnung) bekommt der Anbieter alle aktiven Typen des Mandanten mit ihren Merkmalen und
bestimmt in einem Aufruf den Typ und die Felder. Passt kein Typ, lautet das Ergebnis
SONSTIGES; der Beleg geht in die manuelle Prüfung. Deaktivierte Typen nehmen nicht
teil. Eigene Typen legen Admins im Dokumenttyp-Editor an (siehe Oberfläche): gleichnamige Felder
müssen in allen aktiven Typen denselben Feldtyp haben, Kernfelder eingebauter Typen bleiben erhalten,
jede Speicherung erzeugt eine neue Version.
Drei Ebenen: die Startkonfiguration in .env (nur, was der Dienst zum
Starten braucht), die Betreiber-Einstellungen (global) und die
Mandanten-Einstellungen. Fehlt ein Mandantenwert, gilt der Betreiberwert, dann
der Standardwert. Startwerte aus .env werden beim allerersten Start übernommen
(Betreiberwerte global, alles andere beim Mandanten standard); danach
ignoriert der Dienst diese .env-Werte.
Die API-Endpunkte der Anbieter (api.mistral.ai, api.anthropic.com) sind
fest im Programm hinterlegt und nicht einstellbar.
.env)| Variable | Pflicht | Bedeutung |
|---|---|---|
DATABASE_URL | ja | Verbindung zur Datenbank. Entwicklung: SQLite-Datei (sqlite:///./data/scanmind.db); Produktion: PostgreSQL (wird im Docker-Stack automatisch gesetzt). |
APP_SECRET_KEY | ja | Fernet-Schlüssel, mit dem alle in der Datenbank gespeicherten API-Schlüssel und Passwörter verschlüsselt werden. Einmal erzeugen (scanmind keygen), nie ändern. Bei Verlust müssen alle gespeicherten Schlüssel neu eingegeben werden. |
APP_BASE_URL | ja | Öffentliche Adresse des Dienstes, z. B. https://scanmind.itolia.de. |
ADMIN_INITIAL_PASSWORD | ja (erster Start) | Passwort des Betreiber-Benutzers admin, der beim ersten Start angelegt wird. Danach ändern; der Wert wird nur verwendet, solange kein Benutzer existiert. |
TEMP_RETENTION_DAYS | nein (7) | Nach wie vielen Tagen temporäre Dateien spätestens gelöscht werden. |
SCANMIND_CONFIG_DIR | nein | Ordner mit regeln.yaml, preise.yaml, docuware_mapping.yaml; Standard ist config/ im Projekt. |
SCANMIND_TMP_DIR | nein (./data/tmp) | Ablage der Originaldateien je Mandant und Job (Vorschau, erneutes Auslesen, Export). Im Container /data/tmp. |
POSTGRES_PASSWORD, SCANMIND_PORT | nur Docker | Passwort der Postgres-Datenbank im Stack; lokaler Port für den Reverse Proxy (Standard 8160). |
| Einstellung | Standard | Bedeutung |
|---|---|---|
MISTRAL_OCR_MODEL | mistral-ocr-4-1 | Standardmodell für das Auslesen mit Mistral (je Mandant übersteuerbar). |
MISTRAL_LLM_MODEL | mistral-small-2603 | Standardmodell für Textaufgaben mit Mistral. |
CLAUDE_EXTRACT_MODEL | claude-sonnet-5-5 | Standardmodell für das Auslesen mit Claude. |
CLAUDE_TEXT_MODEL | claude-haiku-5-5 | Standardmodell für Textaufgaben mit Claude. |
ALERT_EMAIL | – | Empfänger für Alarme (je Mandant übersteuerbar); zusätzlich erscheinen Alarme als Banner im Dashboard. |
SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, SMTP_ABSENDER, SMTP_STARTTLS | 587, true | Versand der Alarm-Mails (nur Betreiber). |
EINGANG_INTERVALL_S | 60 | Takt des Hintergrunddienstes in Sekunden. |
TEMP_RETENTION_DAYS | 7 | Löschfrist für temporäre Dateien. |
| Einstellung | Standard | Bedeutung |
|---|---|---|
EXTRACT_PROVIDER | mistral | Anbieter, der die Belege dieses Mandanten ausliest (mistral oder claude). Nur konfigurierte Anbieter sind wählbar. |
TEXT_PROVIDER | mistral | Anbieter für Positionszuordnung und Berichtstext (ab Phase 3/5). Darf vom Extraktions-Anbieter abweichen. |
MISTRAL_API_KEY, ANTHROPIC_API_KEY | – | API-Schlüssel des Mandanten; nur der Betreiber trägt sie ein. Verschlüsselt gespeichert, maskiert angezeigt. |
MISTRAL_OCR_MODEL, MISTRAL_LLM_MODEL, CLAUDE_EXTRACT_MODEL, CLAUDE_TEXT_MODEL | Betreiberwert | Optionale Übersteuerung der Standardmodelle für diesen Mandanten. |
BELEGABGLEICH_AKTIV | false | Schaltet den Abgleich zwischen Belegen eines Vorgangs (Regeln R01–R11) ein. Aus = Belege werden nur ausgelesen, geprüft und exportiert. (Wirkung ab Phase 3.) |
FALLBACK_ANBIETER_AKTIV | false | Erlaubt bei Ausfall eines Anbieters den Wechsel auf den anderen. Aus Datenschutz- und Kostengründen standardmäßig aus; jeder Wechsel wird protokolliert. Die automatische Umschaltung ist noch nicht aktiv (Annahme A46). |
BUDGET_MONAT_MISTRAL, BUDGET_MONAT_CLAUDE | – | Monatsbudget der geschätzten Anbieterkosten in EUR. Ab 80 % Warnung, ab 100 % Hinweis im Dashboard; keine Abschaltung. |
DATENSCHUTZ_GEPRUEFT_MISTRAL, DATENSCHUTZ_GEPRUEFT_CLAUDE | – | Wer die Datenschutzpunkte des Anbieters bestätigt hat (Pflicht vor der Aktivierung, docs/anbieter.md). |
DOCUWARE_PRODUKTIVMODUS | false | Erst nach Abnahme: erlaubt den Export in ein Archiv, dessen URL nicht „test“ enthält. |
EINGANG_ORDNER_AKTIV, EINGANG_IMAP_AKTIV, EINGANG_BRIEFKORB_AKTIV | false | Schalter je Eingangskanal; KANAL_TYP_* ordnet dem Kanal einen festen Dokumenttyp zu. |
INGEST_WATCH_DIR, IMAP_HOST, IMAP_PORT, IMAP_USER, IMAP_PASSWORD, IMAP_ORDNER, IMAP_ORDNER_ERLEDIGT, DOCUWARE_BRIEFKORB_ID, DOCUWARE_BRIEFKORB_LOESCHEN | – | Zugänge der Kanäle (Passwort verschlüsselt). Briefkorb-Dokumente werden nur mit dem Lösch-Schalter entfernt. |
EXPORT_AUTOMATISCH | true | Exportfähige Belege ohne manuellen Anstoß nach DocuWare übergeben. |
DOCUWARE_PLATFORM_URL, DOCUWARE_USERNAME, DOCUWARE_PASSWORD | – | DocuWare-Zugang des Mandanten (Service-Benutzer, Passwort verschlüsselt). Ab Phase 3 für Stammdaten (lesend), ab Phase 7 für den Export. |
DOCUWARE_STAMMDATEN_CABINET_ID, DOCUWARE_STAMMDATEN_DIALOG_ID | – | Archiv und Suchdialog mit den Lieferanten-Stammdaten; ohne Dialog-ID wird der erste Suchdialog genutzt. |
DOCUWARE_FILE_CABINET_ID, DOCUWARE_REPORT_CABINET_ID, IMAP_*, INGEST_WATCH_DIR | – | Zielarchive, Postfach, Scan-Ordner des Mandanten. Werden ab Phase 7 verwendet. |
Je Pflichtfeld wird ein Wert zwischen 0 und 1 gespeichert. Bei Mistral stammt er
aus der OCR (Erkennungssicherheit des Textblocks, der den Wert enthält), bei Claude
ist er eine Modellschätzung, weil die Claude API keine Konfidenzen liefert. Die
beiden Skalen sind nicht identisch; deshalb gibt es in regeln.yaml je Anbieter einen
Schwellwert (Start 0,85) und einen eigenen Schwellwert für die Typerkennung (0,70). Zusätzlich
prüft Scanmind die Rechnung innerhalb des Belegs (Netto + USt = Brutto, Positionssumme = Netto,
USt-Satz passt; Toleranz 0,02 €). Verletzt eine Prüfung die Plausibilität, wird die
Gesamtkonfidenz auf höchstens 0,5 gedeckelt. Liegt die Gesamtkonfidenz unter dem Schwellwert,
geht der Beleg in die manuelle Prüfung (Regel R12, ab Phase 3).
Direkt nach dem Auslesen prüft Scanmind jeden Beleg mit festen Regeln. Jedes Ergebnis ist
OK, HINWEIS, UNVOLLSTAENDIG, ABWEICHUNG oder
PRUEFUNG; das schwerste Ergebnis bestimmt den Gesamtstatus. OK und
HINWEIS ergeben den Status VALIDIERT (exportfähig, Hinweis landet im
Prüfbericht); alles andere den Status PRUEFUNG (manuelle Prüfung). Toleranzen und
Ergebnisstufen sind je Mandant einstellbar (Einstellungen › Regeln oder scanmind regeln zeigen).
| Regel | Prüft | Standard bei Verstoß |
|---|---|---|
| T01 | Dokumenttyp erkannt (nicht SONSTIGES) | PRÜFUNG |
| R12 | Alle Pflichtfelder vorhanden; Gesamtkonfidenz über dem Schwellwert des Anbieters; Typ-Konfidenz über 0,70 | PRÜFUNG |
| F01 | USt-IdNr. formal gültig (DE + 9 Ziffern bzw. EU-Format) | HINWEIS |
| F02 | IBAN-Prüfsumme korrekt | PRÜFUNG |
| F03 | Belegdatum plausibel (nicht mehr als 7 Tage in der Zukunft, nicht älter als 10 Jahre) | HINWEIS |
| R08 | Summe der Positionen = Nettosumme (Toleranz 0,02 €) | ABWEICHUNG |
| R09 | Netto + USt = Brutto, USt-Satz zulässig (19/7/0 %) und passend | ABWEICHUNG |
| R03 | Kein Duplikat: Belegnummer, Betrag, Belegdatum und Lieferant stimmen mit keinem verarbeiteten Beleg überein (Merkmale, die auf einem der Belege fehlen, werden nicht verglichen; identische Datei nur Hinweis) | ABWEICHUNG, blockierend |
| R13 | Lieferant in den Stammdaten (USt-IdNr. vor IBAN vor Name); Lieferantennummer wird ergänzt; Widerspruch zur hinterlegten Nummer = ABWEICHUNG; Treffer nur über Namensähnlichkeit = HINWEIS | PRÜFUNG (je Mandant auf HINWEIS abschwächbar) |
Regeln, die Felder brauchen, die der Dokumenttyp nicht hat (z. B. Beträge beim Lieferschein), werden übersprungen. Sind für den Mandanten keine Stammdaten hinterlegt, wird R13 übersprungen.
Zu jedem Beleg erzeugt Scanmind einen Prüfbericht als PDF (bis zum optionalen Belegabgleich ist ein Vorgang genau ein Beleg; danach umfasst der Bericht alle Belege des Vorgangs). Aufbau:
| Abschnitt | Inhalt |
|---|---|
| Kopf „Vorgang“ | Berichtsnummer PB-… (aus der Job-ID), Mandant, Dokumenttyp, Belegnummer, Belegdatum, Lieferant mit USt-IdNr. und Stammdaten-Treffer, Bestellnummer, Bruttobetrag, Verarbeitungsdatum, Gesamtstatus farblich (grün OK, orange HINWEIS, rot ABWEICHUNG/UNVOLLSTÄNDIG/PRÜFUNG/FEHLER) und Bearbeitungsstatus. |
| Belege | Typ, Nummer, Datum, DocuWare-ID (ab Phase 7), Anbieter und Modell der Auslesung, Datei, Seiten. |
| Positionen | Alle ausgelesenen Positionen mit den Spalten des Dokumenttyps (Beträge rechtsbündig im deutschen Format). Spalten für bestellt/bestätigt/geliefert und Preise laut AB folgen mit dem Belegabgleich. |
| Regelergebnisse | Regel-ID, Ergebnis (farbig, „blockierend“ markiert), Prüfung, Details. Bei fehlgeschlagenem Auslesen steht hier der Fehler. |
| Korrekturen durch Prüfer | Feld, alter und neuer Wert, Benutzer, Zeitpunkt – nur wenn korrigiert wurde. |
| KI-Zuordnungen, Freigabe | KI-Zuordnungen: Platzhalter bis zum Belegabgleich. Freigabe: freigegeben oder abgelehnt von wem, wann, mit Kommentar bzw. Grund; sonst „Noch nicht freigegeben“. |
| Technischer Anhang | Anbieter, Modell, Konfidenzquelle (OCR-Messung bzw. Modellschätzung bei Claude), Gesamt- und Feldkonfidenz, Plausibilität, Typerkennung mit Begründung, Dokumenttyp- und Regelwerk-Version, Versuche, Fallback-Vermerk, Datei mit SHA-256, Zeitstempel (UTC), Scanmind-Version. |
Der Bericht wird nicht gespeichert, sondern bei jedem Abruf aus dem Job erzeugt; die Übergabe nach DocuWare als eigenes Dokument kommt mit dem Export (Phase 7). Format: PDF mit eingebetteter Schrift DejaVu Sans (Lizenz im Paket); die PDF/A-Kennzeichnung (XMP, Farbprofil) folgt mit dem Export.
Der Hintergrunddienst (scanmind worker, im Docker-Stack der Container
scanmind-worker) läuft im Takt von EINGANG_INTERVALL_S Sekunden (Standard 60) und
erledigt je aktivem Mandanten:
| Schritt | Was passiert |
|---|---|
| Eingang | Aktive Kanäle abholen. Scan-Ordner (INGEST_WATCH_DIR): Dateien im Ordner (PDF, PNG, JPEG, WebP), die seit 10 s unverändert sind; verarbeitete Dateien wandern nach erledigt/, abgelehnte nach fehler/. IMAP: ungelesene Mails, Anhänge als Beleg; Mail wird als gelesen markiert und optional in IMAP_ORDNER_ERLEDIGT verschoben. Briefkorb (DOCUWARE_BRIEFKORB_ID): Dokumente herunterladen, optional löschen. Jeder Eingang wird genau einmal verarbeitet (Tabelle eingang_quellen). Ist dem Kanal ein Dokumenttyp zugeordnet (KANAL_TYP_ORDNER, KANAL_TYP_IMAP, KANAL_TYP_BRIEFKORB), gilt er fest; sonst erkennt die KI den Typ. |
| Wiederholung | Belege im Status FEHLER mit wiederholbarem Fehler (Serverfehler, Rate-Limit, Schemafehler) werden erneut ausgelesen, höchstens drei Versuche; danach Alarm. Bei ungültigem Schlüssel oder erschöpftem Guthaben sofort Alarm, keine Wiederholung. |
| Export | Bei EXPORT_AUTOMATISCH (Standard an) werden validierte Belege ohne Beanstandung (OK/HINWEIS) und freigegebene Belege nach DocuWare übergeben: der Beleg mit Indexfeldern aus config/docuware_mapping.yaml ins Belegarchiv (DOCUWARE_FILE_CABINET_ID), der Prüfbericht als eigenes Dokument vom Typ „Prüfbericht“ mit derselben Vorgangsnummer ins Berichtsarchiv (DOCUWARE_REPORT_CABINET_ID, sonst dasselbe Archiv). Zielfelder, die im Archiv fehlen, werden übersprungen und im Audit vermerkt. Nach dem Export wird die Originaldatei aus der Ablage gelöscht; Status EXPORTIERT mit DocuWare-IDs. Ein Archiv, dessen URL nicht „test“ enthält, verlangt DOCUWARE_PRODUKTIVMODUS. Höchstens drei Versuche je Beleg, dann Alarm; manuell über „Nach DocuWare exportieren“ in der Belegansicht oder scanmind export <job-id>. |
| Budgets | Erreicht die geschätzte Monatssumme eines Anbieters BUDGET_MONAT_MISTRAL bzw. BUDGET_MONAT_CLAUDE, geht ein Alarm hinaus (zusätzlich zum Banner). |
| Aufräumen | Einmal täglich: Dateien in der Ablage, die älter als TEMP_RETENTION_DAYS sind, werden gelöscht; abgelaufene Sitzungen ebenso. |
Alarme gehen per E-Mail an ALERT_EMAIL (je Mandant, sonst Betreiberadresse) über
die SMTP-Einstellungen des Betreibers (SMTP_HOST, SMTP_PORT, SMTP_USER,
SMTP_PASSWORD, SMTP_ABSENDER, SMTP_STARTTLS). Derselbe Alarm wird frühestens
nach 24 Stunden wiederholt; alle Alarme stehen unter Einstellungen › Alarme und im Audit. Alarmtexte
enthalten keine Belegdaten. Einmalig von Hand: scanmind worker --einmal (ein Lauf) und
scanmind eingang --mandant <schluessel> [--kanal ordner|imap|briefkorb].
Scanmind spiegelt die Lieferanten-Stammdaten eines Mandanten lokal (Name, USt-IdNr., IBAN,
Lieferantennummer). Quelle ist ein DocuWare-Stammdatenarchiv
(scanmind stammdaten sync) oder eine CSV (scanmind stammdaten import).
Datensätze, die bei einer Synchronisation fehlen, werden deaktiviert, nie gelöscht. Der Abgleich
erkennt den Lieferanten zuerst über die USt-IdNr., dann über die IBAN, dann über den Namen
(Rechtsformen wie GmbH/AG werden ignoriert, kleine Abweichungen toleriert).
Je Mandant sind ein Preis je Seite und ein Preis je Dokument
hinterlegt. Zählweise: jede erfolgreich ausgelesene Datei = 1 Dokument, Seiten = verarbeitete
Seiten. Fehlversuche und automatische Wiederholungen kosten nichts; „Erneut auslesen“ durch einen
Prüfer zählt erneut. Verbindungstests und Evaluierungen werden nicht berechnet. Die
Monatsabrechnung (Seite „Kosten“ mit CSV-Download oder scanmind abrechnung) weist Dokumente,
Seiten und Betrag aus und daneben die geschätzten Anbieterkosten je Modell aus
config/preise.yaml.
| Fall | Verhalten |
|---|---|
| Rate-Limit des Anbieters (429) | Bis zu fünf Versuche mit wachsender Wartezeit (Backoff mit Zufallsanteil, Anbieter-Vorgabe retry-after wird beachtet). |
| Serverfehler, Zeitüberschreitung, Netzwerk | Bis zu drei Versuche, dann Status FEHLER; der Hintergrunddienst wiederholt den Beleg später erneut (insgesamt höchstens drei Läufe), danach Alarm. |
| DocuWare beim Export nicht erreichbar | Der Beleg bleibt mit Fehlertext stehen (Banner im Dashboard), bis zu drei Versuche durch den Hintergrunddienst, dann Alarm; nach Behebung manuell exportieren. |
| Antwort passt nicht zum Schema | Ein Wiederholungsversuch; danach FEHLER, die Rohantwort wird nur im Job (Datenbank) abgelegt, nie im Log. |
| Schlüssel ungültig, Guthaben/Limit erreicht | Keine Wiederholung, sofort FEHLER; das Dashboard zeigt 24 Stunden lang ein Banner. Der Job bleibt erhalten und kann nach der Korrektur erneut ausgelesen werden. |
| Dokument zu groß (Mistral: mehr als 8 Seiten für die Annotation; Claude: mehr als 100 Seiten oder 32 MB) | Keine Wiederholung, manuelle Prüfung. |
| Claude lehnt die Verarbeitung ab (Sicherheitsklassifizierer) | Keine Wiederholung, kein stiller Wechsel auf ein anderes Modell; manuelle Prüfung. |
| Dokumenttyp nicht erkannt | Ergebnis SONSTIGES, keine Felder, manuelle Prüfung; in der Belegansicht wählt der Prüfer den Typ und lässt „Erneut auslesen“, danach sind die Werte korrigierbar. |
| Beleg abgelehnt | Status ABGELEHNT mit Grund; kein Export. Ein Admin kann die Entscheidung zurücknehmen. |
| Einzelne Werte unlesbar (z. B. „viel“ statt Betrag) | Der Wert wird null, der Job erhält einen Hinweis; es wird nie geraten. |