Zum Inhalt

Work Time Compliance Modul

Zweck

Das Work Time Compliance Modul bietet automatische Überwachung der Einhaltung von EU- und deutschen Arbeitszeitregeln. Es unterstützt Echtzeit-Verstoß-Erkennung, konfigurierbare Regel-Sets, unveränderbare Audit-Timeline und Export-Funktionen für Prüfungen (CSV/PDF).

Verantwortlichkeiten

Was gehört zum Modul

  • Compliance-Prüfung: Automatische Prüfung von Arbeitszeitregeln
  • Verstoß-Erkennung: Echtzeit-Erkennung von Verstößen
  • Regel-Sets: Konfigurierbare Regel-Sets (EU, DE, Custom)
  • Audit-Timeline: Unveränderbare Timeline für Compliance-Audits
  • Export-Funktionen: CSV/PDF Export für Prüfungen

Was gehört nicht zum Modul

Implementierung

Backend- und Frontend-API sind modular aufgebaut; Details siehe interne Entwickler-Dokumentation.

Konfiguration

Entitlement

Das Modul erfordert das Entitlement module.work_time_compliance. Dieses wird pro Tenant aktiviert/deaktiviert.

Entitlement-Key: module.work_time_compliance

Environment Variables

Keine modulspezifischen ENV-Variablen erforderlich.

Defaults

  • Standard-Regel-Set: DE (Deutschland)
  • Prüfungs-Intervall: Echtzeit (bei jeder Zeiterfassung)

Abhängigkeiten

Optionale Abhängigkeiten

Keine.

Core-Abhängigkeiten

  • time-tracking: Für Zeiterfassungs-Daten
  • shift-pool: Für Schicht-Daten

API-Endpoints

Authentifizierung

Alle Endpoints erfordern Authentifizierung. Zwei Methoden werden unterstützt:

  1. Firebase ID Token (Standard für Web-App)
  2. API-Token (für externe Nutzung)

Header: Authorization: Bearer <token>

Compliance-Statistiken abrufen

GET /api/work-time-compliance/stats

Gibt Compliance-Statistiken zurück.

Response: 

{
  "totalViolations": 10,
  "unacknowledgedViolations": 5,
  "violationsByType": {
    "max_daily_hours": 3,
    "min_rest_period": 2
  },
  "violationsBySeverity": {
    "warning": 7,
    "error": 3
  }
}

Compliance prüfen

POST /api/work-time-compliance/check

Manuelle Compliance-Prüfung für einen Zeitraum und User.

Request Body: 

{
  "userId": "user123",
  "startDate": "2024-01-01",
  "endDate": "2024-01-31"
}

Response: 

{
  "violations": [
    {
      "id": "violation123",
      "userId": "user123",
      "type": "max_daily_hours",
      "severity": "error",
      "date": "2024-01-15",
      "details": {
        "actualHours": 11,
        "maxHours": 10
      }
    }
  ],
  "count": 1
}

Fehler: - 400 VALIDATION_ERROR: startDate und endDate sind erforderlich

Verstöße abrufen

GET /api/work-time-compliance/violations?userId=user123&violationType=max_daily_hours&severity=error&acknowledged=false&from=2024-01-01&to=2024-01-31&limit=50&offset=0

Lädt Compliance-Verstöße mit Filterung.

Query-Parameter: - userId (optional): Filter nach User-ID - violationType (optional): Filter nach Verstoß-Typ (z.B. max_daily_hours, min_rest_period) - severity (optional): Filter nach Schweregrad (warning oder error) - acknowledged (optional): Filter nach Bestätigungsstatus (true/false) - from (optional): Start-Datum (ISO 8601) - to (optional): End-Datum (ISO 8601) - limit (optional): Maximale Anzahl (Standard: 50) - offset (optional): Offset für Pagination (Standard: 0)

Response: 

{
  "violations": [
    {
      "id": "violation123",
      "userId": "user123",
      "type": "max_daily_hours",
      "severity": "error",
      "date": "2024-01-15",
      "acknowledged": false,
      "details": {
        "actualHours": 11,
        "maxHours": 10
      },
      "createdAt": "2024-01-15T17:00:00Z"
    }
  ],
  "count": 1,
  "total": 10
}

Fehler: - 422 VALIDATION_ERROR: Ungültiger violationType oder severity

Verstoß-Details abrufen

GET /api/work-time-compliance/violations/:id

Lädt Details eines einzelnen Verstoßes.

Response: 

{
  "violation": {
    "id": "violation123",
    "userId": "user123",
    "type": "max_daily_hours",
    "severity": "error",
    "date": "2024-01-15",
    "acknowledged": false,
    "acknowledgedBy": null,
    "acknowledgedAt": null,
    "details": {
      "actualHours": 11,
      "maxHours": 10
    },
    "createdAt": "2024-01-15T17:00:00Z"
  }
}

Fehler: - 404 NOT_FOUND: Verstoß nicht gefunden

Verstoß bestätigen

POST /api/work-time-compliance/violations/:id/acknowledge

Markiert einen Verstoß als erkannt/bestätigt.

Request Body: 

{
  "acknowledged": true
}

