breadcrumb-the-shire/docs/explanation-einstellungen-speicherung.md

# Einstellungen: Speicherung (DB + Cache)

Letzte Aktualisierung: 2026-03-25

## Kurzfassung

- **Source of truth ist immer die Tabelle `settings` in der Datenbank.**
- `storage/runtime/settings.php` ist nur ein **Teil-Cache** für wenige, sehr häufig gelesene UI-Basiswerte.
- Nicht alle Settings müssen oder sollen im Datei-Cache stehen.

## Warum es beides gibt

Die Kombination ist bewusst so gebaut:

1. **DB als Wahrheit**
   - Alle Settings werden persistiert in `settings`.
   - Validierung und Schreiblogik laufen über domänenspezifische Gateways und `AdminSettingsService`.

2. **Datei-Cache für Hot-Path-Reads**
   - `storage/runtime/settings.php` wird durch `SettingCacheService` geschrieben.
   - Verwendet wird er über `appSetting(...)` nur für globale Basiswerte wie:
     - `app_title`
     - `app_locale`
     - `app_registration`

   Appearance-Settings (Theme, Primärfarbe, Erlaubnis für User-Themes) sind
   **tenant-scoped** und werden nicht global gecached — sie liegen auf dem
   Tenant (`tenants.primary_color`, `default_theme`, `allow_user_theme`).

## Was **nicht** im Cache der Datei liegen muss

Sicherheits- oder Integrationswerte werden direkt aus DB gelesen, z. B.:

- SMTP (`smtp_host`, `smtp_port`, `smtp_user`, `smtp_from`, ...)
- Microsoft SSO Shared App Settings
- API-spezifische Policies
- User-Lifecycle-Policies (`user_inactivity_deactivate_days`, `user_inactivity_delete_days`)
- Scheduler-/Job-Konfiguration (`scheduled_jobs`, `scheduled_job_runs`)

Daher ist es korrekt, wenn diese Werte in `settings` (DB) vorhanden sind, aber nicht in `storage/runtime/settings.php`.

## Laufzeitfluss

1. Admin speichert Settings in `admin/settings`.
2. `AdminSettingsService` koordiniert domänenspezifische Gateways (z. B. `SettingsAppGateway`, `SettingsSmtpGateway`, `SettingsMetadataGateway`), die auf `SettingRepository` delegieren und in die DB schreiben.
3. `SettingCacheService` aktualisiert den Datei-Cache nur für den definierten Teilbereich.
4. UI-Helfer `appSetting(...)` liest danach aus Datei-Cache.

## Wenn DB und Datei scheinbar nicht zusammenpassen

Das ist oft erwartbar, solange es um nicht-gecachte Keys geht.

Prüfregel:

- Geht es um `appSetting(...)`-Keys? Dann Datei-Cache relevant.
- Geht es um SMTP/SSO/API-Details? Dann DB ist massgeblich.

## Betriebs-Hinweis

Direkte DB-Änderungen an gecachten `appSetting(...)`-Keys werden erst wirksam, wenn der Datei-Cache aktualisiert wurde
(z. B. durch erneutes Speichern in den Settings).