# Benutzerdefinierte Felder (V1) Kurzreferenz

Letzte Aktualisierung: 2026-03-06

## Ziel

Tenant-spezifische Zusatzfelder für User:

- Definitionen und Optionen werden pro Tenant gepflegt.
- Werte werden pro User gespeichert.
- Address-Book-Filter nutzen dynamische Query-Parameter.

## Berechtigungen

- `custom_fields.manage`
  - Definitionen/Optionen im Tenant-Tab pflegen.
- `custom_fields.edit_values`
  - Werte im User-Tab pflegen.

## Tabellen

- `tenant_custom_field_definitions`
  - Felddefinition pro Tenant (Label, Typ, aktiv, filterbar, `field_key` intern).
- `tenant_custom_field_options`
  - Optionen für `select`/`multiselect` je Definition.
- `user_custom_field_values`
  - Gespeicherter Wert pro `user_id + definition_id` (unique).
- `user_custom_field_value_options`
  - N:M-Optionen für Multiselect-Werte.

## Typen und Verhalten

- `text`, `textarea`
  - Eingabe am User möglich.
  - Nicht als Address-Book-Filter zugelassen.
- `select`, `multiselect`, `boolean`, `date`
  - Eingabe am User möglich.
  - Optional als Address-Book-Filter (wenn `is_filterable=1`).

## Wichtige Regeln

- `field_key`
  - Wird serverseitig aus Label erzeugt und tenant-weit eindeutig gehalten.
  - Kein manuelles UI-Feld.
- User-Werte sind in V1 optional (keine Pflichtvalidierung).
- Bei Tenant-Wechsel am User werden Werte außerhalb der aktuellen User-Tenants bereinigt.

## Query-Parameter im Address Book

- `cf_<definition_uuid>`
  - scalar/select/boolean
- `cfm_<definition_uuid>`
  - multiselect (CSV mit Option-IDs)
- `cfd_<definition_uuid>_from`
- `cfd_<definition_uuid>_to`
  - date-range

Unbekannte/manipulierte Parameter werden ignoriert.

## Relevante Pfade

- Tenant-Tab Formular:
  - `/pages/admin/tenants/_form.phtml`
- Tenant Actions:
  - `/pages/admin/tenants/custom-field-create($id).php`
  - `/pages/admin/tenants/custom-field-update($id).php`
  - `/pages/admin/tenants/custom-field-delete($id).php`
- User-Werte:
  - `/lib/Service/CustomField/UserCustomFieldValueService.php`
  - `/lib/Repository/CustomField/*`
- Address-Book-Filter:
  - `/pages/address-book/index().php`
  - `/pages/address-book/index(default).phtml`

## Troubleshooting (kurz)

- Multiselect speichert nichts:
  - Feldname ohne doppeltes `[]` prüfen.
- Optionen sind leer:
  - Label-Key für MultiSelect auf `label`/`description` prüfen.
- Filterbar ist deaktiviert:
  - Typ ist nicht in `select|multiselect|boolean|date`.