# Prozessverlauf (comms, DMS, trade)

> **Zielgruppe & Rolle**
>
> **Rolle**: Technik / Entwickler & Systemintegratoren | **Bereich**: Systemarchitektur & End-to-End-Prozessverlauf


# Prozessverlauf (comms, DMS, trade)

Die automatisierte Verarbeitungsstrecke für Eingangsbelege ist auf drei Module verteilt: **comms** nimmt die Mails des Belegeingangs an, das **DMS** speichert, prüft und liest die Dokumente, **trade** wertet sie als Eingangsrechnungen aus – von der Extraktion über Stammdatenzuordnung und steuerliche Belegprüfung bis zum Bestellabgleich und zur Freigabe. Die Module sprechen über REST: comms übergibt Dokumente per Upload-Befehl an das DMS, das DMS kündigt Ergebnisse in seinem Outbox-Feed an, trade folgt diesem Feed (ADR 0002).


## End-to-End Prozess-Visualisierung

Der gesamte Lebenszyklus eines Dokuments vom Eingang bis zur Freigabe ist im folgenden Ablaufdiagramm dargestellt:

```mermaid
flowchart TD
    %% 1. EINGANG
    subgraph S1["1. Eingang & Übernahme"]
        A[Mail an die Belegeingangsadresse] --> A1{Quelle}
        A1 -- "SES-Plattformadresse" --> B[SES legt die Mail unter incoming/ ab, SQS meldet sie]
        A1 -- "Microsoft-365-Postfach" --> B1[comms liest das Postfach über Microsoft Graph]
        B --> C[comms ordnet den Mandanten zu und kopiert nach tenants/…/processing/]
        B1 --> D
        C --> D[Mail-Intake: Mail-Datensatz + DMS-Upload-Befehle in einer Transaktion]
        D --> E[DMS speichert PDF/XML-Anhänge als Original-Eingangsbeleg, die Mail als .eml]
        E --> F{ClamAV-Prüfung}
        F -- "INFECTED" --> F1[Version gesperrt, keine Extraktion]
        F -- "CLEAN" --> G[DMS-Extraktion & Dokumentklassifizierung]
        G --> H[Feed-Ereignis text_extracted / text_extraction_failed / classified]
        H --> I[trade: Eingangsrechnung je DMS-Dokument, Status RECEIVED]
    end

    %% 2. EXTRAKTION
    subgraph S2["2. Extraktion"]
        I --> J{E-Rechnung?}
        J -- "XRechnung CII/UBL, ZUGFeRD" --> K[kosit-Bibliothek: XML ins Common-Format]
        J -- "PDF / Scan / Bild" --> L[Text aus dem DMS laden]
        L --> M[KI-Klassifizierung, Rolle weak]
        M -- "999" --> M1[REJECTED: keine Rechnung]
        M -- "270" --> M2[Übergabe an die Lieferscheine]
        M -- "380 / 381 / 384" --> N[KI-Extraktion, Rolle medium]
        K --> O[EXTRACTED: Extraktion gespeichert]
        N --> O
    end

    %% 3. ENRICHMENT
    subgraph S3["3. Währung & Enrichment"]
        O --> P[Lieferant: USt-IdNr, IBAN, Vektorsuche, KI-Entscheidung, Sammellieferant]
        P --> Q[Artikel: Artikelnummer, Lieferanten-Artikelnummer, Vektorsuche, KI-Entscheidung]
        Q --> R[EZB-Kurs aus masterdata, Skonto und Zahlungsziel]
    end

    %% 4. PRÜFUNG
    subgraph S4["4. Belegprüfung"]
        R --> S[§ 14 UStG: Pflichtangaben und Steuerrechnung]
        S --> T[Empfänger-USt-IdNr, Pflicht zur E-Rechnung, Erkennungssicherheit]
        T --> U{Dublette?}
    end

    %% 5. BESTELLABGLEICH & FREIGABE
    subgraph S5["5. Bestellabgleich & Freigabe"]
        U -- Ja --> V[DUPLICATE]
        U -- Nein --> W[Bestellabgleich gegen Bestellung und Wareneingänge]
        W --> X{Blockierende Sperrgründe?}
        X -- Nein --> Y[MATCHED]
        X -- Ja --> Z[DISCREPANCY]
        Y --> AA{Automatische Freigabe aktiv und zulässig?}
        AA -- Ja --> AB[RELEASED]
        AA -- Nein --> AC[Freigabe durch Person oder Freigabe-Workflow]
        Z --> AD[Prüfung: korrigieren, Sperrgrund akzeptieren, Abgleich erneut]
        AD --> AC
        AC --> AB
        AC --> AE[REJECTED]
    end

    style S1 fill:#f0f4f9,stroke:#3b82f6,stroke-width:1px
    style S2 fill:#f0fdf4,stroke:#22c55e,stroke-width:1px
    style S3 fill:#fefce8,stroke:#eab308,stroke-width:1px
    style S4 fill:#fff7ed,stroke:#f97316,stroke-width:1px
    style S5 fill:#fdf2f8,stroke:#ec4899,stroke-width:1px
```



