Transaktionen

Zweck

Transaktionen (Transaction) sind die Konto-Bewegungen, die aus externen Quellen importiert werden — typischerweise über finAPI (Banking) oder PayPal-Integration. Pro Transaktion sehen Sie Datum, Wertdatum, Betrag, Waehrung, Quelle/Ziel-Konto, Status und ein Matching-Status, der die Verknuepfung mit OP-Listen widerspiegelt.

Voraussetzungen

- Mindestens ein verbundenes Bankkonto oder PayPal-Konto (siehe Setup-Wizard Schritt 6). - Berechtigung `view:Transaction`.

Berechtigungen (CASL)

Action	Subject	Wirkung	Keycloak-Rolle
view	FE_Transaction, Transaction	Liste/Details	—
update	Transaction	Status, Kategorie, Notiz ändern	APP_SPEAMCORE_UPDATE_TRANSACTION
delete	Transaction	Soft-Delete	APP_SPEAMCORE_DELETE_TRANSACTION
view	TransactionAllocation	Tab Allokationen	APP_SPEAMCORE_VIEW_TRANSACTION_ALLOCATION

Schritt-für-Schritt-Anleitung

Transaktionen einsehen

1. Transaktionen (/transactions) — Liste mit Status-Filter (booked Default, pending, reversed).
2. Klick auf Zeile → Detail-Seite mit zwei Tabs: General Data und Allocations.
3. Im General-Data-Tab koennen Sie Status und Kategorie ändern. Datum, Betrag, Reference und Note sind read-only — sie kommen aus der externen Quelle.

Transaktion einer OP zuweisen

Tab Allocations (/transactions/:id/allocations) — zeigt alle bestehenden TransactionAllocation-Einträge. Neue Allokationen werden über das OP-Listen-Modal erstellt (siehe Forderungen / Verbindlichkeiten).

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

Filter: Status

Listenseite. booked (Default), pending, reversed.

Auswahl: Transaction Account From/To

Zwei Read-only Anzeigen mit Direkt-Link zur jeweiligen /transaction-accounts/:id-Detailseite.

Felder und Eingaben

Feldname	Pflicht	Datentyp	Wirkung beim Ausfuellen	Voraussetzung
amount	—	Decimal/Currency (read-only)	Wert der Transaktion. Wird vom externen Provider gesetzt.	—
currency	—	String (read-only)	Waehrung der Transaktion.	—
transactionDate	—	Datum (read-only)	Buchungsdatum.	—
valueDate	—	Datum (read-only)	Wertdatum.	—
reference	—	TEXT (read-only)	Verwendungszweck/Reference vom Sender.	—
note	nein	TEXT	Interne Notiz. Wird nicht im Banking-System gespiegelt.	—
transactionCategoryId	nein	UUID (Select)	Kategorie zur Klassifizierung. Beeinflusst Reports und automatisches Matching.	view:TransactionCategory.
status	nein	pending/booked/reversed	Buchungsstatus. reversed zeigt eine Storno-Bewegung an.	—
transactionAccountFromId / transactionAccountToId	—	UUID (read-only Link)	Quell- und Ziel-Buchhaltungskonto.	view:TransactionAccount.
matchingStatus	—	Enum (read-only)	unmatched, auto_matched, proposal_created, manually_matched, skipped. Steuert Anzeige im Cockpit und triggert die Allocation-Proposal-Engine. Schreibrechte über update:Transaction (Skip-Aktion).	—
hasReceipt	—	Boolean (virtuell, read-only)	true, wenn ein verknüpftes Document als Beleg hängt. Wird vom BE per batched afterFind-Hook berechnet und für das Beleg-Icon im Cockpit verwendet.	—
feeTransactionId	—	UUID (Self-Ref)	Verknuepft eine zugehörige Gebuehren-Transaktion.	—
reversalTransactionId	—	UUID (Self-Ref)	Verknuepft die Storno-Transaktion (bei status = reversed).	—

Verknüpftes TransactionAiAssessment

Pro Transaktion legt die KI-Klassifizierung optional ein TransactionAiAssessment an. Relevante Felder für die Allocation-Engine:

• classificationReasoning — Text-Begründung der KI: warum dieses SKR-Konto? Wird im Cockpit im rechten Panel und in der Allocation-Summary angezeigt.
• classificationConfidence — KI-Confidence in % (0 – 100). Fließt mit Faktor × 0,3 in den Score-Engine-Wert ein.
• suggestedAccountId, suggestedTaxRateId, suggestedWorkorderId, suggestedExpenseId — Vorschläge der KI.

