Mitarbeiter

Zweck

Der Mitarbeiterstamm haelt alle Beschaeftigten — interne Mitarbeiter, externe Dienstleister und API-Konten. Pro Mitarbeiter werden Verträge, Arbeitszeitmodelle, Rollen, Fahrzeuge, Schulungen, Mailbox und Compliance-Prüfungen gefuehrt. Mitarbeiter sind über keycloakUserId an SpeamID gekoppelt.

Voraussetzungen

- Berechtigung `create:Employee`. - Für Self-Service-Endpoints (`/employees/me`) reicht eine eigene Mitarbeiter-Verknuepfung. - Für Keycloak-Orphan-Verwaltung: `do:ManageKeycloakOrphan`.

Berechtigungen (CASL)

Frontend-Page-Guard:

Action	Subject	Keycloak-Rolle
view	FE_Employee	—
view	Employee	APP_SPEAMCORE_VIEW_EMPLOYEE

Tab-Subjects:

Tab	Subject
Rollen	Assignment:view
Fahrzeuge	Vehicle:view
Verträge	EmployeeContract:view
Schulungen	CourseEnrollment:view
Dokumente	Document:view
Dashboard	Dashboard:view
Zeiterfassung	EmployeeTimeTracking:view
Mail-Konten	MailAccount:view
Compliance-Checks	ComplianceCheck:view

API-Datenzugriff (Auswahl):

Action	Subject	Endpoint	Keycloak-Rolle
view	Employee	GET /api/employees, GET /api/employees/:id, GET /api/employees/me	APP_SPEAMCORE_VIEW_EMPLOYEE
create	Employee	POST /api/employees	APP_SPEAMCORE_CREATE_EMPLOYEE
update	Employee	PATCH /api/employees/:id, POST /api/employees/:id/favorite-tiles/toggle	APP_SPEAMCORE_UPDATE_EMPLOYEE
do	ManageKeycloakOrphan	GET /api/employees/keycloak-orphans, POST /api/employees/link-keycloak-user/:keycloakUserId	APP_SPEAMCORE_DO_MANAGE_KEYCLOAK_ORPHAN
do	DeleteKeycloakUser	DELETE /api/employees/keycloak-users/:keycloakUserId	APP_SPEAMCORE_DO_DELETE_KEYCLOAK_USER
do	ResetEmployeePassword	POST /api/employees/:id/reset-password	APP_SPEAMCORE_DO_RESET_EMPLOYEE_PASSWORD

Schritt-für-Schritt-Anleitung

Mitarbeiter anlegen

1. Mitarbeiter (/employees) → + Neu.
2. firstName, lastName, email, employeeType (internal / external / api).
3. Optional password setzen (initial; im Keycloak hinterlegt). password ist nur in der Anlage-Maske vorhanden — danach nicht mehr editierbar.
4. Speichern. Bei internal wird automatisch ein Keycloak-User mit keycloakUserId verknuepft.

Passwort zuruecksetzen

1. Mitarbeiter-Detailseite öffnen.
2. Passwort zuruecksetzen klicken. Erfordert do:ResetEmployeePassword.
3. Mitarbeiter erhaelt ein temporaeres Passwort und muss es beim nächsten Login ändern.

Keycloak-Orphans aufloesen

Wenn in Keycloak Benutzer existieren, die keinem Mitarbeiter zugeordnet sind:

1. Liste über GET /api/employees/keycloak-orphans (Admin-UI; erfordert do:ManageKeycloakOrphan).
2. Verknuepfen ruft POST /api/employees/link-keycloak-user/:keycloakUserId und legt einen Mitarbeiter zum Keycloak-User an.

Toolbar (Detail-Seite)

Die Mitarbeiter-Detailseite hat eine wichtige Spezial-Aktion:

Icon	Aktion (aria-label)	CASL	Wirkung
←	Zurückgehen	—	Zurück zur Mitarbeiterliste.
🏠	Zur Startseite gehen	—	Springt auf das Dashboard / /.
🔄	Zu Fremddienstleister umwandeln	update:Employee + create:Contractor	Wandelt einen internen Mitarbeiter in einen externen Fremddienstleister (Contractor) um. Verträge, Zertifikate und Compliance-Daten werden migriert. Nicht reversibel ohne erneute manuelle Anlage.
⏮/◀/▶/⏭	Pagination	—	Navigation durch die gefilterte Mitarbeiterliste.

Die Umwandlung **Mitarbeiter → Fremddienstleister** ist eine kritische operative Entscheidung. Sie sollte erst genutzt werden, wenn der Mitarbeiter das Unternehmen verlässt und in eine externe Dienstleister-Beziehung wechselt (z. B. selbständiger Berater, Subunternehmer). Aktive Verträge werden archiviert; das `EmployeeOffice`-Mapping bleibt für historische Reports erhalten, aber der Mitarbeiter wird in zukünftigen Aufträgen nicht mehr als interner Auswahl-Kandidat angezeigt — stattdessen erscheint er unter [/contractors](/contractors).

