System-Enzyklopädie: KAI Backend

Version: 34.0 (Final Production - Extended)

Stand: 20.11.2025

Detaillierte technische Referenz aller Module, Endpunkte, Datenbank-Logiken und Hintergrundprozesse.

1. E-Commerce & Einnahmen (shopwaresql.py)

Kernkompetenz: Direkte SQL-Extraktion
Dieses Modul umgeht die langsame Shopware-API und greift direkt lesend auf die MySQL-Datenbank des Shops zu. Dies ermöglicht den Export von tausenden Bestellungen in Sekunden für den Monatsabschluss.
TASK shopware_extract_and_export_csv_task SQL Extraktion
  • Sinn & Zweck: Erstellt die Grundlage für die Umsatzsteuer-Voranmeldung durch Export aller bezahlten Bestellungen.
  • SQL-Logik:
    • Verbindet Tabellen order, order_customer, state_machine_state (Status), order_address (Rechnung/Lieferung), order_line_item (Produkte).
    • Extrahiert Nettobeträge, Steuerbeträge und Bruttobeträge direkt aus den JSON-Feldern der DB (JSON_EXTRACT(o.price, '$.totalPrice')).
    • Filtert exakt nach Status-IDs (z.B. "Komplett abgeschlossen" oder "Versandt"), um nur buchungsrelevante Umsätze zu erfassen.
  • Output: Eine CSV-Datei, die exakt dem Lexoffice-Importformat entspricht.
TASK shopware_upload_csv_to_lexoffice_task Lexoffice Bridge
  • Sinn & Zweck: Überträgt die generierte CSV-Datei vollautomatisch in das Buchhaltungssystem.
  • Logik: Nimmt die lokale CSV aus dem /exports Ordner und übergibt sie an die Lexoffice-Import-Logik. Definiert dabei Steuersatz und Buchungskategorie (z.B. "Erlöse 19%").
GET /shopware/accounts/{account_name}/statuses Status Mapping
  • Sinn & Zweck: Lädt dynamisch alle verfügbaren Bestell- und Zahlungsstatus aus der Shop-DB.
  • Logik: Nutzt Fallback-Queries, um sowohl alte Shopware-Versionen als auch neue Versionen (mit Translation-Tables) zu unterstützen.

2. Lexoffice Buchhaltung (lexoffice.py)

Vollständige Integration zur Automatisierung von Belegen, Kontakten und Buchungen.

TASK run_full_accounting_workflow_task Master Workflow
  • Sinn & Zweck: Orchestriert den gesamten Monatsabschluss.
  • Logik (State Machine): Löst das "Single-Worker-Problem". Der Task startet einen Schritt (z.B. KI-Extraktion), beendet sich sofort und plant eine Wiedervorlage (Retry) in 5 Sekunden. So blockiert er keine Ressourcen, während er auf Ergebnisse wartet.
TASK lexoffice_process_and_book_invoice_task Beleg-Buchung
  • Sinn & Zweck: Verarbeitet eine einzelne PDF-Rechnung (Eingangsbeleg).
  • Ablauf: 1. Upload der Datei via API /files.
    2. Erstellung des Beleg-Datensatzes (Voucher) via /vouchers mit den von der KI extrahierten Daten (Summe, Datum, Belegnummer).
    3. Verknüpfung der Datei mit dem Beleg.
TASK lexoffice_import_csv_task CSV Import Engine
  • Sinn & Zweck: Verarbeitet Massendaten (z.B. Shopware-Exporte) zeilenweise.
  • Logik: Iteriert durch jede CSV-Zeile.
    Prüft via /contacts, ob der Kunde existiert. Falls nein -> POST /contacts (Erstellen).
    Erstellt für jede Zeile einen Buchungsbeleg in Lexoffice.
POST /account/.../get-or-create-contact Kontakt-Management
  • Sinn & Zweck: Stellt sicher, dass Debitoren/Kreditoren immer vorhanden sind.
  • Logik: Sucht erst nach E-Mail/Name. Wenn kein Treffer -> Legt neuen Kontakt an (unterscheidet zwischen Kunde/Lieferant).
GET /account/.../vouchers Beleg-Suche
  • Sinn & Zweck: Findet vorhandene Belege (z.B. zur Duplikatsprüfung).
  • Logik: Filtert nach Typ (Rechnung/Gutschrift), Status (offen/bezahlt) und Datum.
GET /account/.../download Beleg-Download
  • Sinn & Zweck: Lädt das PDF eines Belegs herunter.
  • Logik: Holt erst die Metadaten des Belegs um die fileId zu bekommen, dann Stream-Download der Datei.

3. KI-Engine & Parsing (ai_invoices.py)

Die "Augen" des Systems: Versteht Dokumente wie ein Mensch.

TASK run_ai_invoice_workflow_task Der Sammler
  • Sinn & Zweck: Holt Dokumente aus allen konfigurierten Quellen (IMAP, Drive, etc.).
  • Logik: 1. Ruft E-Mails ab (Filter auf Datum & Keywords).
    2. Führt OCR auf Anhängen aus (Tesseract).
    3. Startet Hybrid-Parsing (siehe unten).
    4. Speichert Ergebnis als standardisiertes PDF.
LOGIC Hybrid-Parsing (Regex + LLM) Daten-Extraktion
  • Sinn & Zweck: Kosteneffiziente und präzise Datenextraktion.
  • Ablauf: 1. Regex: Versucht Muster wie "Rechnungs-Nr.: 123" zu finden (Kostenlos, schnell).
    2. Validierung: Prüft, ob plausible Werte (Summe > 0) gefunden wurden.
    3. KI-Fallback: Wenn Regex scheitert, wird der Text an ein LLM (z.B. Llama 3) gesendet mit dem Prompt "Extrahiere Rechnungsdaten als JSON".
    4. Merge: Kombiniert die besten Werte aus beiden Methoden.

4. Core System (app.py, extensions.py)

FUNC _save_pdf_with_metadata Audit-Trail
  • Sinn & Zweck: Revisionssicherheit.
  • Logik: Schreibt die extrahierten Daten (Absender, Datum, Summen, KI-Modell) sichtbar auf eine "Deckblatt-Seite" oder in den Header des PDFs. So ist immer nachvollziehbar, woher die Daten kommen.
POST /api/jobs/cancel/{id} Not-Aus
  • Sinn & Zweck: Stoppt laufende Prozesse.
  • Logik: Sendet `SIGKILL` an den Celery-Worker-Prozess, der den Job mit der spezifischen ID bearbeitet. Verhindert, dass hängende Jobs das System blockieren.

5. Connectors (imap, google, microsoft)

TASK imap_..._task (Diverse) IMAP Engine
  • Sinn & Zweck: Kommunikation mit Standard-Mailservern.
  • Besonderheit: Nutzt konsequent charset='UTF-8' bei allen Suchbefehlen. Dies verhindert Abstürze bei deutschen Umlauten ("Rückerstattung", "Bestätigung") in E-Mail-Betreffs.
TASK google_analyze_drive_file_task Drive OCR
  • Sinn & Zweck: Verarbeitet Dokumente, die manuell in Google Drive abgelegt wurden.
  • Logik: Lädt Datei in RAM -> Führt OCR aus -> Wendet Hybrid-Parsing an -> Liefert JSON für Lexoffice.