Epson-Scanner und Dokumentenablage

Unter Organisation → Dokumentenablage erscheinen noch nicht abgelegte Scanner-Dateien des aktiven Mandanten, neueste zuerst. Die Seite aktualisiert sich alle zehn Sekunden; Suche, Vorschau und Herunterladen sind verfügbar. Jede übertragene Datei wird unverändert als ein Dokument gespeichert. Ein mehrseitiges PDF bleibt ein Dokument. Der Empfang führt keine Texterkennung, Seitentrennung oder Rechnungsverarbeitung aus.

In Dateien ablegen

Auf den Dateinamen, Vorschau oder Ablegen klicken. Das Modal zeigt das Original und rechts die Zuordnung.
Beim Öffnen wird ein KI-Vorschlag für Ordner und Dokumenttyp aus dem Dokumentinhalt angefordert. Ein gültiger Vorschlag füllt die Auswahlfelder vor und zeigt eine kurze Begründung. Bereits manuell geänderte Werte werden nicht überschrieben. KI-Vorschlag einsetzen übernimmt ihn bei Bedarf wieder in die Felder; Erneut prüfen fordert eine neue Analyse an.
Den vorgeschlagenen vorhandenen FEDEO-Dateiordner oder Dateien (Hauptebene) und Dokumenttyp prüfen und bei Bedarf ändern. Unterordner erscheinen mit ihrem vollständigen Pfad. Neue Typen lassen sich unter Stammdaten → Dateitypen anlegen. Ein vorgeschriebener Ordnertyp ist nicht änderbar.
Erst Übernehmen und ablegen speichert Ordner und Typ am bestehenden Original. Danach verschwindet das Dokument aus dem Eingang und ist unter Dateien im gewählten Ordner verfügbar. Es wird keine Kopie erzeugt und keine Rechnungsverarbeitung ausgelöst.

Nur aktive Ordner und Typen desselben Mandanten sind zulässig. Bei einem Fehler bleibt das Dokument im Eingang. Ein erneuter Scanner-Upload mit demselben Namen und Inhalt bestätigt weiterhin den ursprünglichen Empfang, ohne einen neuen Eingangseintrag anzulegen.

KI-Vorschläge

Die Analyse nutzt die bestehende zentrale FEDEO-KI-Anbindung oder den konfigurierten OPENAI_API_KEY, entsprechend den E-Mail-Zuordnungsvorschlägen. Die Antwort verwendet Structured Outputs und store: false. Dokumentinhalt, Dateiname und Kandidatennamen gelten als Daten, nicht als Anweisungen. Das Backend prüft vorgeschlagene IDs und verpflichtende Ordnertypen gegen die aktiven Stammdaten des Mandanten, auch noch einmal nach der Analyse. Der Scanner-Zugang kann diese API nicht nutzen.

Für die Analyse werden höchstens die ersten fünf PDF-Seiten bzw. die erste Bildseite lokal gelesen (Poppler/Tesseract; JPEG, PNG und TIFF werden für die OCR aufbereitet). Diese Werkzeuge sind im Backend-Image enthalten. Es werden maximal 24.000 Textzeichen und eine begrenzte Auswahl passender Ordner und Typen an die KI geschickt. Die Analyse ist auf Dateien bis 25 MiB begrenzt; die Texterkennung und die einzelnen KI-Anfragen haben Zeitlimits von jeweils 45 Sekunden. Fehlen lesbarer Text, passende Stammdaten oder eine KI-Konfiguration, bleibt die manuelle Zuordnung verfügbar.

Vorschläge und erkannter Text verändern weder das Original noch dessen Klassifizierung. Die Vorschau hält Ergebnisse während des Seitenbesuchs im Speicher, um erneute Analysen beim Wiederöffnen zu vermeiden; ein Mandantenwechsel verwirft sie. Gleichzeitige Analysen desselben Dokuments werden im Backend zusammengefasst, maximal vier Analysen laufen gleichzeitig pro Backend-Prozess. Die fachliche Qualität der KI-Vorschläge sollte bei der Inbetriebnahme mit eigenen Beispieldokumenten geprüft werden.

Einrichtung