Quick-Buttons (rechter Rand)

Die Mitarbeiter-Detailseite hat einen ZEIT-Quick-Button (gruener Tag rechts) — ein mitarbeiter-bezogener Wochen-Arbeitszeit-Tracker, fokussiert auf den geöffneten Mitarbeiter (im Gegensatz zum globalen ZEIT-Floating-Drawer links, der den eingeloggten Anwender zeigt).

Element	Funktion
Headline „ARBEITSZEIT (Mitarbeiter)"	Modal-Titel mit Mitarbeiter-Bezug.
Wochen-Aggregation	Stunden des aufgerufenen Mitarbeiters in der gewählten KW.
Mini-Wochengrid Mo–So	Tagessummen pro Wochentag.
Play/Stop + Timer	Stempeln im Namen des Mitarbeiters — nuetzlich für HR/Buchhaltung, die Stunden retrospektiv eintragen.
Stift-Icon	Manuell editieren.

Wirkung: Schreibt EmployeeTimeTracking-Datensaetze mit employeeId = aktueller Mitarbeiter (nicht currentUser). Erfordert create:EmployeeTimeTracking und update:Employee für andere Personen — sonst nur eigene Zeit möglich.

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: „+ Neu"

Erfordert create:Employee. Beim ersten Save kann optional password mitgegeben werden.

Button: „Passwort zuruecksetzen"

Detailseite. Erfordert do:ResetEmployeePassword. Setzt ein temporaeres Passwort, erzwingt Änderung beim nächsten Login.

Aktion: „Favoriten-Tile umschalten"

Im Dashboard verfuegbar; toggelt Einträge im favoriteTiles-Array via POST /employees/:id/favorite-tiles/toggle.

Felder und Eingaben

Feldname	Pflicht	Datentyp	Wirkung beim Ausfuellen	Voraussetzung
employeeNumber	nein	String	Personalnummer für interne Identifikation und Lohn-Exporte.	—
employeeType	ja	internal/external/api	Steuert Tab-Sichtbarkeit (z. B. api-Mitarbeiter haben reduzierte Tabs) und Lohn-Logik.	—
email	ja	E-Mail	Login-E-Mail. Wird beim Anlegen an Keycloak weitergegeben — daraus entsteht keycloakUserId.	internal ohne bestehenden Keycloak-User; eindeutig pro Realm.
firstName	nein	String	Anzeigename in Listen, Aufträgen und E-Mails.	—
lastName	nein	String	wie oben.	—
password	konditional	VIRTUAL	Nur bei Anlage befuellt — wird nicht persistiert. Im beforeCreate-Hook an Keycloak gepusht.	Nur bei Mitarbeiter-Anlage in der UI sichtbar.
status	ja	active/inactive	inactive blockt Login und blendet den Mitarbeiter in Auswahl-Listen aus.	—
fieldService	ja	Boolean	Markiert Aussendienst-Mitarbeiter — beeinflusst Disposition, Geo-Routing und mobile Funktionen.	—
backOffice	ja	Boolean	Markiert Innendienst — relevant für Schicht-/Buero-Ansichten.	—
requiredDeviceConsents	ja	Boolean	Wenn true: Mitarbeiter muss Geraete-Einwilligungen vor Login bestaetigen (DSGVO/Compliance).	—
complianceCheckEnabled	ja	Boolean	Wenn true: ArbZG-Compliance-Prüfung laeuft beim Login. Bei Verstoss wird Login blockiert oder gewarnt.	Compliance-Modul aktiv.
shareBirthday	nein	Boolean	Mitarbeiter erlaubt die interne Anzeige des Geburtstags auf Dashboard-Cards. Toggle-Wechsel wird über logConsentAudit als EmployeeComplianceCheck (type=other) protokolliert und sofort acknowledged.	Eigenes oder Admin-Update; Admin-Update löst Bestätigungs-Modal aus.
shareJubilee	nein	Boolean	Mitarbeiter erlaubt die interne Anzeige des Firmen-Jubiläums. Selbe Audit-Protokollierung wie shareBirthday.	wie oben.
substituteEmployeeId	nein	UUID (Lookup)	Vertretung — wer übernimmt bei Abwesenheit. Steht leer auf „Aktuell automatisch: …" (Vorschlag), bis aktiv gesetzt.	view:Employee.
hourlyRate (+ hourlyRateProductId)	nein	Decimal	Verrechnungssatz (Verkauf) — Kostensatz/Stunde des Mitarbeiters; fließt in die Kalkulation abrechenbarer Arbeitszeit ein. Optional an ein Stundensatz-Produkt gekoppelt.	—
keycloakUserId	automatisch	UUID	Verknuepfung zum Keycloak-User. Wird beim Anlegen oder über Keycloak-Orphan-Verknuepfen gesetzt.	OAuth/Keycloak-Anbindung.
favoriteTiles	—	Array	Persoenliche Favoriten-Navigation. Wird via POST /:id/favorite-tiles/toggle aktualisiert.	update:Employee.