## Architektur & Hintergrunddienste

- **Belegeingang (comms)**: Der SES-Importer liest die SQS-Meldungen zu neuen Mails im SES-Eingangs-Bucket, der Postfach-Importer liest Microsoft-365-Postfächer über Microsoft Graph. Beide nutzen denselben Mail-Intake: Mail-Datensatz und Upload-Befehle an das DMS werden in einer Transaktion geschrieben und vom Command-Dispatcher zugestellt.
- **Malware-Prüfung, Extraktion und Klassifizierung (DMS)**: Jede neue Version wird mit ClamAV geprüft; erst eine saubere Version wird extrahiert (River-Job `dms.extraction`). Danach ordnet der Dokumentklassifizierer Original-Eingangsbelege einem Dokumenttyp zu; der Typ bestimmt das Zielmodul (`trade.invoice` für den Rechnungseingang).
- **Feed-Konsument (trade)**: Folgt dem Outbox-Feed des DMS (`/internal/events`, Cursor `dms-inbound-invoices`, alle 3 Sekunden) und verarbeitet die Ereignisse idempotent je DMS-Dokument. Rechnungen und Lieferscheine teilen sich diesen Cursor.
- **Semantischer Index (trade)**: Lieferanten und aktive Artikel aus masterdata liegen mit Embeddings in Postgres (pgvector). Gefüllt wird der Index aus dem Feed von masterdata, über die Synchronisation in den Einstellungen und den Job `trade.index-backfill`.
- **Währungskurse (masterdata)**: masterdata lädt die EZB-Referenzkurse täglich und speichert sie; trade liest sie über `GET /internal/exchange-rates` und ruft die EZB nie selbst auf.
- **Freigabe-Workflows (workflow)**: Freigabe-Vorlagen des Moduls `workflow` nehmen Eingangsrechnungen über die interne Transaktions-API von trade auf (z. B. `MATCHED` zur Freigabe, `DISCREPANCY`/`IN_REVIEW` zur Klärung). Solange ein Workflow läuft, ist die Rechnung für andere Änderungen gesperrt.



## Die 5 Kernphasen des Prozessverlaufs

### 1. Eingang & Übernahme
comms ordnet jede Mail genau einem Mandanten zu und übergibt PDF- und XML-Anhänge als Original-Eingangsbelege an das DMS. Das DMS prüft sie mit ClamAV, extrahiert den Text und kündigt das Ergebnis im Feed an. trade legt je DMS-Dokument genau eine Eingangsrechnung an – auch bei wiederholt zugestellten Ereignissen.

[Detaillierte Dokumentation zu Schritt 1: Eingang und Übernahme](/knowledge/docs/products/invoice/technical/step-1-receipt-and-intake.md)

### 2. Extraktion & Belegklassifizierung
Die Extraktion führt beide Wege in dasselbe Datenmodell (`Extraction`):
- **E-Rechnungen**: XRechnung (CII/UBL) und ZUGFeRD/Factur-X werden mit der kosit-Bibliothek direkt aus dem XML gelesen; dafür ist keine KI nötig.
- **PDF & Scans**: Den Text liefert das DMS (Textebene des PDFs, KI-OCR über das Modul `ai`). trade klassifiziert den Beleg nach UN/EDIFACT 1001 und extrahiert Kopf- und Positionsdaten mit einem KI-Modell. Nicht-Rechnungen (`999`) werden abgelehnt, Lieferscheine (`270`) an die Lieferscheinverarbeitung übergeben.

[Detaillierte Dokumentation zu Schritt 2: Extraktion](/knowledge/docs/products/invoice/technical/step-2-extraction.md) | [Feldzuordnung E-Rechnung](/knowledge/docs/products/invoice/technical/field-mapping.md)