Manuell neu anstoßen über POST /api/transactions/:id/ai-classify (nur Klassifikation) oder — seit Juni 2026 — über den konsolidierten Pass POST /api/transactions/:id/ai-analyze, der Bewertung und Klassifikation in einem Request erledigt (CASL do:AiSuggestion). Letzteren nutzt das Transaktions-Cockpit.

Workflows und Zustaende

Wiederverwendbare Konzepte

• Buchhaltungskonten
• Berechtigungen verstehen (CASL)

Verknuepfungen zu anderen Modulen

• Buchhaltungskonten (TransactionAccount) — Quell-/Ziel-Konto.
• Transaktions-Cockpit — Arbeitsoberfläche für Zuordnung und Buchung.
• Transaktions-Zuordnungen — Allocation pro Tx + Score-Engine + Buchung.
• KI-Allocation-Engine — Score-Logik und Auto-Apply-Regeln.
• Konten-Buchungen — werden vom Booking-Service erzeugt, wenn eine Allocation gebucht wird.
• Match-Vorschläge — paralleler Workflow gegen offene Posten.
• Forderungen / Verbindlichkeiten (/customer-open-items, /supplier-open-items) — OP-Matching-Ziel.
• Setup-Wizard Schritt 6 — Banking-Verbindung anlegen.

KI-Analyse im Chat (seit Juni 2026)

Der KI-Chat kann Transaktionen jetzt serverseitig auswerten — über spezialisierte Werkzeuge (MCP-Tools), die auf einer Aggregations-Schicht (transactionAnalytics.service) arbeiten, statt rohe Datensätze in den Chat zu laden:

Werkzeug	Was es liefert
Transaktionen suchen	gefilterte Suche (Betrag, Zeitraum, Gegenpartei, Zweck).
Zusammenfassen	Summen/Salden über einen Zeitraum.
Aufschlüsseln	Gruppierung (z. B. nach Konto, Monat, Gegenpartei).
Wiederkehrende erkennen	regelmäßige Zahlungen (Daueraufträge, Abos).
Anomalien finden	auffällige Ausreißer.
Zahlungskonten auflisten	verfügbare Bank-/Pleo-Konten.

So bleiben auch große Transaktionsmengen auswertbar — die Tool-Ergebnisse sind serverseitig begrenzt (Kappung sehr großer Ausgaben), damit der Chat performant bleibt.

Verknüpfung mit Geschäftsobjekten (TransactionEntityLink)

