feat(documents): prepare inbox suggestions and add entity assignments

docs/scanner-dokumentenablage.md

@@ -1,15 +1,16 @@
 # 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.
+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. Ein Badge am Menüeintrag zählt die offenen, nicht archivierten Dokumente unabhängig von der aktuellen Suche. Es aktualisiert sich alle zehn Sekunden und unmittelbar nach dem Ablegen. Jede übertragene Datei wird unverändert als ein Dokument gespeichert. Ein mehrseitiges PDF bleibt ein Dokument. Nach dem erfolgreichen Empfang wird die KI-Zuordnung im Hintergrund vorbereitet; der Scanner muss darauf nicht warten. Seitentrennung und Rechnungsverarbeitung werden nicht ausgelöst.
 
 ## In Dateien ablegen
 
 1. Auf den Dateinamen, **Vorschau** oder **Ablegen** klicken. Das Modal zeigt das Original und rechts die Zuordnung.
-2. 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.
+2. Das Modal lädt den bereits vorbereiteten KI-Vorschlag für Ordner und Dokumenttyp. Läuft die Vorbereitung noch, zeigt es den Fortschritt und lädt das Ergebnis automatisch nach. 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** stellt eine abgeschlossene oder fehlgeschlagene Analyse erneut in die Warteschlange.
 3. 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.
-4. 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.
+4. Optional unter **Zuordnungen** einen Bereich und einen Eintrag auswählen und mit **Zuordnung hinzufügen** vormerken. Wie auf der Dateiseite stehen Projekt, Kunde, Lieferant, Fahrzeug, Objekt, Vertrag, Produkt, Ausgangsbeleg, Eingangsrechnung, Inventarartikel, Überprüfung und Mitarbeiter zur Verfügung. Mehrere Bereiche können gleichzeitig zugeordnet werden, jeweils ein Eintrag pro Bereich. Die Einträge lassen sich nach Namen suchen; bestehende Zuordnungen werden angezeigt und können entfernt werden.
+5. Erst **Übernehmen und ablegen** speichert Ordner, Typ und vorgemerkte Zuordnungen gemeinsam am bestehenden Original. Danach verschwindet das Dokument aus dem Eingang und ist unter **Dateien** im gewählten Ordner und mit den gewählten Verknüpfungen 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.
+Nur aktive Ordner, Typen und Zuordnungsziele desselben Mandanten sind zulässig. Mitarbeiter müssen aktiv und interne Benutzer sein. Bei einem Fehler bleibt das Dokument im Eingang; auch die übrigen Änderungen werden nicht teilweise gespeichert. Ein erneuter Scanner-Upload mit demselben Namen und Inhalt bestätigt weiterhin den ursprünglichen Empfang, ohne einen neuen Eingangseintrag oder Analyseauftrag anzulegen.
 
 ### KI-Vorschläge
 
@@ -17,7 +18,9 @@ Die Analyse nutzt die bestehende zentrale FEDEO-KI-Anbindung oder den konfigurie
 
 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.
+Vorschläge und erkannter Text verändern weder das Original noch dessen Klassifizierung. Der Auftrag entsteht zusammen mit dem Eingangseintrag in der Datenbank. Das Backend verarbeitet offene Aufträge automatisch, auch ohne geöffnete Dokumentenablage. Vorschlag, Status und eine gegebenenfalls nötige Fehlermeldung werden dauerhaft am Eingangseintrag gespeichert; beim Wiederöffnen wird keine neue Analyse ausgelöst. Erkannter Volltext wird hierfür nicht gespeichert. Vorhandene offene Dokumente werden nach der Migration ebenfalls vorbereitet.
+
+Pro Backend-Prozess läuft eine Analyse gleichzeitig. Datenbanksperren und Auftragskennungen koordinieren mehrere Instanzen. Neue Aufträge werden spätestens beim nächsten Durchlauf nach zwei Sekunden berücksichtigt, wenn kein älterer Auftrag mehr läuft. Nach einem Prozessabbruch werden seit fünf Minuten nicht abgeschlossene Aufträge erneut übernommen; verspätete Ergebnisse eines alten Auftrags können das neuere Ergebnis nicht überschreiben. Abgelegte, archivierte und Dokumente von Mandanten im Wartungsmodus werden nicht neu gestartet. Fehlgeschlagene Analysen lassen sich im Modal erneut anfordern; die manuelle Ablage bleibt möglich. Die fachliche Qualität der KI-Vorschläge sollte bei der Inbetriebnahme mit eigenen Beispieldokumenten geprüft werden.
 
 ## Einrichtung
 
@@ -36,7 +39,7 @@ Nach der Dateinamenprüfung sendet der ES-580W zunächst einen leeren `PUT` mit
 
 ## 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.
+- Datenbankmigrationen `0073_scanner_document_inbox`, `0074_scanner_inbox_filing` und `0077_scanner_inbox_preparation` werden über die reguläre Drizzle-Migration eingespielt. Keine neuen Umgebungsvariablen oder zusätzlichen Dienste sind erforderlich; der vorhandene S3-kompatible Dateispeicher wird genutzt. Die Hintergrundverarbeitung startet mit dem Backend.
 - 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.
@@ -44,8 +47,9 @@ Nach der Dateinamenprüfung sendet der ES-580W zunächst einen leeren `PUT` mit
 - 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.
+- `GET /api/document-inbox/count` liefert `{ "total": 3 }` für den aktiven Mandanten. `GET /api/document-inbox/filing-options` liefert verfügbare Ordner, Typen und `assignmentKinds`. `GET /api/document-inbox/assignment-options?kind=project&search=Beispiel` liefert bis zu 100 passende Ziele mit `id` und `name`; `GET /api/document-inbox/:id/assignments` die bereits bestehenden Verknüpfungen des Dokuments.
+- `POST /api/document-inbox/:id/file` mit JSON `{ "folder": "<Ordner-UUID oder null>", "type": "<Dateityp-UUID>", "assignments": { "project": 123, "customer": 456 } }` klassifiziert das Original, speichert die optionalen Verknüpfungen und markiert den Eingang atomar als abgelegt. Weggelassene Zuordnungen bleiben erhalten; JSON-`null` entfernt eine vorhandene Zuordnung. Die Schlüssel entsprechen den Dateifeldern; `check` und `authProfile` verwenden UUIDs, die übrigen Bereiche numerische IDs. 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.
+- `GET /api/document-inbox/:id/suggestion` liest den gespeicherten Status `pending`, `processing`, `ready` oder `failed` und liefert bei Erfolg beispielsweise `{ "status": "ready", "suggestion": { "folderId": "<UUID oder null>", "typeId": "<UUID>", "confidence": "high|medium", "reason": "…" } }`. Ohne passende Zuordnung ist `suggestion` gleich `null` und `message` erklärt den Grund. `POST /api/document-inbox/:id/suggestion` fordert eine erneute Vorbereitung an und antwortet mit `202` und demselben Statusformat, ohne auf die Analyse zu warten. Ein bereits wartender oder laufender Auftrag wird nicht dupliziert. Nur offene, nicht archivierte Dokumente des aktiven Mandanten sind zugänglich. Diese Anfragen legen nichts ab; dafür bleibt der separate `/file`-Aufruf erforderlich.
 
 ## Lokaler Funktionstest