ConnectCLOUDDocs

Appearance

invoice-go Architektur & Übersicht ​

Diese Dokumentation bietet einen umfassenden Überblick über die Architektur, den Datenfluss und die Funktionsweise der invoice-go Komponente. Sie dient als zentrale Wissensbasis für Entwickler und Administratoren.

0. Prozess-Visualisierung ​

Der gesamte Lebenszyklus eines Dokuments – vom Eingang bis zur Archivierung – ist in einem detaillierten Mermaid-Diagramm visualisiert: 👉 Prozess-Flussdiagramm

1. Hintergrunddienste & Trigger ​

  • S3 Polling (Eingang): Der InvoiceWorker überwacht kontinuierlich das S3-Eingangsverzeichnis (mail/pending/). Sobald neue Dokumente (E-Mails mit Anhängen oder manuelle Uploads) erkannt werden, wird der Verarbeitungsprozess initiiert.
  • RagSyncWorker: Synchronisiert stündlich Adressen, Artikel und Buchungshistorie (tblTransactions) aus dem microtech ERP in die Vektordatenbank (Qdrant), um die Grundlage für den RAG-Abgleich zu schaffen. Hierbei werden die Daten in überlappende Chunks aufgeteilt und mittels OpenAI-kompatibler Embeddings vektorisiert.
  • ECB Rate Fetcher: Aktualisiert alle 12 Stunden die Währungskurse der EZB und speichert sie im S3-Cache, um die Verarbeitung von Fremdwährungsbelegen zu ermöglichen.
  • Fallback Recovery: Ein stündlicher Hintergrundprozess (RecoveryService), der Dokumente im Status Retry überwacht und basierend auf bereits extrahierten Daten eine automatische Wiederholung der ERP-Anlage anstößt.

2. Einstieg & Infrastruktur ​

S3 Locking & Race-Condition Schutz ​

Bevor ein Dokument verarbeitet wird, muss sichergestellt werden, dass keine zwei Worker-Instanzen dasselbe Dokument gleichzeitig bearbeiten.

  • Ablauf:
    1. Der InvoiceWorker generiert eine eindeutige holderId (UUID).
    2. Das Dokument wird von mail/pending/ nach mail/processing/ verschoben.
    3. Die holderId wird atomar in den S3-Metadaten hinterlegt.
    4. Nur wenn die gelesene ID mit der eigenen übereinstimmt, beginnt die Verarbeitung.
  • Stale-Check: Dokumente, die zu lange in processing verweilen (z. B. nach einem Crash), werden automatisch zurück nach retry verschoben.

3. Extraktions-Workflows ​

Das System nutzt zwei Pfade, um Daten zu gewinnen. Beide münden im einheitlichen Common-Format (IncomingInvoice-Modell).

Pfad A: E-Rechnungen (kosit-go) ​

  • Technik: Nutzt die kosit-go Bibliothek zum direkten Auslesen von XML-Daten (ZUGFeRD, XRechnung/UBL/CII).
  • Vorteil: Keine KI-Klassifizierung nötig. Belegtyp und alle Kopf-/Positionsdaten stammen direkt aus dem maschinenlesbaren XML.

Pfad B: PDF & Scans (KI/LLM) ​

  • Textextraktion: Digitale PDFs werden via Apache Tika ausgelesen.
  • LLM-Vision (OCR-Fallback): Falls Tika keinen Text findet (z. B. bei Handyfotos), "sieht" sich die KI den Scan visuell an.
  • KI-Klassifizierung: Bestimmt den Dokumenttyp ausschließlich über UN/EDIFACT 1001 Codes (z. B. 380 für Rechnungen, 381 für Gutschriften, 384 für Rechnungskorrekturen, 389 für Gutschriftverfahren). Weitere Details zu Klassifizierungsregeln und zur Überschreibung der microtech Belegtypen via invTypes finden sich in 👉 Dokumentenklassifizierung.
    • 999 (Sonstige / Nicht-relevant, z. B. Lieferscheine/Werbung -> werden sofort archiviert)
  • KI-Extraktion: Wandelt unstrukturierten Text in ein exaktes JSON-Schema (IBAN, Beträge, Steuern, Positionen) um.

4. Währungskurse (ECB Service) ​

Für Belege, die nicht in EUR ausgestellt sind, ermittelt das System automatisch den passenden Wechselkurs:

  • Datenquelle: Die Europäische Zentralbank (EZB).
  • Synchronisation: Ein Hintergrund-Prozessor (ECB Rate Fetcher) lädt alle 12 Stunden die aktuellen Kurse und speichert sie im S3-Cache.
  • Logik: Der Service sucht im Cache nach dem Kurs zum Belegdatum. Wird kein exakter Treffer gefunden (z. B. Wochenende), wird bis zu 6 Tage in die Vergangenheit gesucht, um den letzten verfügbaren Kurs zu nutzen.

5. Stammdaten-Enrichment (RAG / KI) ​

Dieser Schritt reichert den "rohen" Beleg mit ERP-Informationen aus microtech an.