Workflows und Zustaende

Wiederverwendbare Konzepte

• Berechtigungen verstehen (CASL)
• Polymorpher Parent-Pattern — Document/Assignment-Verknuepfungen.

Verknuepfungen zu anderen Modulen

• Verträge — EmployeeContract (1:N) — bestimmt aktives Arbeitszeitmodell, Branch, Office.
• Aufträge — Workorder.employeeId, employeeOfficeId, branchId werden aus Employee.activeContract abgeleitet.
• Verkaufsbelege — SalesDocument.employeeId.
• Mail-Konten — primary MailAccount über MailAccount.parentId (Mitarbeiter-Postfach).
• Compliance-Checks — ArbZG-Konformitaet vor Login (wenn complianceCheckEnabled = true).

Häufige Fehler und Lösungen

Fehler	Lösung
Login schlaegt fehl trotz Anlage	keycloakUserId nicht verknuepft (Orphan). Über Keycloak-Orphans-Tool verknuepfen.
Passwort-Reset nicht möglich	do:ResetEmployeePassword fehlt.
branchId nicht übernommen	Mitarbeiter hat keinen aktiven EmployeeContract.
Favoriten-Tiles werden nicht gespeichert	update:Employee fehlt — Toggle-Endpoint braucht Update-Permission.

API/Schnittstellen

Methode	Endpoint	Zweck	CASL
GET	/api/employees	Liste	view Employee
GET	/api/employees/me	Eigener Mitarbeiter	view Employee
POST	/api/employees	Anlegen	create Employee
GET	/api/employees/:id	Detail	view Employee
PATCH	/api/employees/:id	Ändern	update Employee
GET	/api/employees/:id/workTimeConfig	Effektive Arbeitszeit-Konfiguration (Vertrag → Modell → Land)	view Employee
GET	/api/employees/:id/time-balance	Kumulierte Stunden	view EmployeeContract, view WorkTimeModel, view EmployeeTimeTracking
POST	/api/employees/:id/reset-password	Temp-Passwort	do ResetEmployeePassword
POST	/api/employees/:id/favorite-tiles/toggle	Favoriten umschalten	update Employee
GET	/api/employees/keycloak-orphans	Verwaiste Keycloak-User	do ManageKeycloakOrphan
POST	/api/employees/link-keycloak-user/:keycloakUserId	Orphan zu Mitarbeiter verknuepfen	do ManageKeycloakOrphan
DELETE	/api/employees/keycloak-users/:keycloakUserId	Keycloak-User löschen	do DeleteKeycloakUser

DSGVO-Consent-Audit (Welle 115)

Toggles, die Sichtbarkeit personenbezogener Daten innerhalb des Mandanten steuern (shareBirthday, shareJubilee), durchlaufen einen revisionssicheren Audit-Mechanismus:

• Beim Toggle ruft das FE die Util logConsentAudit(...) (in src/utils/consentAuditLog.ts) auf.
• Diese legt einen Compliance-Check vom Typ other an (createEmployeeComplianceCheck) und acknowledged ihn unmittelbar (acknowledgeEmployeeComplianceCheck).
• Der Eintrag enthält den alten Wert, den neuen Wert, das Feld, einen menschenlesbaren Titel (z. B. „Geburtstag aktiviert") und den Kontext (admin oder self).
• Admin-Pfad: Beim Toggle im Mitarbeiter-Formular durch HR/Admin erscheint ein Bestätigungs-Modal mit Orange-Warning und DSGVO-Hinweis. Erst nach Bestätigung läuft logConsentAudit({…, context: "admin"}). Toast-Feedback bestätigt das Audit. Schlägt das Audit fehl, wird das Formular trotzdem gespeichert (Warn-Toast).
• Self-Pfad: Beim Toggle im eigenen Profil läuft das Audit still im Hintergrund (context: "self"), ohne Modal.

Die so erzeugten Audit-Einträge sind über /employees/:id/compliance-history (GET /api/employees/:id/employee-compliance-checks) abrufbar.

Versionshinweise

• 2026-04-29: Initiale Veröffentlichung.
• 2026-05-12 (Welle 115): Felder shareBirthday und shareJubilee als DSGVO-relevante Consent-Toggles dokumentiert. Audit-Mechanismus über EmployeeComplianceCheck (type=other) mit getrennten Pfaden für Admin (Pflicht-Modal) und Self (silent). Util: src/utils/consentAuditLog.ts. Employee-Form-Redesign: 12-Spalten-Grid mit klickbarem Status-Badge im Header.