Eine Transaktion kann mit beliebigen Geschäftsobjekten verknüpft werden, um Kontext festzuhalten („diese Bankzahlung gehört zu dieser Rechnung und diesem Projekt und diesem Auftrag"). Das geschieht über das polymorphe n:m-Modell TransactionEntityLink — eine reine Referenz ohne Buchungseffekt.

Feld	Datentyp	Bedeutung
transactionId	UUID	FK → Transaktion
linkedEntityType	String	Art des Objekts — z. B. PurchaseDocument, SalesDocument, Project, Workorder, Customer, Supplier, Employee, Vehicle, Expense, PayrollRun, HealthInsuranceFund
linkedEntityId	UUID	ID des verknüpften Objekts
source	Enum (manual, ai, booking, Default manual)	Herkunft der Verknüpfung

Pro Kombination (transactionId, linkedEntityType, linkedEntityId) gibt es genau eine Verknüpfung (idempotent). Wird ein Beleg über das Cockpit gebucht, legt der Allocation-Controller automatisch eine Verknüpfung mit source = booking an, sodass gebuchte Belege im Cockpit verlinkt sind.

Im Transaktions-Cockpit:

• Das Verknüpfungs-Panel zeigt bestehende Links als klickbare Chips (LinkedEntityChip) mit „Verwalten"-Button.
• Das Link-Modal fügt neue Verknüpfungen hinzu (Auswahl über die jeweiligen Objekt-Suchen) oder löscht sie.
• Der Cockpit-Filter „verknüpft" zeigt nur Transaktionen mit mindestens einer Verknüpfung (gespeist aus GET /transaction-entity-links/linked-transaction-ids).

Zugriff läuft über das Transaction-Subject (lesen view, ändern update) — kein eigenes CASL-Subject.

Generisches EntityLink-System (seit Cockpit 2.0)

Mit dem rechnungsfluss-v2-Umbau (Juni 2026) gibt es zusätzlich ein generisches EntityLink-Modell, das Verknüpfungen zwischen beliebigen zwei Geschäftsobjekten abbildet (nicht nur ab einer Transaktion). Es ergänzt TransactionEntityLink und wird u. a. im Belegfreigabe-Cockpit und für Referenz-Vorschläge im Transaktions-Cockpit genutzt.

Feld	Bedeutung
sourceType / sourceId	erstes Objekt (Typ + ID)
targetType / targetId	zweites Objekt (Typ + ID) — bidirektional
linkType	Art der Verknüpfung (Default reference; z. B. commission, order, settlement, source)
source	Herkunft (manual, ai, import, booking, send)
amount / metadata	optionaler Betrag bzw. Freiform-Zusatzdaten

Endpoints: GET/POST /api/entity-links, GET /api/entity-links/bulk, GET/DELETE /api/entity-links/:id. Eindeutig je (sourceType, sourceId, targetType, targetId, linkType).

API/Schnittstellen

Methode	Endpoint	Zweck	CASL
GET	/api/transactions	Liste	view Transaction
GET	/api/transactions/:id	Detail (inkl. hasReceipt, matchingStatus, aiAssessment)	view Transaction
PATCH	/api/transactions/:id	Status / Kategorie / Notiz / matchingStatus ändern	update Transaction
DELETE	/api/transactions/:id	Soft-Delete	delete Transaction
GET	/api/transactions/:id/allocation-proposal	Score-Engine-Vorschlag (siehe TransactionAllocation)	view TransactionAiAssessment
POST	/api/transactions/:id/allocation-proposal/apply	„Bestätigen & Buchen" — legt Allocation an und bucht	create TransactionAllocation, update Transaction
POST	/api/transactions/:id/ai-classify	KI-Klassifizierung neu anstoßen	do AiSuggestion
POST	/api/transactions/:id/ai-analyze	Konsolidierter KI-Pass (Bewerten + Klassifikation) — vom Cockpit genutzt	do AiSuggestion
GET	/api/transactions/:id/links	Verknüpfungen einer Transaktion lesen	view Transaction
POST	/api/transactions/:id/links	Verknüpfung hinzufügen (idempotent)	update Transaction
DELETE	/api/transactions/:id/links/:linkId	Verknüpfung löschen	update Transaction
GET	/api/transaction-entity-links/linked-transaction-ids	IDs aller verknüpften Transaktionen (Cockpit-Filter „verknüpft")	view Transaction

Versionshinweise

• 2026-04-29: Initiale Veröffentlichung mit FE-Tiefen-Standard.
• 2026-05-16 (Welle 129): Virtuelles hasReceipt-Feld (Beleg-Icon-Spalte im Cockpit), TransactionAiAssessment mit classificationReasoning + classificationConfidence durchgereicht in der Allocation-Engine, neue Endpoints /:id/allocation-proposal, /:id/allocation-proposal/apply, /:id/ai-classify dokumentiert. Detailbeschreibung der Score-Engine: KI-Allocation-Engine.
• 2026-06-09: Abschnitt „KI-Analyse im Chat" ergänzt — sechs neue MCP-Werkzeuge (Suchen/Zusammenfassen/Aufschlüsseln/Wiederkehrende/Anomalien/Konten) auf Basis von transactionAnalytics.service, mit serverseitiger Ergebnis-Begrenzung. Verifiziert an src/mcp/tools/*transaction*.
• 2026-06-11: Abschnitt „Verknüpfung mit Geschäftsobjekten (TransactionEntityLink)" ergänzt — polymorphe n:m-Verknüpfung (Beleg/Projekt/Auftrag/…), Cockpit-Filter „verknüpft", neue /links-Endpoints. Verifiziert an transactionEntityLink.model.ts, transaction.router.ts (Master e01f8bdc).
• 2026-06-12: Generisches EntityLink-System (bidirektional, beliebige Objekt-Paare, linkType) ergänzt — koexistiert mit TransactionEntityLink, genutzt in Cockpit 2.0 + Belegfreigabe. Verifiziert an entityLink.model.ts, entityLink.router.ts (Master 69bd4617).