Custom User Fields System

Custom User Fields ermöglichen es Admins, zusätzliche Informationen über Mitarbeiter zu speichern und diese für die Schichtzuweisung zu nutzen (z.B. "Hat Gabelstaplerführerschein", "Allergien: keine").

Für Admins

Was sind Custom User Fields?

Custom User Fields sind zusätzliche Felder, die für jeden Mitarbeiter verfügbar sind. Du kannst sie im Team Management konfigurieren und dann:

• Beim Anlegen/Bearbeiten von Mitarbeitern ausfüllen
• In der Mitarbeiter-Ansicht und Quick-Edit-Dialogen sehen
• Für Schicht-Anforderungen verwenden (z.B. nur Mitarbeiter mit Gabelstaplerführerschein für diese Schicht)

Schritt-für-Schritt: Custom Fields einrichten

1. Feld erstellen

1. Geh zu Admin > System > Team-Einstellungen
2. Scrolle zum Abschnitt Custom User Fields
3. Klick auf + Feld hinzufügen
4. Fülle die folgenden Felder aus:

Feldtypen erklärt:

• text — Text eingeben (z.B. Sprachen, Qualifikationen): "English", "Spanish"
• boolean — Ja/Nein Auswahl: true (Ja) oder false (Nein)
• number — Zahl eingeben (z.B. Zertifikat-Nummern): 12345

2. Feld bearbeiten

1. Geh zu Admin > System > Team-Einstellungen > Custom User Fields
2. Klick auf das Feld, das du ändern möchtest
3. Ändere die Werte
4. Speicher die Änderungen

3. Feld löschen

⚠️ Wichtig: Wenn du ein Feld löschst, verlieren alle Mitarbeiter diese Daten!

1. Geh zu Admin > System > Team-Einstellungen > Custom User Fields
2. Klick neben dem Feld auf den Löschen-Button (🗑)
3. Bestätige die Löschung

4. Reihenfolge ändern

1. Geh zu Admin > System > Team-Einstellungen > Custom User Fields
2. Nutze die Pfeile neben jedem Feld zum Verschieben
3. Speichern

Wo werden Custom Fields angezeigt?

Für Admins

• Benutzer bearbeiten: Admin > Benutzerverwaltung > Mitarbeiter auswählen > Bearbeiten
  • Alle Custom Fields werden im Formular angezeigt
  • Erforderliche Felder sind mit * markiert
• Admin Calendar — Employee Quick Info:
  • Wenn Admin einen Mitarbeiter anklickt, sieht er/sie die Custom Fields

Für Mitarbeiter

• Profil bearbeiten: Mein Konto > Profil > Bearbeiten
  • Alle nicht-leeren Custom Fields werden angezeigt
  • Erforderliche Felder müssen ausgefüllt sein

Custom Fields in der Schichtzuweisung nutzen

Custom Fields können als Anforderungen für Schichten genutzt werden. Das läuft über die Kompatibilitätsprüfung:

Setup (für Admins, die Schichten erstellen)

1. Erstelle eine Schicht oder bearbeite eine existierende unter Admin > Planning > Events > Schicht hinzufügen
2. Im Abschnitt Anforderungen oder Required Fields kannst du einstellen: "Diese Schicht braucht Feld X"
3. Speichern

Auswirkung bei Schichtzuweisung

Wenn ein Admin einen Mitarbeiter zu einer Schicht mit Custom-Field-Anforderung zuordnen möchte:

• Mitarbeiter hat das Feld erfüllt: Keine Warnung, Zuweisung möglich
• Mitarbeiter hat das Feld NICHT erfüllt: Warnung (oder Fehler, wenn Strict Mode an ist)

  ⚠️ Warnung: Mitarbeiter erfüllt Anforderung nicht: "Gabelstaplerführerschein"

Praktische Beispiele

Beispiel 1: Gabelstaplerführerschein (Boolean)

ID: forklift_license
Name: Gabelstaplerführerschein
Type: boolean
Erforderlich: Nein (Mitarbeiter können es später eintragen)
Standardwert: false (Nein)

Verwendung:

• Admin erstellt Schicht: "Lagerverwaltung" und fordert forklift_license = true
• Nur Mitarbeiter mit Gabelstaplerführerschein können zugewiesen werden

Beispiel 2: Sprachen (Text)

ID: languages
Name: Sprachkenntnisse
Type: text
Erforderlich: Ja (muss dokumentiert sein)
Standardwert: "" (nicht gesetzt)

Verwendung:

• Admin kann alle Mitarbeiter mit "English" filtern
• Schichten für englischsprachige Gäste werden nur Mitarbeitern mit "English" zugewiesen

Beispiel 3: Zertifikat-Nummer (Number)

ID: cert_number
Name: Sicherheitszertifikat-Nr.
Type: number
Erforderlich: Ja
Standardwert: "" (nicht gesetzt)

For Developers

Data Model

Custom User Fields werden auf zwei Ebenen gespeichert:

Team-seitig: team.customUserFields

// Definition aller möglichen Custom Fields
team.customUserFields = [
  {
    id: "forklift_license",
    name: "Gabelstaplerführerschein",
    type: "boolean",           // 'boolean' | 'text' | 'number'
    description: "Hast du einen gültigen Gabelstaplerführerschein?",
    required: false,
    defaultValue: false,
    icon: "mdi:certificate"    // optional
  },
  ...
];

User-seitig: user.customFields

// Tatsächliche Werte für einen Mitarbeiter
user.customFields = {
    forklift_license: true,
    languages: 'English, Spanish',
    cert_number: 12345,
};

Implementation References

1. Configuration UI: src/sections/teams/edit-form/users.tsx

   • Allows admins to add/edit/delete custom fields
   • Uses React Hook Form + Zod validation

2. User Edit Form: src/sections/user/user-quick-edit-form-custom-fields.tsx

   • Renders custom field inputs (boolean → Switch, text/number → Text Input)
   • Located at: fieldsBaseName.${field.id}

3. Compatibility Checks: src/sections/admin-calendar-v2/daily-planning/utils/compatibility-check.ts

   • Reads shift.requiredUserFields (array of field IDs)
   • Checks user.customFields[fieldId] against requirement
   • Key logic (L396-404):

     for (const requiredField of shift.requiredUserFields) {
         const field = team?.customUserFields?.find((f) => f.id === requiredField);
         if (employee.user.customFields?.[requiredField] !== true) {
             // Add warning/error
         }
     }

   • When strictModeEnabled, these warnings become blocking errors

4. Types:

   • DBTeam.customUserFields: Array of field definitions
   • DBUser.customFields: Record<fieldId, value>
   • See: _types/teams.ts, _types/users.ts

Usage in Planning

When an admin assigns a shift with required custom fields:

1. System reads shift.requiredUserFields (list of field IDs)
2. For each field ID, system checks:
   • Does team.customUserFields have this field defined?
   • Does employee.user.customFields[fieldId] match the requirement?
3. If mismatch → warning or error (depending on strictModeEnabled)

This allows flexible, team-specific requirements without code changes.