Vendor Lookup (Lieferanten-Erkennung) ​

  • Suche: Semantischer Abgleich via Qdrant Vektordatenbank basierend auf Name, Anschrift, USt-IdNr und IBAN.
  • Fallback-Vendor: Wird kein eindeutiger Kreditor gefunden, nutzt das System einen konfigurierten Sammel-Kreditor (z. B. "99999"). Der Beleg wird in diesem Fall im ERP automatisch gesperrt (fldGspKz: true), um eine manuelle Zuordnung zu erzwingen.

Positionen-Matching (Artikel-Zuordnung) ​

Das System nutzt ausschließlich die letzten 200 buchungsrelevanten Vorgänge (tblTransactions) des Mandanten als Datenbasis:

  • Priorität 1: Bestellnummer: Exakter Treffer der Lieferanten-Artikelnummer (fldBstNr) innerhalb der historischen Vorgänge.
  • Priorität 2: Semantik: KI-gestützte Suche über den Positionstext, ebenfalls basierend auf den historischen Transaktionsdaten und eingeschränkt auf den identifizierten Lieferanten.
  • Anreicherung: Identifiziert die interne ArticleNo und die zugehörige Kostenstelle (CostCenterNo) aus der gefundenen historischen Buchung.

6. Gesetzliche Prüfung (§ 14 UStG) ​

Diese Prüfung stellt die steuerliche Konformität der Belege sicher.

  • Trigger: Die Prüfung erfolgt automatisch für jeden buchungsrelevanten Beleg (380, 381, 384, 389 etc.). Dokumente vom Typ 999 (z. B. Lieferscheine) überspringen diesen Schritt.
  • Schwellenwert (250€-Grenze): Das System unterscheidet zwischen Standardrechnungen und Kleinbetragsrechnungen gemäß § 33 UStDV.
    • Der Schwellenwert liegt bei 250,00 € Brutto.
    • Bei Fremdwährungen wird der Betrag mittels des aktuellen ECB-Kurses in EUR umgerechnet, um die Grenze zu bestimmen.

Prüffelder bei Standardrechnungen (> 250 €):

  1. Leistender Unternehmer: Vollständiger Name und Anschrift.
  2. Leistungsempfänger: Vollständiger Name und Anschrift (Abgleich gegen Mandanten-Stammdaten).
  3. Steuernummer/USt-IdNr: Angabe der Steuernummer oder USt-IdNr des Ausstellers.
  4. Rechnungsnummer: Eindeutige, fortlaufende Nummer (ReceiptNo).
  5. Datum: Rechnungsdatum und Leistungs-/Lieferdatum.
  6. Positionen: Menge und Art der gelieferten Gegenstände oder sonstigen Leistungen.
  7. Entgelte & Steuern: Aufschlüsselung nach Steuersätzen, Nettobeträgen und Steuerbeträgen.
  8. Hinweise: Pflichtangaben wie "Gutschrift" (bei Typ 381), "Steuerbefreiung" oder "Reverse-Charge".

Prüffelder bei Kleinbetragsrechnungen (≤ 250 €): Hier gelten erleichterte Bedingungen gemäß § 33 UStDV. Folgende Angaben werden nicht geprüft bzw. sind nicht zwingend erforderlich:

  • Name und Anschrift des Leistungsempfängers (deine Firmendaten).
  • Steuernummer oder USt-IdNr des leistenden Unternehmers.
  • Eine eindeutige Rechnungsnummer.
  • Der Zeitpunkt der Lieferung oder sonstigen Leistung (Leistungsdatum).
  • Die Aufschlüsselung in Netto-Betrag und Steuerbetrag (Angabe von Bruttobetrag und Steuersatz genügt).

Erforderliche Kernfelder (IMMER erforderlich): Unabhängig vom Betrag müssen gemäß der Systemlogik und dem Gesetz immer vorhanden sein:

  • Vollständiger Name und Anschrift des Leistenden (Lieferant).
  • Das Ausstellungsdatum der Rechnung.
  • Menge und Art der gelieferten Gegenstände oder Leistung.
  • Der Bruttobetrag sowie der anzuwendende Steuersatz (oder ein Hinweis auf Steuerbefreiung).

7. AuditService (KI-Entscheidung) ​

Bei Diskrepanzen (z. B. Rundungsdifferenzen, Dublettenverdacht oder abweichende Namen), die während der Validierung oder dem Stammdaten-Abgleich festgestellt wurden, wird ein High-Reasoning KI-Modell eingeschaltet:

  • Bewertung: Die KI beurteilt, ob eine Abweichung plausibel ist (z. B. "Muster GmbH" vs. "Muster Holding").
  • Freigabe: Die KI entscheidet über Approved (direkte Anlage) oder Manual Review (Anlage mit Sperrkennzeichen).
  • Dokumentation: Jede Entscheidung der KI wird mit einem detaillierten Reasoning begründet, das im ERP am Beleg eingesehen werden kann.

8. Zustellung & ERP-Integration ​

Anlage im ERP ​