Als Administrator den gewünschten Mandanten auswählen und auf der Seite Scanner einrichten → Scanner-Zugang erstellen wählen.
Zieladresse, Benutzername und das einmalig angezeigte Passwort übernehmen. Der Zugang gehört ausschließlich zu diesem Mandanten und kann nur Scanner-Dateien einliefern. Er verwendet kein persönliches FEDEO-Passwort. Ein neues Passwort ersetzt das alte; Zugang deaktivieren sperrt weitere Übertragungen.
Am Epson ES-580W oder ES-C380W Netzwerkordner/FTP → WebDAV (HTTPS) wählen. In Web Config kann der Zieltyp SharePoint (WebDAV) heißen; dort bei separater Auswahl von HTTPS im Feld Speichern unter den Adressanteil ohne https:// eintragen. Zieladresse und Zugangsdaten eintragen, Port 443 bzw. den Port der eigenen HTTPS-Adresse verwenden. Das Serverzertifikat muss vom Scanner akzeptiert werden.
PDF, Duplex und beispielsweise 300 dpi einstellen. Das Ziel als FEDEO speichern. Dateinamen mit Datum/Uhrzeit und laufender Nummer verwenden. Für getrennte Dokumente jeweils eine eigene Datei übertragen; Vorder- und Rückseite können in einer PDF bleiben.

Beim ES-580W nach einem Neustart eine gegebenenfalls angezeigte Freigabe der Netzwerkfunktionen bestätigen. Solange diese gesperrt sind, kann der Scanner vor dem Papiereinzug einen Kommunikationsfehler melden, ohne das Ziel anzusprechen; seine Weboberfläche kann trotzdem erreichbar sein.

Die vollständige Adresse wird aus der konfigurierten Backend-Adresse gebildet, z. B. https://fedeo.example/backend/scanner-inbox/. Ein vorhandener /backend-Präfix muss erhalten bleiben. Es ist kein lokaler Rechner oder Geräte-Agent erforderlich.

Grundlage sind die Epson-Handbücher für ES-580W und ES-C380W. Am physischen ES-580W wurde eine anfängliche GET-Prüfung des Empfangsordners beobachtet: Auf die 401-Anmeldeaufforderung folgt ein authentifiziertes GET. Dieses muss erfolgreich beantwortet werden. Danach prüft Epson den Dateinamen per HEAD. Bei einer Zieladresse mit abschließendem Schrägstrich hängt das Gerät einen weiteren Trenner an, beispielsweise /scanner-inbox//scan.pdf. Der Endpunkt behandelt diese Adresse wie /scanner-inbox/scan.pdf; echte Unterordner und ungültige Dateinamen bleiben gesperrt. Ein fälschlich mit 400 beantworteter HEAD-Test führte am Gerät zur Meldung „Dateiname bereits verwendet“. Einen vollständigen Scan bis zum Eintrag in der Dokumentenablage bei der Inbetriebnahme prüfen.

Nach der Dateinamenprüfung sendet der ES-580W zunächst einen leeren PUT mit Content-Length: 0. Dieser wird als Schreibprobe mit 201 bestätigt, sofern Zugang, Mandant und Dateiname zulässig sind. Dabei entstehen weder eine Datei noch ein Ablageeintrag oder eine dauerhafte Namensreservierung. Erst ein anschließender vollständiger Dokument-Upload wird gespeichert. Vorhandene Dateinamen werden auch bei einer leeren Probe mit 409 bzw. bei If-None-Match: * mit 412 geschützt.

Schnittstelle und Betrieb

