feat(email): suggest entity links with AI when opening messages

docs/bedienung/email-ki-zuordnung.md

@@ -0,0 +1,21 @@
+# KI-Zuordnung von E-Mails
+
+Beim Öffnen einer E-Mail im Postfach startet die Analyse im Hintergrund. Unter „KI-Zuordnungsvorschläge“ erscheinen bis zu fünf Vorschläge für Kunden, Lieferanten, Projekte und Objekte mit Begründung und Einschätzung der Übereinstimmung. „Übernehmen“ legt die jeweilige Verknüpfung an. Die manuelle Zuordnung bleibt verfügbar.
+
+Die Analyse wird pro Mail gespeichert, auch wenn sie keine Treffer findet. Erneutes Öffnen verwendet das gespeicherte Ergebnis. „Erneut prüfen“ aktualisiert die Analyse, beispielsweise nach Änderungen an Stammdaten. Bereits verknüpfte Entitäten werden ausgeblendet. Fehler werden nicht gespeichert und können erneut versucht werden.
+
+## Betrieb
+
+Vor dem Einsatz die Backend-Migrationen mit `npm run migrate` im Backend-Verzeichnis ausführen. Migration `0068_email_entity_suggestions` ergänzt den Ergebnisspeicher. Die Erkennung nutzt wie die bestehende Rechnungserkennung den konfigurierten zentralen KI-Dienst oder `OPENAI_API_KEY`, mit dem bestehenden Modell `gpt-4o`. Ohne KI-Konfiguration erscheint eine Meldung im Postfach.
+
+Übermittelt werden Betreff, Absender, Empfänger, CC und bis zu 16.000 Zeichen Mailtext (ersatzweise HTML ohne Tags oder Vorschautext). Anhänge werden nicht analysiert. Stammdaten werden auf den aktuellen Mandanten und nicht archivierte Einträge begrenzt; übertragen werden Name, Typ, ID, Nummer und vorhandene E-Mail-Adressen. Bei mehr als 150 Einträgen priorisiert eine lokale Vorauswahl passende Adressen, Nummern und Namen. Dadurch können bei großen Datenbeständen rein semantische Zusammenhänge außerhalb dieser Vorauswahl unentdeckt bleiben.
+
+Der Zugriff auf die Mail wird vor Analyse und Cache-Zugriff anhand von Mandant und Benutzer geprüft. Modellantworten werden gegen die angebotenen Stammdaten validiert. Parallele Anfragen für dieselbe Mail werden innerhalb eines Backend-Prozesses zusammengefasst. Mehrere Backend-Instanzen können beim erstmaligen Öffnen gleichzeitig analysieren.
+
+## Prüfung
+
+- Backend: `npx tsc --noEmit`
+- Regressionstests: `node --import tsx tests/emailEntitySuggestions.test.ts`
+- Frontend: `npm run build`
+
+Eine fachliche Prüfung mit echten Mails erfolgt nach Migration und mit konfiguriertem KI-Dienst. KI-Vorschläge müssen vor der Übernahme vom Benutzer geprüft werden.