Kategorien (Categories)

Zweck

Category ist eine polymorphe Klassifizierung quer durch SpeamCore. Eine Kategorie kann für eine oder mehrere Domaenen aktiviert werden:

• isTransaction = true — auswählbar in Transaktionen.
• isDocument = true — auswählbar im Document-Center und an Beleg-Anhängen.
• isMail = true — auswählbar in Mail.
• isTimeTracking = true — auswählbar in Zeiterfassungen.

Kategorien sind hierarchisch (parentCategoryId) und haben einen Status — active, inactive oder pending (AI hat die Kategorie vorgeschlagen, Anwender muss sie freigeben). Für Bank-Transaktionen gibt es zusaetzlich einen finAPI-Sync (finapiCategoryId, isCustom).

Kategorien sind **nicht** identisch mit den [Transaktions-Kategorien](/transaction-categories), die für das Sub-Routing `transactionCategory.transactions` an Transaktionen genutzt werden. `Category` ist die uebergreifende Kategorie-Klasse (polymorph), `TransactionCategory` ist eine eigene, transaktionsspezifische Kategorisierung.

Voraussetzungen

- Berechtigung `view:Category` und `create:Category`. - Für finAPI-Sync: konfigurierter finAPI-Provider und Berechtigung `create:Category` (Sync legt Kategorien an). - Für Sub-Listen pro Domaene: jeweils `view`-Berechtigung der referenzierten Entitaet.

Berechtigungen (CASL)

Action	Subject	Wirkung	Keycloak-Rolle
view	FE_Category, Category	Liste/Detail aufrufbar	—
create/update/delete	Category	Pflegen	APP_SPEAMCORE_CREATE/UPDATE/DELETE_CATEGORY
view	Transaction/Document/Mail/EmployeeTimeTracking	Sub-Listen pro Domaene	APP_SPEAMCORE_VIEW_TRANSACTION/DOCUMENT/MAIL/EMPLOYEE_TIME_TRACKING

Schritt-für-Schritt-Anleitung

Eigene Kategorie anlegen

1. Kategorien (/categories) → + Neu — leerer Eintrag wird angelegt, Detail-Seite öffnet sich.
2. name pflegen.
3. Optional parentCategoryId setzen, um die Kategorie als Unter-Kategorie eines Eltern-Eintrags einzuordnen.
4. Scopes aktivieren (isTransaction, isDocument, isMail, isTimeTracking) — bestimmen, in welchen Modulen die Kategorie auswählbar ist.
5. color setzen (Hex oder Chakra-Token).
6. sortOrder zur Steuerung der Reihenfolge in Dropdowns.
7. Status auf active lassen, damit die Kategorie aktiv genutzt werden kann.

finAPI-Kategorien synchronisieren

1. Liste öffnen → Button Sync ausführen klicken — POST /api/categories/sync.
2. Backend importiert finAPI-Standard-Kategorien als Category-Einträge mit isTransaction = true, isCustom = false, finapiCategoryId gesetzt.
3. Diese Kategorien sind read-only für wesentliche Felder (isCustom = true bei selbst angelegten).

Pending-Kategorien freigeben

AI-generierte Kategorien (z. B. aus Mail-Klassifizierung) erscheinen mit Status pending. Filter „Nur Pending" in der Liste. Kategorie prüfen, Status auf active setzen — damit erscheint sie in Auswahllisten.

Sub-Liste pro Domaene

Detail-Seite einer Kategorie hat Tabs:

• Transaktionen (/categories/:id/transactions) — alle Transaktionen mit dieser Kategorie.
• Dokumente (/categories/:id/documents).
• Mails (/categories/:id/mails).
• Zeiterfassungen (/categories/:id/time-trackings).

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)

Felder und Eingaben

Feldname	Pflicht	Datentyp	Wirkung beim Ausfuellen	Voraussetzung
name	ja	String (255)	Anzeigename in Selectors und Reports.	—
parentCategoryId	nein	UUID	Eltern-Kategorie für Hierarchie.	view:Category.
color	nein	String (50)	Hex- oder Chakra-Color-Token. Wird in Liste und Selectors als Indikator angezeigt.	—
icon	nein	String (100)	Icon-Identifier (typischerweise react-icons).	—
sortOrder	nein	Integer	Reihenfolge in Dropdowns und Listen.	—
status	ja	ENUM (active, inactive, pending)	Steuert Sichtbarkeit. pending markiert AI-Vorschläge zur Freigabe.	—
isTransaction	nein	Boolean (Switch)	Aktiviert die Kategorie für Transaktionen.	—
isDocument	nein	Boolean (Switch)	Aktiviert für Dokumente.	—
isMail	nein	Boolean (Switch)	Aktiviert für Mail.	—
isTimeTracking	nein	Boolean (Switch)	Aktiviert für Zeiterfassungen.	—
finapiCategoryId	nein (read-only)	Integer	finAPI-System-ID. Wird vom Sync-Job gesetzt.	—
isCustom	nein (read-only)	Boolean	true: vom Anwender angelegt. false: aus finAPI-Sync.	—
isSensitive	nein	Boolean (Switch)	Markiert sensitive Inhalte (z. B. Gehaltsbuchungen). Beeinflusst Anzeige in nicht-priviligierten Sichten.	—

Wiederverwendbare Konzepte

• Polymorpher Parent-Pattern — Domaenen-Querschnitt.
• Berechtigungen verstehen (CASL)

Verknuepfungen zu anderen Modulen

• Transaktionen — Transaction.categoryId. Sub-Liste am Kategorie-Detail.
• Document-Center — Document-Anhänge mit Kategorie. Sub-Liste verfuegbar.
• Mail — Kategorisierung pro Mail-Eintrag. Sub-Liste verfuegbar.
• Zeiterfassungen — Kategorie pro Zeit-Eintrag. Sub-Liste verfuegbar.
• Cockpit und Match-Vorschlaege — Kategorien helfen beim Auto-Matching.

Häufige Fehler und Lösungen

Fehler	Lösung
Kategorie taucht nicht im Selector auf	status != active oder Scope-Switch (z. B. isTransaction) ist false.
finAPI-Sync legt Doppelten an	Sync ist idempotent über finapiCategoryId — bei Doppelten manuell prüfen, ob isCustom = true (eigene) gegen false (finAPI) verschoben werden soll.
Pending-Kategorien stapeln sich	AI-Klassifizierung erzeugt diese — entweder regelmaessig durchsehen und freigeben, oder die Funktion deaktivieren.
Hierarchie nicht sichtbar	parentCategoryId korrekt gesetzt? Liste hat Hierarchie-Anzeige; in Selectors wird sie nicht zwingend dargestellt.

API/Schnittstellen

Methode	Endpoint	Zweck	CASL
GET	/api/categories	Liste (mit include=parentCategory)	view Category
POST	/api/categories	Anlegen	create Category
GET	/api/categories/:id	Detail	view Category
PATCH	/api/categories/:id	Ändern	update Category
DELETE	/api/categories/:id	Soft-Delete	delete Category
POST	/api/categories/sync	finAPI-Standard-Kategorien synchronisieren	create Category
GET	/api/transactions?filter[categoryId]	Sub-Liste Transaktionen	view Transaction
GET	/api/documents?filter[categoryId]	Sub-Liste Dokumente	view Document
GET	/api/mails?filter[categoryId]	Sub-Liste Mails	view Mail
GET	/api/employee-time-trackings?filter[categoryId]	Sub-Liste Zeit	view EmployeeTimeTracking

Versionshinweise

• 2026-04-30: Initiale Veroeffentlichung.