Datenbankmigrationen 0073_scanner_document_inbox und 0074_scanner_inbox_filing werden über die reguläre Drizzle-Migration eingespielt. Keine neuen Umgebungsvariablen oder zusätzlichen Dienste sind erforderlich; der vorhandene S3-kompatible Dateispeicher wird genutzt.
Der Scanner-Endpunkt liegt außerhalb der Browser-JWT-Anmeldung unter /scanner-inbox/ und verwendet HTTP Basic mit eigenen zufälligen Zugangsdaten. Ausschließlich über HTTPS veröffentlichen. Passwörter werden nur als SHA-256-Hash gespeichert.
Unterstützt werden OPTIONS, PROPFIND (Depth 0/1), HEAD und PUT /scanner-inbox/<Dateiname>. Ein authentifiziertes GET auf den Empfangsordner (mit oder ohne abschließenden Schrägstrich) liefert für die Epson-Vorprüfung 200 mit leerem Inhalt. Dokumente lassen sich damit nicht herunterladen. Der Empfangsordner existiert bereits; Unterordner, Lesen von Dateien, Löschen, Umbenennen und Überschreiben über den Scanner-Zugang sind nicht vorgesehen. Dies ist ein begrenzter WebDAV-Upload-Eingang, kein allgemeines Netzlaufwerk. Ein PROPFIND des Ordners gibt keine Dokumentenliste preis.
PUT enthält genau eine vollständige Datei als Rohdaten, ohne Multipart-Formular. PDF, JPEG, PNG und TIFF werden anhand von Dateiendung und Signatur geprüft, maximal 100 MiB. Keine Prüfung der gesamten Dokumentstruktur auf Beschädigungen.
Erfolgreiches Speichern: 201. Identische Wiederholung unter demselben Dateinamen: 204, ohne zweiten Ablageeintrag. Anderer Inhalt unter demselben Namen: 409; mit If-None-Match: * bei vorhandenem Namen: 412. Gleicher Inhalt unter einem neuen Namen wird als weiteres Dokument akzeptiert.
Fehlende/ungültige/deaktivierte Zugangsdaten: 401; ungültiger Pfad oder leerer Upload ohne explizite Schreibprobe (Content-Length: 0): 400; zu groß: 413; falsches Format: 415; Mandantenwartung: 423. Bei Speicherfehlern gibt es keine Erfolgsbestätigung und keinen unvollständigen Ablageeintrag. Der Scanner kann erneut senden.
Der Reverse Proxy muss die genannten HTTP-Methoden, den Authorization-Header und Uploads bis 100 MiB zulassen. Bei einem abgeschnittenen Pfadpräfix sollte er X-Forwarded-Prefix setzen (Traefik StripPrefix erledigt dies). HTTPS endet üblicherweise am bestehenden Proxy.
Die Browser-API unter /api/document-inbox erfordert die normale FEDEO-Anmeldung und einen aktiven Mandanten. Portalbenutzer sind ausgeschlossen. Scanner-Zugänge verwalten nur Administratoren. Die Originale sind außerdem über die bestehende Dateiverwaltung zugänglich.
GET /api/document-inbox/filing-options liefert verfügbare Ordner und Typen. POST /api/document-inbox/:id/file mit JSON { "folder": "<Ordner-UUID oder null>", "type": "<Dateityp-UUID>" } klassifiziert das Original und markiert den Eingang atomar als abgelegt. Für die Hauptebene ist folder als JSON-null zu senden. Ein bereits abgelegtes Dokument ergibt 409; zwischenzeitlich archivierte oder fremde Ziele werden abgewiesen. Dateiänderungen enthalten Zeitpunkt und Benutzer.
POST /api/document-inbox/:id/suggestion liefert { "suggestion": { "folderId": "<UUID oder null>", "typeId": "<UUID>", "confidence": "high|medium", "reason": "…" } } oder einen leeren Vorschlag mit Erklärung. Nur offene, nicht archivierte Dokumente des aktiven Mandanten sind analysierbar. Die Anfrage legt nichts ab; dafür bleibt der separate /file-Aufruf erforderlich.

Lokaler Funktionstest

Mit Testzugangsdaten und einer Test-PDF gegen eine eigene Instanz:

curl --user "$SCANNER_USER:$SCANNER_PASSWORD" --include "$SCANNER_URL"
curl --user "$SCANNER_USER:$SCANNER_PASSWORD" -X PROPFIND -H 'Depth: 0' "$SCANNER_URL"
curl --user "$SCANNER_USER:$SCANNER_PASSWORD" -H 'Content-Type: application/pdf' --upload-file test.pdf "${SCANNER_URL}test.pdf"

Die Vorprüfungen liefern 200 (GET, leerer Inhalt) und 207 (PROPFIND). Der erste Upload liefert 201; eine identische Wiederholung ergibt 204. Anschließend steht genau ein Dokument in der Ablage. Die automatisierten Integrationsprüfungen verwenden eine isolierte PostgreSQL-Datenbank und einen ersetzten Objektspeicher, niemals produktive Zugangsdaten:

cd backend
FEDEO_TEST_POSTGRES_IMAGE=postgres:16-alpine node --import tsx --test tests/scannerInbox.test.ts

11 KiB Raw Blame History