Der Beleg wird via GraphQL im microtech ERP angelegt. Dabei entscheidet das System, ob der Beleg sofort zur weiteren Bearbeitung freigegeben wird oder mit einem Sperrkennzeichen (fldGspKz: true) versehen wird.

  • Direkt (Freigegeben): Wenn alle Prüfungen erfolgreich waren und keine Diskrepanzen vorliegen.
  • Gesperrt (Sperrkennzeichen): In diesem Fall wird der Grund der Sperre im Feld fldGspInfo im ERP hinterlegt.

Gründe für eine automatische Sperre ​

Ein Beleg wird in folgenden Fällen gesperrt angelegt, um eine manuelle Nachprüfung zu erzwingen:

  1. Fallback-Kreditor verwendet: Der Lieferant konnte nicht eindeutig identifiziert werden, und es wurde auf den Sammel-Kreditor (z. B. "99999") zurückgegriffen.
  2. Fehlende Artikelnummern: Eine oder mehrere Positionen konnten nicht automatisch einem ERP-Artikel zugeordnet werden (Matching fehlgeschlagen).
  3. Potenzielle Dubletten: Es existiert bereits ein Beleg mit der gleichen Rechnungsnummer beim identifizierten Kreditor.
  4. Gesetzliche Mängel (§ 14 UStG): Pflichtangaben fehlen oder sind fehlerhaft (z. B. fehlendes Leistungsdatum oder falscher Steuersatz).
  5. Ungültige E-Rechnung: Die technische Validierung des XML-Datensatzes (Schematron) durch kosit-go war nicht erfolgreich.
  6. Fachliche Diskrepanzen: Abweichungen zwischen den extrahierten Daten und den ERP-Stammdaten (z. B. abweichende IBAN, Währung oder Rundungsdifferenzen im Bruttobetrag).
  7. KI-Audit Veto: Der AuditService hat die gefundenen Diskrepanzen bewertet und eine manuelle Prüfung empfohlen (Manual Review).
  8. Audit-Fehler: Tritt während des Audit-Prozesses ein technischer Fehler auf (z. B. Timeout der KI), wird der Beleg sicherheitshalber gesperrt.

Status-Management ​

  • Archived: Erfolgreich verarbeitet (auch wenn im ERP gesperrt).
  • DeadLetter: Permanent fehlgeschlagen (z. B. nach 5 Fehlversuchen). Diese Dokumente werden von mail-go aufgegriffen, um den Absender im Postfach zu benachrichtigen.
  • RejectedFinal: Endzustand nach der Benachrichtigung durch mail-go.

9. Fehlerbehandlung & Retry-Logik ​

Das System ist auf maximale Robustheit ausgelegt:

  • Technischer Fehler: Schlägt die Anlage im ERP fehl (z. B. Timeout), wird der Beleg in den Status Retry verschoben.
  • Schleife: Der Worker prüft alle 60 Sekunden auf Retry-Dokumente und startet den Prozess neu.
  • Limit: Nach 5 Fehlversuchen wird der Beleg nach DeadLetter verschoben. Dabei wird die letzte Fehlermeldung in den S3-Metadaten (last-error) gespeichert.
  • Outlook-Integration: Der mail-go Service pollt auf den DeadLetter Status. Er extrahiert den Fehlergrund, aktualisiert den Betreff und den Body der ursprünglichen E-Mail in Outlook (Rejection Hint) und verschiebt die Mail in den konfigurierten "Rejected"-Ordner. Abschließend wird der Status in S3 auf RejectedFinal gesetzt.
  • Fallback Service: Ein stündlicher Hintergrundprozess (Recovery) versucht zusätzlich, hängengebliebene Dokumente basierend auf bereits extrahierten Metadaten zu retten.

10. Die kosit-go Bibliothek ​

kosit-go ist eine spezialisierte, in Eigenregie entwickelte Go-Bibliothek zur Verarbeitung von elektronischen Rechnungen (E-Rechnungen) nach europäischen Standards (EN 16931). Sie dient als technisches Fundament für die Verarbeitung maschinenlesbarer Formate ohne den Einsatz von KI.

Kernfunktionen ​

  1. Extraktion (Parsing):
    • Unterstützt UBL (Universal Business Language) und CII (Cross Industry Invoice / ZUGFeRD).
    • Wandelt die komplexen XML-Strukturen in ein internes Common Data Model (CDM) um, das dann vom invoice-go Service in das Common-Format überführt wird.
  2. Validierung (Schematron):
    • Implementiert einen nativen Go-Schematron-Runner (basierend auf XPath).
    • Prüft Dokumente gegen offizielle Regelwerke der KoSIT (Koordinierungsstelle für IT-Standards), wie z. B. XRechnung-Validierungsstufen.
    • Sichert die technische Korrektheit der Belege ab, bevor diese in das ERP-System gelangen.
  3. Visualisierung (XSLT):
    • Nutzt eine XSLT 3.0 Engine, um aus den XML-Rohdaten menschenlesbare HTML-Dokumente ("Sichtbelege") zu generieren.
    • Ermöglicht die Erstellung von PDF-Vorschauen für rein XML-basierte Rechnungen.