### 3. Währung & Stammdaten-Enrichment
Lieferant und Artikel werden zuerst exakt (USt-IdNr, IBAN, Artikelnummern) in masterdata gesucht, dann semantisch im pgvector-Index; unklare Treffer entscheidet ein KI-Modell. Fremdwährungsbeträge werden mit dem EZB-Kurs aus masterdata in EUR umgerechnet; Skonto und Zahlungsziel werden aus den Zahlungsbedingungen gelesen.

[Detaillierte Dokumentation zu Schritt 3: Währung und Enrichment](/knowledge/docs/products/invoice/technical/step-3-currency-and-enrichment.md)

### 4. Gesetzliche Belegprüfung (§ 14 UStG)
Die Pflichtangaben nach § 14 Abs. 4 UStG und die Steuerrechnung werden geprüft; jeder Verstoß wird ein blockierender Sperrgrund. Dazu kommen die Prüfung der Empfänger-USt-IdNr, die optionale Pflicht zur E-Rechnung, unsichere KI-Erkennung und die Dublettenprüfung.

[Detaillierte Dokumentation zu Schritt 4: Belegprüfung](/knowledge/docs/products/invoice/technical/step-4-business-and-legal-validation.md)

### 5. Bestellabgleich & Freigabe
Rechnungen (Code `380`) werden gegen eine Bestellung und deren Wareneingänge abgeglichen (Preis, Menge, Steuer, gelieferte Menge). Ohne blockierende Sperrgründe ist die Rechnung `MATCHED` und kann automatisch, durch eine Person oder durch einen Freigabe-Workflow freigegeben werden (`RELEASED`); sonst steht sie in `DISCREPANCY` zur Prüfung.

[Detaillierte Dokumentation zu Schritt 5: Bestellabgleich und Freigabe](/knowledge/docs/products/invoice/technical/step-5-audit-erp-posting-and-status.md) | [Sperrgründe](/knowledge/docs/products/invoice/technical/lock-reasons.md)


## Stabilität, Wiederholungen & Fehlerbehandlung

- **Feed mit Wiederholung**: Fehler beim Speichern oder beim Laden des Textes aus dem DMS bleiben im Feed stehen – das Ereignis wird erneut verarbeitet. Alle anderen Fehler setzen die Rechnung auf `FAILED`, damit ein fehlerhaftes Dokument den Feed des Mandanten nie blockiert.
- **Erneut verarbeiten**: `FAILED` (oder hängende) Rechnungen lassen sich mit `POST /api/trade/v1/inbound-invoices/:id/reprocess` aus ihrem DMS-Dokument neu verarbeiten.
- **Lücken im Feed**: Ist der Cursor hinter die aufbewahrten Ereignisse des DMS gefallen, beginnt der Konsument beim ältesten vorhandenen Ereignis; die Verarbeitung ist je Dokument idempotent.
- **Wiederholungen im DMS**: Die Extraktion versucht ein Dokument bis zu fünfmal; danach meldet das DMS `dms.document.text_extraction_failed` und trade setzt die Rechnung auf `FAILED`.
- **Mails im Belegeingang**: comms führt den Zustand jeder Mail in Postgres; ein Administrator kann eine Mail in der Liste der importierten Mails erneut importieren.



## E-Rechnungen und der kosit-Dienst

- **Einlesen**: DMS und trade lesen XRechnung (UBL und CII) und ZUGFeRD/Factur-X mit der Bibliothek des kosit-Moduls (`kosit/pkg/extraction`) in ein einheitliches Datenmodell (CDM).
- **Konformitätsprüfung**: Die Prüfung mit dem offiziellen KoSIT-Validator (Sidecar des kosit-Dienstes, ADR 0035) läuft für ausgestellte Rechnungen und im E-Rechnungs-Validator des Portals; die Eingangsrechnungs-Pipeline liest E-Rechnungen, ruft den Validator aber nicht auf.
- **Sichtbeleg**: Die HTML-Darstellung (offizielle xrechnung-visualization) erzeugt der kosit-Dienst bei Bedarf; gespeichert wird sie nicht.


> **Detaillierten Ablauf schrittweise verfolgen**
>
> Beginnen Sie mit der ersten Verarbeitungsphase der Pipeline:
> [**Schritt 1: Eingang und Übernahme**](/knowledge/docs/products/invoice/technical/step-1-receipt-and-intake.md)
