# Schritt 1 - Eingang und Übernahme

> **Zielgruppe & Rolle**
>
> **Rolle**: Technik / Entwickler & Support | **Schritt**: 1 von 5 der Verarbeitungspipeline


# Eingang und Übernahme

> **Ziel des Schritts**
>
> Neue Belege schnell starten, Doppelverarbeitung verhindern und Fehlerfälle kontrolliert nachziehen.


## Eingangskanal und Ablage

Mails des Belegeingangs nimmt ausschließlich das Modul **comms** an (ADR 0009, ADR 0013). Es gibt zwei Quellen mit einem gemeinsamen Intake:

- **Plattform-Adresse (Amazon SES)**: `<lokaler Teil>@<Subdomain des Mandanten>.<Mail-Domain>`. SES legt die Mail im Eingangs-Bucket unter `incoming/` ab und meldet sie über SQS. comms bestimmt den Mandanten aus den Empfängern des Umschlags, kopiert die Mail nach `tenants/<Kundennummer>/<Mandant>/processing/` und löscht sie aus `incoming/`. Mails ohne eindeutigen Mandanten, an deaktivierte Postfächer oder mit Virusbefund von SES landen unter `quarantine/`.
- **Microsoft-365-Postfach**: comms liest das Postfach über Microsoft Graph und verschiebt die Mail nach dem Ergebnis in die konfigurierten Ordner.

Der Mail-Intake übernimmt PDF- und XML-Anhänge (nicht leer, innerhalb der Upload-Grenze des DMS) und die Mail selbst als `.eml`. Mail-Datensatz und die Upload-Befehle an das DMS werden in **einer** Transaktion geschrieben; der Command-Dispatcher stellt sie zu (ADR 0002). Eine Mail, die schon importiert wurde, legt keine neuen Befehle an.

Abgelehnt werden bereits beim Eingang Spam, unlesbare, verschlüsselte oder zu große Mails und Mails ohne PDF- oder XML-Anhang. Der Mandant sieht sie mit Grund in der Liste der importierten Mails.

> **S3 nur im SES-Eingangs-Bucket**
>
> Die Präfixe `incoming/` und `tenants/…/processing|done|rejected/` sind die einzigen S3-Zustände der Strecke. Sie bilden nur den Zustand der **Mail** ab. Dokumente liegen im DMS, der Zustand der Eingangsrechnung in Postgres (trade).


## Zustände einer Mail im Belegeingang

| Zustand | Bedeutung |
| --- | --- |
| `PENDING` | Importiert, die Dokumente sind an das DMS übergeben. |
| `ARCHIVED` → `COMPLETED` | Verarbeitet; die Mail wird an der Quelle abgelegt (SES: `done/`, Microsoft 365: Archivordner). |
| `REJECTED` / `DEAD_LETTER` → `REJECTED_FINAL` | Abgelehnt; die Mail wird an der Quelle als abgelehnt abgelegt (SES: `rejected/`). |
| `RETRY_MANUAL` | Zum erneuten Import freigegeben; comms importiert die Mail neu. |

Das Ergebnis einer Mail melden nachgelagerte Dienste über die interne Status-API von comms; ein Administrator kann eine Mail im Portal erneut importieren.

## Ablage, Malware-Prüfung und Textextraktion im DMS

- Jeder Anhang wird ein DMS-Dokument mit der Rolle **Original-Eingangsbeleg** (`incoming_original`) und der Herkunft `mail`; die `.eml` wird als Dokument der Plattform-Art `mail` ohne Textextraktion abgelegt.
- Jede neue Version ist `PENDING`, bis ClamAV sie geprüft hat. Nur `CLEAN` geprüfte Versionen werden extrahiert und ausgeliefert; `INFECTED` wird gesperrt, ein fehlgeschlagener Scan nach einer Stunde wiederholt.
- Danach liest das DMS den Text (siehe [Schritt 2](/knowledge/docs/products/invoice/technical/step-2-extraction.md)) und ordnet den Dokumenttyp zu. Der Typ bestimmt das Zielmodul; Belege für den Rechnungseingang tragen `targetModule=trade.invoice`.
- Das Ergebnis wird im Outbox-Feed des DMS angekündigt: `dms.document.text_extracted`, `dms.document.text_extraction_failed` und `dms.document.classified`.

## Übernahme durch trade

trade folgt dem DMS-Feed (`GET <DMS>/internal/events`) mit dem Cursor `dms-inbound-invoices` und fragt ihn alle 3 Sekunden ab. Verarbeitet werden:

- `text_extracted` von Dokumenten mit Zielmodul `trade.invoice`, solange die Klassifizierung nicht auf eine Person wartet (`needs_review`),
- `text_extraction_failed` solcher Dokumente (die Rechnung wird `FAILED`),
- `classified`, wenn eine Person das Dokument endgültig dem Rechnungseingang zugeordnet hat.

## Sichere Übernahme pro Beleg

Je DMS-Dokument gibt es genau eine Eingangsrechnung: trade legt sie beim ersten Ereignis mit Status `RECEIVED` an und findet sie bei jedem weiteren Ereignis wieder. Verarbeitet wird nur eine Rechnung in `RECEIVED`, `OCR_DONE` oder `FAILED`; spätere Zustände bleiben unberührt. Statusänderungen werden nur aus dem erwarteten Ausgangsstatus geschrieben – gewinnt ein paralleler Lauf, wird der andere verworfen. Ein laufender Freigabe-Workflow sperrt die Rechnung; das Feed-Ereignis wird dann übersprungen.

Ein Dokument, das bereits als Lieferschein geführt wird, wird übersprungen. Über `POST /api/trade/v1/inbound-invoices` lässt sich auch ein vorhandenes DMS-Dokument als Eingangsrechnung anmelden.

## Fehlerpfad während der Übernahme

- Fehler beim Speichern oder beim Laden des Textes aus dem DMS werden an den Feed zurückgegeben; das Ereignis wird erneut verarbeitet.
- Alle anderen Fehler setzen die Rechnung auf `FAILED` mit Fehlertext (Ereignis `trade.inboundinvoice.failed`), damit ein fehlerhaftes Dokument den Feed nie blockiert.
- `FAILED` oder hängende Rechnungen werden über `POST /api/trade/v1/inbound-invoices/:id/reprocess` aus ihrem DMS-Dokument neu verarbeitet.

## Hängende Verarbeitungen

Einen Stale-Check über S3 gibt es nicht mehr. Die Extraktion im DMS läuft als River-Job mit Lease und höchstens fünf Versuchen; ein Job eines ausgefallenen Pods wird von River neu gestartet. Während eines Laufs zeigt trade den aktuellen Verarbeitungsschritt an der Rechnung (`processing`); eine laufende Verarbeitung lässt sich nicht parallel neu anstoßen.

---

> **Nächster technischer Schritt**
>
> Nach der erfolgreichen Übernahme folgt das Auslesen der Belegdaten:
> [**Schritt 2: Extraktion (E-Rechnung, PDF, Scan)**](/knowledge/docs/products/invoice/technical/step-2-extraction.md)
