Match-Vorschläge (TransactionMatchProposals)
Zweck
TransactionMatchProposal modelliert den OP-Matching-Workflow: pro Transaktion werden ein oder mehrere Vorschläge erzeugt, die die Transaktion einem Offenen Posten (Debitor / Kreditor) zuordnen — also Forderungen oder Verbindlichkeiten ausgleichen. Jeder Vorschlag hat einen confidence-Score (0–100) und matchReasons mit Detail-Begründungen.
Die Liste ist die globale Verwaltungssicht; das fokussierte Tagesgeschäft läuft im /transaction-cockpit. Hier hingegen können Vorschläge per Bulk freigegeben, ein neuer Matching-Lauf gestartet und Vorschläge endgültig gelöscht werden.
| TransactionMatchProposal | TransactionAllocation | |
|---|---|---|
| Zweck | OP-Matching gegen Debitor/Kreditor | SKR-Kontierung + Booking |
| Ziel | Offener Posten (Forderung/Verbindlichkeit) | Konto, Steuer, Auftrag, Beleg, Auslage |
| Engine | Regel-basiert (Betrag, IBAN, Referenz-Match) | Score-Engine (Expense / KI / Account-Default) |
| Ergebnis bei Approve | OP gilt als ausgeglichen | Allocation gebucht, AccountEntries erzeugt |
matchingStatus der Tx | manually_matched / auto_matched | manually_matched / auto_matched (gleich) |
| API-Stamm | /transaction-match-proposals | /transaction-allocations, /transactions/:id/allocation-proposal |
In der Praxis: Erst Match-Proposals abarbeiten (OP ausgleichen), dann ggf. die Allocation-Engine für die SKR-Buchung anschauen. Beim Cockpit-Workflow „Bestätigen & Buchen" wird die Allocation erzeugt; OP-Matches sind ein paralleler Schritt für Belege, die als Forderung/Verbindlichkeit erfasst wurden.
Voraussetzungen
Berechtigungen (CASL)
| Action | Subject | Wirkung | Keycloak-Rolle |
|---|---|---|---|
view | FE_TransactionMatchProposal, TransactionMatchProposal | Liste/Detail aufrufbar | — |
update | TransactionMatchProposal | Freigeben/Ablehnen, Bulk-Approve | APP_SPEAMCORE_UPDATE_TRANSACTION_MATCH_PROPOSAL |
delete | TransactionMatchProposal | Vorschlag entfernen | APP_SPEAMCORE_DELETE_TRANSACTION_MATCH_PROPOSAL |
do | RunTransactionMatching | Matching-Lauf manuell anstossen | APP_SPEAMCORE_DO_RUN_TRANSACTION_MATCHING |
Schritt-für-Schritt-Anleitung
Matching-Lauf starten
- Match-Vorschläge (
/transaction-match-proposals) öffnen. - Matching ausführen klicken —
POST /api/transaction-match-proposals/run-matching. - Backend-Service vergleicht alle offenen Transaktionen mit offenen Posten und Belegen, scort und schreibt neue Vorschläge in die Tabelle.
- Liste aktualisiert sich automatisch (TanStack-Query-Invalidation).
Einzel-Vorschlag freigeben oder ablehnen
In der Listen-Zeile stehen drei Aktionen zur Verfuegung:
- Freigeben —
POST /api/transaction-match-proposals/:id/approve. Status wirdapproved, Allokation entsteht, Transaktion wirdmanually_matched. - Ablehnen —
POST /api/transaction-match-proposals/:id/reject. Status wirdrejected, kein Effekt auf Transaktion. - Löschen —
DELETE /api/transaction-match-proposals/:id. Vorschlag wird permanent entfernt.
Bulk-Approve
Mehrere Vorschläge markieren → Bulk-Freigeben → POST /api/transaction-match-proposals/bulk-approve mit IDs im Body.
Toolbar (Detail-Seite)
Schlanke Toolbar oben rechts:
| Icon | Aktion (aria-label) | CASL | Wirkung |
|---|---|---|---|
| ← | Zurückgehen | — | Zurück zur Liste. |
| 🏠 | Zur Startseite gehen | — | Springt auf das Dashboard / /. |
| ⏮/◀/▶/⏭ | Pagination | — | Navigation durch die gefilterte Liste — Massen-Bearbeitung ohne Liste-Sprung. |
Globale Floating-Drawer (links)
Wie auf jeder Detail-Seite verfuegbar — siehe Floating-Quickbar:
- KAL. (Mini-Kalender)
- ZEIT (Persoenliche Wochen-Arbeitszeit)
- ARBEIT (Eigene bevorstehende Aufträge)
UI-Elemente
Confidence-Farbcodes
| Confidence | Zeilen-Hintergrund | Bedeutung |
|---|---|---|
| 95 – 100 | gruen | Hohe Wahrscheinlichkeit, oft Auto-Apply |
| 50 – 94 | gelb | Prüfen empfohlen |
| 0 – 49 | rot | Wahrscheinlich Fehl-Match |
Status approved / auto_applied | hellgruen | Bereits zugeordnet |
Status rejected | grau | Verworfen |
Button: „Matching ausführen"
Sichtbar nur bei do:RunTransactionMatching-Berechtigung. Loest synchronen Backend-Lauf aus, der pro offene Transaktion bis zu N Vorschläge erzeugt.
Felder und Eingaben (lesend)
| Feldname | Datentyp | Bedeutung |
|---|---|---|
transactionId | UUID | Verweis auf Transaktion. |
openItemId | UUID (nullable) | Verweis auf Offenen Posten. null bei Cross-Source-Match. |
documentId + documentType | UUID + ENUM (SalesDocument, PurchaseDocument) | Polymorph-Verweis auf Beleg. |
linkedTransactionId | UUID (nullable) | Cross-Source-Verweis (z. B. Bank-Buchung gegen Pleo-Buchung). |
confidence | Integer (0–100) | Score. |
matchReasons | JSON-Array | Liste mit type, score, detail. |
status | ENUM | pending, approved, rejected, auto_applied. |
Wiederverwendbare Konzepte
- Buchhaltungskonten — Querschnitt zu Konto-Modellen.
- Berechtigungen verstehen (CASL)
Verknuepfungen zu anderen Modulen
- Transaktionen — Datenquelle.
- Cockpit — Arbeitsoberflaeche pro Transaktion.
- Offene Posten Kunden / Offene Posten Lieferanten — typischer Match-Partner.
- Verkaufsbelege / Bestellbelege — alternativer Match-Partner.
Häufige Fehler und Lösungen
| Fehler | Lösung |
|---|---|
| Matching-Lauf ohne Wirkung | Keine offenen Transaktionen oder keine offenen Posten. Status der Transaktionen prüfen. |
Vorschlag mit confidence = 0 | Match-Reasons prüfen — meist liegt nur eine schwache Korrelation vor (z. B. nur Betrag). |
| Auto-Apply trotz hoher Confidence nicht erfolgt | Auto-Apply-Schwelle ist konfigurierbar (Default confidence ≥ 95). Bei manuell konfigurierten Schwellen prüfen. |
| Bulk-Approve schlaegt fehl | Eine der Transaktionen ist bereits gematcht — Vorschläge für bereits gematchte Transaktionen werden serverseitig abgelehnt. |
API/Schnittstellen
| Methode | Endpoint | Zweck | CASL |
|---|---|---|---|
GET | /api/transaction-match-proposals | Liste (mit include=transaction,openItem) | view TransactionMatchProposal |
GET | /api/transaction-match-proposals/:id | Detail | view TransactionMatchProposal |
POST | /api/transaction-match-proposals/:id/approve | Freigeben | update TransactionMatchProposal |
POST | /api/transaction-match-proposals/:id/reject | Ablehnen | update TransactionMatchProposal |
POST | /api/transaction-match-proposals/bulk-approve | Bulk-Freigeben | update TransactionMatchProposal |
POST | /api/transaction-match-proposals/run-matching | Matching-Lauf | do RunTransactionMatching |
DELETE | /api/transaction-match-proposals/:id | Löschen | delete TransactionMatchProposal |
Versionshinweise
- 2026-05-16 (Welle 129): Abgrenzung zu TransactionAllocation ergänzt — beide Modelle koexistieren, decken unterschiedliche Aufgaben ab (OP-Matching vs. SKR-Kontierung). Keine inhaltlichen Änderungen am Match-Workflow selbst.
Frühere Versionen
- 2026-04-30: Initiale Veroeffentlichung.