Backend-Arbeitsstand: ERP-Sync, Lieferlebenszyklus, Reports + config.toml

Bringt das Backend vom initialen Skeleton auf den aktuellen Arbeitsstand
(Clean Architecture: domain → application → infrastructure → api).

Wesentliche Bereiche:
- ERP-Anbindung (MSSQL-Pull der Touren, Import-Scheduler, Rückschreiben)
- Lieferlebenszyklus: Scan/Hold/Cancel/Complete, Gutschriften, Notizen,
  Bild-Anhänge, Unterschriften, PDF-Lieferreport → DOCUframe
- Stammdaten: Kunden, Artikel, Lager, Zahlungsarten, Services
- Keycloak-JWT-Gate + Fahrer-Provisionierung via Admin-API
- Admin-API-Key-Gate (X-Admin-Api-Key) für Maschinen-Endpunkte

Jüngste Änderungen dieser Session:
- Belegspezifische Kontaktdaten: alle ERP-Adressen (Beleg-/Liefer-/
  Rechnungsadresse, Ansprechpartner, Kundenstamm) mit Telefon/Mobil/
  E-Mail werden gesynct (Migration 0029, MSSQL-Query, TourDetails)
- Konfiguration von .env (envy/dotenvy) auf config.toml (toml/serde)
  umgestellt; Vorlage config.example.toml, Pfad via HOLZLEITNER_CONFIG

Nicht im Repo (per .gitignore): config.toml (Secrets), data/ (Laufzeit-/
Kundendaten), demo.mp4, .claude/, variocontrol-ai/.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docker-compose.yml

@@ -2,9 +2,18 @@
 # Startbefehl: docker compose up -d
 #
 # Postgres-Daten landen im benannten Volume `postgres-data` und überleben
-# Container-Neustarts. Keycloak nutzt bewusst keinen persistenten Volume —
-# der Realm wird bei jedem Start frisch aus `keycloak/import/` importiert,
-# damit die Quellen-of-truth Versionierte Dateien bleiben.
+# Container-Neustarts.
+#
+# Keycloak hat seit der Fahrer-Provisionierung EBENFALLS ein persistentes
+# Volume (`keycloak-data` → /opt/keycloak/data): per Sync angelegte Fahrer-
+# Konten (Username = Fahrernummer, temporäres Passwort) überleben damit
+# Neustarts. ACHTUNG: `--import-realm` importiert nur, wenn der Realm noch
+# NICHT existiert — nach dem ersten Start werden Änderungen an
+# `keycloak/import/realm-holzleitner.json` also NICHT mehr automatisch
+# übernommen. Realm bewusst neu importieren / frische Demo-Daten:
+#   docker compose down -v && docker compose up -d   (löscht ALLE Volumes)
+# oder gezielt nur Keycloak:
+#   docker volume rm holzleitner-backend_keycloak-data  (Container vorher stoppen)
 # Komplettes Reset: `docker compose down -v`.
 
 services:
@@ -38,10 +47,22 @@ services:
       KC_BOOTSTRAP_ADMIN_PASSWORD: admin
       # Health-Endpoints für externe Checks aktivieren.
       KC_HEALTH_ENABLED: "true"
+      # Hostname, den Keycloak ins `iss`-Claim und in die Discovery-URLs
+      # schreibt. Per Default die LAN-IP (Android-Test über WLAN). Für den
+      # USB-Tunnel-Modus (`adb reverse`) mit
+      #   KC_HOSTNAME=localhost docker compose up -d
+      # überschreiben — dann muss auch das Backend mit
+      # KEYCLOAK_ISSUER_URL=http://localhost:8080/realms/holzleitner laufen
+      # (siehe tool/dev_usb.sh, das beides zusammen hochfährt).
+      KC_HOSTNAME: "${KC_HOSTNAME:-192.168.0.138}"
     ports:
       - "8080:8080"
     volumes:
+      # Persistente H2-DB: provisionierte Fahrer-Konten überleben Neustarts.
+      - keycloak-data:/opt/keycloak/data
+      # Realm-Import (nur beim ersten Start wirksam, s. Kopf-Kommentar).
       - ./keycloak/import:/opt/keycloak/data/import:ro
 
 volumes:
   postgres-data:
+  keycloak-data: