Subunternehmer (Contractors)

Zweck

Contractor ist eine Sonderform des Mitarbeiter-Modells (Employee mit employeeType = contractor). Subunternehmer werden separat verwaltet, haben eigene Sub-Listen für Stundensaetze (/contractors/:id/cost-rates), Dokumente und Zeiterfassungen, koennen aber bei Bedarf einen Keycloak-User (Login) erhalten.

Hinter den Kulissen verwendet `/contractors` das gleiche Datenmodell wie [/employees](/employees) — der Filter `employeeType = contractor` trennt sie. Die FE-Page bietet jedoch ein vereinfachtes Form mit nur den Subunternehmer-relevanten Feldern.

Voraussetzungen

- Berechtigung `view:Employee` und `create:Employee`. - Optional Keycloak-Realm aktiv, falls Login für Subunternehmer gewünscht. - Sub-Listen erfordern `view:ContractorEmployeeCostRate`, `view:EmployeeTimeTracking`, `view:Document`.

Berechtigungen (CASL)

Action	Subject	Wirkung	Keycloak-Rolle
view	FE_Contractor, Employee	Liste/Detail aufrufbar	—
create/update/delete	Employee	Pflegen	APP_SPEAMCORE_CREATE/UPDATE/DELETE_EMPLOYEE
view	ContractorEmployeeCostRate	Stundensatz-Sub-Liste	APP_SPEAMCORE_VIEW_CONTRACTOR_EMPLOYEE_COST_RATE
view	EmployeeTimeTracking	Zeit-Sub-Liste	APP_SPEAMCORE_VIEW_EMPLOYEE_TIME_TRACKING
view	Document	Dokument-Sub-Liste	APP_SPEAMCORE_VIEW_DOCUMENT

Schritt-für-Schritt-Anleitung

1. Subunternehmer (/contractors) → + Neu.
2. employeeNumber (interne Nummer) und name pflegen.
3. email ergaenzen — falls gesetzt, wird beim Backend-Save ein Keycloak-User ohne Rollen angelegt.
4. Service-Typ (Switches): fieldService (Aussendienst), backOffice (Innendienst).
5. language wählen — bestimmt die Spracheinstellung im Login.
6. status = active.

Sub-Listen (Tabs auf der Detail-Seite)

Sub-Route	Inhalt	Anlege-Pattern
/contractors/:id/cost-rates	Stundensaetze pro Service-Typ und Datum (ContractorEmployeeCostRate)	Inline-Row-Editing — neue Zeile, Service wählen, Tagessatz/Stundensatz, validFrom/validTo. Sich ueberlappende Zeitraeume sind nicht zulässig (Backend-Validierung).
/contractors/:id/employee-time-trackings	Erfasste Arbeitszeit (EmployeeTimeTracking mit contractorId)	Inline-Row-Editing analog Auftrag-Arbeitszeit — Service-Auswahl, Start/Ende, Abrechenbar-Toggle. Wichtig für Subunternehmer-Abrechnung.
/contractors/:id/documents	Verträge, Bescheinigungen, Versicherungs-Nachweise	Standard-Document-Pattern (siehe Dokumente und Anhaenge). Typische Inhalte: Werkvertrag, A1-Bescheinigung, Berufshaftpflicht-Nachweis, Branchen-Zertifikate.

**Subunternehmer-Abrechnung-Workflow:** Der `Contractor` erfasst Arbeitszeit auf einem Auftrag (entweder via `/workorders/:id/working-times` mit Auswahl als Mitarbeiter, oder direkt am Auftrag via Quick-Button). Der Stundensatz wird **nicht aus dem Mitarbeiter-Vertrag** gezogen, sondern aus `ContractorEmployeeCostRate.rate` zum Zeitpunkt der Erfassung (Datum-Match auf `validFrom`/`validTo`). Bei der Beleg-Erstellung erscheinen Subunternehmer-Stunden in einer separaten Position-Gruppe.

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
employeeNumber	nein	String	Interne Nummer für Reports und Rechnungen.	—
status	ja	ENUM (active, inactive)	Steuert Sichtbarkeit.	—
email	nein	String	Email des Subunternehmers. Bei gesetzt: Keycloak-User wird angelegt.	—
name	nein	String	Anzeigename.	—
fieldService	nein	Boolean	Subunternehmer hat Aussendienst-Aufgaben.	—
backOffice	nein	Boolean	Subunternehmer hat Innendienst-Aufgaben.	—
language	nein	String (BCP-47 Locale)	Login-Sprache und Mail-Default.	—

Wiederverwendbare Konzepte

• Berechtigungen verstehen (CASL)

Verknuepfungen zu anderen Modulen

• Mitarbeiter — gleiches Modell, gefiltert nach employeeType.
• Document-Center — Verträge, Versicherungen.
• Zeiterfassungen — geleistete Arbeit.
• Workorders — Subunternehmer koennen als Bearbeiter zugewiesen werden.

Häufige Fehler und Lösungen

Fehler	Lösung
Subunternehmer erscheint in Mitarbeiter-Liste	Filter employeeType = contractor greift nur auf /contractors. In /employees werden alle Typen angezeigt.
Keycloak-User wurde nicht angelegt	email muss beim Anlegen gesetzt sein.

API/Schnittstellen

Methode	Endpoint	Zweck	CASL
GET	/api/contractors	Liste (filtert auf employeeType = contractor)	view Employee
POST	/api/contractors	Anlegen	create Employee
GET	/api/contractors/:id	Detail	view Employee
PATCH	/api/contractors/:id	Ändern	update Employee
DELETE	/api/contractors/:id	Soft-Delete	delete Employee
GET	/api/contractor-employee-cost-rates?filter[employeeId]	Stundensaetze	view ContractorEmployeeCostRate
GET	/api/employee-time-trackings?filter[employeeId]	Zeit-Sub-Liste	view EmployeeTimeTracking

Versionshinweise

• 2026-04-30: Initiale Veroeffentlichung.