Buchhaltungskonten (TransactionAccount)

Zweck

TransactionAccount repraesentiert ein Buchhaltungskonto im Sinne des Kontenrahmens (z. B. SKR03). Konten sind hierarchisch organisiert (parentTransactionAccountId), koennen mit einer externen Quelle verknuepft sein (isExternal, parentType polymorph zu BankAccount, PayPalAccount o. ae.) und tragen einen Lebenszyklus-Status (active, inactive, pending).

Die FE-Route [/transaction-accounts](/transaction-accounts) (Komponente `TransactionAccountListPage`) existiert für die Verwaltung. Massen-Anlage erfolgt typischerweise über die Ersteinrichtung ([Setup-Wizard Schritt 4](/setup-wizard) — „Standards (DE) laden" importiert ~250 SKR03-Konten). Manuelle Pflege einzelner Konten geschieht direkt in der Routen-Seite.

Modell

Feld	Typ	Bedeutung
id	UUID	Primary Key
displayName	String	Anzeigename („1200 Bank", „4400 Erloese")
currency	String	Default EUR
status	Auswahl	active, inactive, pending
parentTransactionAccountId	UUID	Eltern-Konto für die Hierarchie (self-referential)
parentId + parentType	polymorph	externe Quelle (z. B. BankAccount) — null bei manuellen Konten
isExternal	Boolean	Konto wird automatisch synchronisiert
lastSyncAt	DateTime	Letzter Sync-Zeitpunkt (read-only)
externalId	String	ID des externen Datensatzes

Hierarchie

Konten sind in einem Baum organisiert. Beispiel SKR03:

Aktiva
├── Anlagevermoegen
│   └── 0500 Geschaeftsausstattung
└── Umlaufvermoegen
    ├── 1200 Bank
    └── 1400 Forderungen

GET /api/transaction-accounts ruft im Backend einen Tree-aware Listing-Handler auf (listWithHierarchy), der über Root-Konten paginiert (parentTransactionAccountId IS NULL) und die Children komplett mitlaedt. Bei aktivem Filter oder Suche faellt der Handler auf flache Pagination zurück.

Berechtigungen (CASL)

Action	Subject	Wirkung	Keycloak-Rolle
view	TransactionAccount	Liste/Detail lesen	APP_SPEAMCORE_VIEW_TRANSACTION_ACCOUNT
create/update/delete	TransactionAccount	Konto pflegen	APP_SPEAMCORE_CREATE/UPDATE/DELETE_TRANSACTION_ACCOUNT

In der Praxis bekommen nur Buchhaltungs- und Admin-Rollen update:TransactionAccount. Das Importieren des SKR03-Standards über den Setup-Wizard erzeugt die Konten technisch — Endanwender sehen sie als Auswahl in Konten-Selects (expenseAccountId, revenueAccountId, accountId) auf Belegen und Produkten.

Verknuepfungen

Wo das Subject als FK auftaucht	Bedeutung
Product.accountId / Product.expenseAccountId	Erloes-/Aufwandskonto eines Produkts
SalesDocument.revenueAccountId	Erloeskonto je Beleg
PurchaseDocument.expenseAccountId	Aufwandskonto je Beleg
Branch.primaryTransactionAccountId / Branch.secondaryTransactionAccountId	Niederlassungs-Bankkonten
BankAccount ↔ TransactionAccount	externe Quelle (Sync)

API/Schnittstellen

Methode	Endpoint	Zweck	CASL
GET	/api/transaction-accounts	Liste mit Tree-Pagination (listWithHierarchy)	view TransactionAccount
GET	/api/transaction-accounts/:id	Detail	view TransactionAccount
POST	/api/transaction-accounts	Manuell anlegen	create TransactionAccount
PATCH	/api/transaction-accounts/:id	Ändern	update TransactionAccount
DELETE	/api/transaction-accounts/:id	Soft-Delete	delete TransactionAccount

Drift-Risiken

1. Keine FE-Seite — Endanwender koennen Konten nur indirekt sehen. Wer einen falsch importierten Kontenrahmen korrigieren will, muss API oder DB nutzen.
2. Zirkulaere Referenzen in parentTransactionAccountId werden nicht geprüft.
3. isExternal und parentType muessen konsistent gesetzt sein — wenn isExternal = true und parentId null, gibt es keine Sync-Quelle.

Stand der Doku (nach Welle 17): Eine eigene FE-Seite /transaction-accounts ist live mit Tree-Aware-Pagination — der Punkt aus dem TODO ist erledigt. Verwaltung erfolgt nicht mehr ausschliesslich über den Setup-Wizard.

Verknuepfungen

• Setup-Wizard Schritt 4 — Massenimport SKR03.
• Bankkonten und Zuweisungen — externe Quelle.
• Polymorpher Parent-Pattern — TransactionAccount.parentType.

Versionshinweise

• 2026-04-29: Initiale Veroeffentlichung.