Transaktions-Kategorien

Zweck

Kategorien (Category) sind ein hierarchisches Klassifizierungs-System mit Multi-Scope — eine Kategorie kann gleichzeitig für Transaktionen, Dokumente, Mails und Zeiterfassung genutzt werden. Die Master-Liste wird von FinAPI gepflegt (Sync-Aktion); benutzerdefinierte Kategorien lassen sich darunter ergaenzen.

Voraussetzungen

- Berechtigung `create:Category`. - Für FinAPI-Sync: aktive FinAPI-Anbindung.

Berechtigungen (CASL)

Action	Subject	Keycloak-Rolle
view	FE_Category, Category	—
create/update/delete	Category	APP_SPEAMCORE_CREATE/UPDATE/DELETE_CATEGORY
view	Transaction (Sub-Liste pro Kategorie)	APP_SPEAMCORE_VIEW_TRANSACTION (SUB-LISTE PRO KATEGORIE)`

Schritt-für-Schritt-Anleitung

Kategorie anlegen

1. Transaktions-Kategorien (/transaction-categories) → + Neu.
2. Name vergeben.
3. Optional: parentCategoryId setzen — ergibt Hierarchie (sichtbar als Einrueckung in der Liste).
4. Scopes wählen — pro Kategorie kann ein oder mehrere Bereiche aktiv sein:
   • isTransaction — Buchhaltungsbewegungen.
   • isDocument — Dokumenten-Klassifizierung.
   • isMail — Mail-Tagging.
   • isTimeTracking — Zeiterfassungs-Klassifizierung.
5. Status auf active.

FinAPI-Sync ausloesen

POST /api/categories/sync triggert einen Massensync von der FinAPI — neue Kategorien werden mit pending-Status angelegt; bestehende werden aktualisiert.

Beim Sync werden `finapiCategoryId` und `isCustom` auf den FinAPI-Stand gesetzt. Diese Felder sind im FE **disabled** und nur durch den Sync veraenderbar.

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

Button: „Sync (FinAPI)"

Listenseite. Ruft POST /api/categories/sync auf. Toast bei Erfolg/Fehler.

Filter: Pending-only

Listenseite. Toggelt showPendingOnly-State; zeigt nur Kategorien mit status = pending.

Felder und Eingaben

Feldname	Pflicht	Datentyp	Wirkung beim Ausfuellen	Voraussetzung
name	ja	String	Anzeige in der Hierarchie und in Auswahllisten.	—
parentCategoryId	nein	UUID (Self-Ref)	Bestimmt die Position in der Hierarchie.	Keine Zyklen — Kategorie darf nicht (direkt oder indirekt) ihr eigener Parent sein.
color	nein	Hex-Farbe	UI-Anzeige in Listen und Tags.	—
sortOrder	nein	Integer	Reihenfolge in der Hierarchie-Anzeige.	—
status	nein	active/pending/inactive	pending ist der Default für neu angelegte Categories vor FinAPI-Sync.	—
isTransaction	nein	Boolean (Switch)	Bei true: in Transaktions-Auswahl sichtbar.	—
isDocument	nein	Boolean (Switch)	Bei true: in Dokumenten-Auswahl sichtbar.	—
isMail	nein	Boolean (Switch)	Bei true: in Mail-Auswahl sichtbar.	—
isTimeTracking	nein	Boolean (Switch)	Bei true: in Zeiterfassungs-Auswahl sichtbar.	—
finapiCategoryId	—	Integer (read-only)	Quell-ID aus FinAPI. Wird vom Sync gesetzt.	—
isCustom	—	Boolean (read-only)	true = Mandanten-eigene Kategorie.	—
isSensitive	nein	Boolean (Switch)	Markiert Kategorien als sensibel — beeinflusst Berichts-Sichtbarkeit (Datenschutz).	—

Wiederverwendbare Konzepte

• Buchhaltungskonten
• Berechtigungen verstehen (CASL)

Verknuepfungen zu anderen Modulen

• Transaktionen (/transactions) — Transaction.transactionCategoryId.
• Dokumenten-Center (/document-center) — Dokumente koennen kategorisiert werden.
• Mailbox — Mails koennen kategorisiert werden.
• Zeiterfassung (/employee-time-trackings) — Zeit-Einträge koennen kategorisiert werden.

Häufige Fehler und Lösungen

Fehler	Lösung
Kategorie nicht in Auswahl sichtbar	Passender Scope-Switch (isTransaction etc.) ist false.
pending-Kategorien stapeln sich	FinAPI-Sync ausstehend — manuell ausloesen.
FinAPI-Felder lassen sich nicht ändern	Per Design read-only — Änderungen passieren nur im Sync.
Kategorie-Auswahl leer	Keine active-Kategorie mit dem passenden Scope vorhanden.

API/Schnittstellen

Methode	Endpoint	Zweck	CASL
GET	/api/categories	Liste	view Category
GET	/api/categories/:id	Detail	view Category
POST	/api/categories	Anlegen	create Category
PATCH	/api/categories/:id	Ändern	update Category
DELETE	/api/categories/:id	Soft-Delete	delete Category
POST	/api/categories/sync	FinAPI-Sync	update Category

Versionshinweise

• 2026-04-29: Initiale Veroeffentlichung mit FE-Tiefen-Standard.