Response: 

{
  "violation": {
    "id": "violation123",
    "acknowledged": true,
    "acknowledgedBy": "user123",
    "acknowledgedAt": "2024-01-15T18:00:00Z"
  }
}

Compliance-Regeln abrufen

GET /api/work-time-compliance/rules

Lädt das aktuelle Regel-Set für den Tenant.

Response: 

{
  "rule": {
    "ruleSet": "DE",
    "maxDailyHours": 10,
    "minRestPeriod": 11,
    "maxShiftDuration": 12,
    "updatedAt": "2024-01-15T10:00:00Z",
    "updatedBy": "admin123"
  }
}

Compliance-Regeln aktualisieren

PUT /api/work-time-compliance/rules

Aktualisiert das Regel-Set (nur Admin/Manager).

Request Body: 

{
  "ruleSet": "DE",
  "maxDailyHours": 10,
  "minRestPeriod": 11,
  "maxShiftDuration": 12
}

Response: 

{
  "rule": {
    "ruleSet": "DE",
    "maxDailyHours": 10,
    "minRestPeriod": 11,
    "maxShiftDuration": 12,
    "updatedAt": "2024-01-15T10:00:00Z",
    "updatedBy": "admin123"
  }
}

Fehler: - 422 VALIDATION_ERROR: Ungültiges ruleSet - 403 ADMIN_OR_MANAGER_REQUIRED: Nur Admin oder Manager können Regeln aktualisieren

Prüfungs-Report generieren

POST /api/work-time-compliance/reports/generate

Generiert einen Prüfungs-Report (CSV/PDF) (nur Admin/Manager).

Request Body: 

{
  "periodStart": "2024-01-01",
  "periodEnd": "2024-01-31",
  "format": "csv",
  "filters": {
    "userId": "optional-user-id",
    "violationType": "optional-violation-type"
  }
}

Response: 

{
  "report": {
    "id": "report123",
    "periodStart": "2024-01-01",
    "periodEnd": "2024-01-31",
    "format": "csv",
    "status": "generating",
    "downloadUrl": null,
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

Fehler: - 400 VALIDATION_ERROR: periodStart, periodEnd und format sind erforderlich - 422 VALIDATION_ERROR: Format muss csv oder pdf sein - 403 ADMIN_OR_MANAGER_REQUIRED: Nur Admin oder Manager können Reports generieren

Report abrufen

GET /api/work-time-compliance/reports/:id

Lädt einen generierten Report.

Response: 

{
  "report": {
    "id": "report123",
    "periodStart": "2024-01-01",
    "periodEnd": "2024-01-31",
    "format": "csv",
    "status": "completed",
    "downloadUrl": "https://storage.googleapis.com/...",
    "createdAt": "2024-01-15T10:00:00Z",
    "completedAt": "2024-01-15T10:05:00Z"
  }
}

Fehler: - 404 NOT_FOUND: Report nicht gefunden

Audit-Logs abrufen

GET /api/work-time-compliance/audit-logs?action=rule_updated&from=2024-01-01&to=2024-01-31&limit=50&offset=0

Lädt die Audit-Timeline für Compliance-Aktionen.

Query-Parameter: - action (optional): Filter nach Aktion (z.B. rule_updated, violation_acknowledged) - from (optional): Start-Datum (ISO 8601) - to (optional): End-Datum (ISO 8601) - limit (optional): Maximale Anzahl (Standard: 50) - offset (optional): Offset für Pagination (Standard: 0)

Response: 

{
  "logs": [
    {
      "id": "log123",
      "action": "rule_updated",
      "userId": "admin123",
      "details": {
        "ruleSet": "DE",
        "changes": ["maxDailyHours"]
      },
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ],
  "count": 1,
  "total": 10
}

Firestore Collections

Compliance Violations

Pfad: /tenants/{tenantId}/complianceViolations/{violationId}

{
  userId: string;
  type: 'max_daily_hours' | 'min_rest_period' | 'max_shift_duration' | ...;
  severity: 'warning' | 'error';
  date: string; // ISO 8601
  details: Record<string, unknown>;
  createdAt: Timestamp;
}

Wird dokumentiert: Detaillierte Datenbank-Struktur folgt.

Fehlerfälle

HTTP-Status-Codes

  • 200 OK: Erfolgreich
  • 400 Bad Request: Validierungsfehler
  • 401 Unauthorized: Nicht authentifiziert
  • 403 Forbidden: Keine Berechtigung
  • 500 Internal Server Error: Server-Fehler

Fehlercodes

Die folgenden Fehlercodes werden von den API-Endpunkten zurückgegeben:

  • NOT_FOUND: Ressource nicht gefunden
  • VALIDATION_ERROR: Validierungsfehler bei Eingabedaten
  • MISSING_ENTITLEMENT: Work-Time-Compliance Entitlement fehlt
  • ADMIN_OR_MANAGER_REQUIRED: Nur Admin oder Manager können diese Operation ausführen
  • NO_TENANT: Keine Tenant-Mitgliedschaft

FAQ / Troubleshooting

Wird dokumentiert: Häufige Fragen und Lösungen folgen.