KI-Allocation-Proposal-Engine
Die Allocation-Engine ist die Buchhaltungs-KI von SpeamCore: Sie nimmt eine Bank- oder Pleo-Transaktion und schlägt vor, auf welches SKR-Konto, mit welchem Steuersatz, gegen welchen Beleg oder Auftrag sie gebucht werden soll. Diese Seite erklärt, wie der Vorschlag entsteht, wann er autonom durchläuft und wo der Mensch zustimmt.
Drei Signale, ein Score
Pro Transaktion liefert der Service transactionAllocationProposal.service.ts einen AllocationProposal. Der Vorschlag fasst drei unabhängige Signale zu einem Score zwischen 0 und 100 zusammen:
| Signal | Punkte | Wer liefert? | Was wird übernommen? |
|---|---|---|---|
| Expense-Match | 0 / 60 / 95 | Deterministischer Matcher gegen Expense (recurring / contract / credit) | defaultAccountId, taxRateId, suggestedExpense |
| AI-Confidence | 0 – 30 | Anthropic-Klassifizierung in TransactionAiAssessment | suggestedAccountId, suggestedTaxRateId, suggestedWorkorderId, classificationReasoning |
| Account-Default | 0 / 10 | transactionAccountFrom.defaultOffsetAccountId | Fallback-Konto (z. B. „Pleo Geldtransit contra → 1361") |
Score = clamp(Expense + AI + Account-Default, 0, 100).
Signal 1 — Expense-Match (deterministisch)
Die zuverlässigste Quelle: Matchen direkt gegen die Expense-Tabelle (wiederkehrende Auslagen, Verträge, Pleo-Card-Käufe).
- Hard Match (95 Punkte): Name-Token-Overlap plus Betrag ±2 %, im 14-Tage-Fenster um die Transaktion. Trifft zu, wenn z. B. „Vodafone Festnetz" als Auslage mit dem Lastschrift-Beleg übereinstimmt.
- Soft Match (60 Punkte): Nur Betrag (±5 %). Nutzt der Pleo-Pfad — Karte rechnet ohne Empfänger-Namen ab, Match läuft über die Auslage selbst.
- Kein Match (0 Punkte): Kein passender Expense im Zeitfenster.
Der Hard Match ist die einzige Bedingung für Auto-Apply (siehe unten). Soft Matches gehen ins Cockpit.
Signal 2 — AI-Confidence
Die KI (Anthropic Claude) klassifiziert jede Transaktion gegen den SKR03-Kontenrahmen, schaut sich Beleg-OCR und historische Buchungen an. Ergebnis im TransactionAiAssessment:
classificationConfidence(0 – 100) — wie sicher ist die KI?classificationReasoning— Text-Begründung in der Cockpit-SichtsuggestedAccountId/suggestedTaxRateId/suggestedWorkorderId/suggestedExpenseId
Die Confidence fließt mit Faktor 0,3 in den Score — eine 100%-sichere KI bringt maximal 30 Punkte. Damit bleibt die KI niemals allein für Auto-Apply qualifiziert — sie muss immer mit Expense-Match oder manueller Bestätigung kombiniert werden.
Die KI füllt Lücken, nicht Überschriften: Hat der Expense-Match schon ein Konto vorgeschlagen, ergänzt die KI nur fehlende Felder (z. B. Workorder-Zuordnung).
Signal 3 — Account-Default
Pro Buchhaltungskonto (Pleo-Karte, Bank, …) kann ein defaultOffsetAccountId gepflegt werden — z. B. „Pleo Geldtransit contra → 1361". Wenn weder Expense noch KI greifen, schlägt der Service dieses Konto als saubere Bank-Gegenbuchung vor (10 Punkte).
So bleiben technische Bank-Bewegungen (Karten-Aufladung, Inter-Konto-Transfer) auto-klassifizierbar, ohne dass die KI involviert sein muss.
Auto-Apply — die strenge Schwelle
autoApplyEligible = score ≥ 95 AND suggestedAccountId !== null
Konkret: Nur ein Expense-Hard-Match löst das autonome Buchen aus. Alle anderen Fälle (Soft Match, reine KI, Account-Default-only) landen als Vorschlag im Cockpit und warten auf manuelle Bestätigung.
Begründung: Auto-Apply schreibt eine AccountEntry-Buchung. Reverse ist möglich, aber teuer (Storno-Buchung). Lieber drei zusätzliche Klicks im Cockpit als ein Buchhaltungs-Cleanup nach Falsch-Buchung.
Drei Apply-Pfade
Der Service applyAutoProposal() unterscheidet drei Pfade — je nachdem, wer ihn ruft:
| Pfad | Ruft | Bedingung | Action | resultierender matchingStatus |
|---|---|---|---|---|
| Auto-Apply | Sync-Pipeline (Pleo, finAPI) | autoApplyEligible = true | Allocation anlegen + buchen + Tx-Update | auto_matched |
| Cockpit-Bestätigung | User klickt „Bestätigen & Buchen" | forceBookAndMatch = true | bestehende Proposal-Allocation übernehmen + buchen | manually_matched |
| Proposal Only | Sync-Pipeline | Score 1 – 94 | Allocation anlegen, nicht buchen | proposal_created |
Der dritte Pfad ist der Trick, der den Cockpit-Workflow trägt: Die KI legt schon beim Sync eine Vorschlags-Allocation an. Im Cockpit muss der User nur noch bestätigen — der Service holt sich die bestehende Allocation, ergänzt die AccountEntries und setzt den matchingStatus.
Idempotent: Findet applyAutoProposal() eine bestehende Allocation, wird sie wiederverwendet. Keine Duplikate.
Batch-Run nach Sync
Nach einem erfolgreichen Sync läuft runAutoApplyBatch():
- sucht alle
business_expense-Transaktionen der letzten 30 Tage (limit 50) - versucht für jede
applyAutoProposal()mitautoApplyEligible - zählt:
{ applied, proposed, scanned }— Telemetrie zum Sync-Job
Die Schwelle „letzte 30 Tage" verhindert, dass alte Transaktionen rückwirkend gebucht werden, wenn jemand einen Expense lange nach Zahlung anlegt.
Reasoning — was sieht der User?
Das AiClassificationCard im Cockpit zeigt zwei Reasonings übereinander:
- Score-Engine-Reasoning (auto-generiert): „Expense-Match: ‚Vodafone Festnetz · 49,90 €' → +95 · KI-Vorschlag (Conf 88) → +26 · Account-Default → +10 = 100 (clamp)"
- KI-Reasoning (Anthropic): Warum wurde dieses SKR-Konto fachlich gewählt? „Klassische Telekom-Aufwendung, Konto 4920 (Telefon/Internet) gemäß SKR03; voller Vorsteuerabzug (19 %)."
Damit ist immer sichtbar, wer was vorgeschlagen hat — die deterministische Regel oder die KI. Manuelle Bestätigung wird so zur informierten Entscheidung, nicht zur Black-Box-Genehmigung.
Was die Engine NICHT tut
- Kein OP-Matching: Forderungen und Verbindlichkeiten werden über TransactionMatchProposal abgeglichen — ein paralleler, deterministischer Workflow.
- Kein Auto-Reverse: Falsch-Buchungen werden manuell über
POST /api/transaction-allocations/:id/reversezurückgenommen. - Keine Konto-Anlage: Fehlt ein SKR-Konto, schlägt die Engine kein Konto vor (Score-Beitrag = 0). Der User muss erst über /accounts ein Konto pflegen.
- Keine Buchung ohne Allocation: Jede
AccountEntryhat eine Quelle. Direkt-Buchungen ohne Allocation laufen über das Account-Modul, nicht über diese Engine.
Konfiguration
| Wo | Was | Wirkung |
|---|---|---|
| TransactionAccount | defaultOffsetAccountId setzen | Account-Default-Signal aktivieren (+10 Punkte) |
| Expense (recurring / contract / credit) | Pflege der defaultAccountId und taxRateId | Expense-Match-Signal nutzt diese Werte |
| Mandanten-Setting | KI-Provider (Anthropic-Modell-Version) | Steuert classificationConfidence-Qualität |
| Account | SKR-Kontenrahmen + Display-Namen | KI nutzt die Anzeigenamen für ihre Reasoning-Texte |
Verknüpfungen zu anderen Modulen
- Transaktions-Zuordnungen — Allocation-Modell, API-Endpoints, Status-Lebenszyklus
- Transaktions-Cockpit — Arbeitsoberfläche, in der die Engine sichtbar wird
- Transaktionen — Datenbasis,
matchingStatusundTransactionAiAssessment - Konten-Buchungen — was die Engine am Ende erzeugt
- Buchhaltungskonten — SKR03-Kontenrahmen-Konzept
- Match-Vorschläge — OP-Matching-Pendant
- Auslagen — Quelle für das Expense-Match-Signal
Versionshinweise
- 2026-05-16 (Welle 129): Initiale Veröffentlichung. Quelle: BE-Service
transactionAllocationProposal.service.ts(546 Zeilen), BE-Servicebooking.service.ts, FE-KomponentenAiClassificationCard,TransactionAllocationSummary. Score-Engine, drei Signale, Auto-Apply-Schwelle und drei Apply-Pfade dokumentiert.