From 01a0a43f3929d1e8906a61f2053a4d9db70ffb55 Mon Sep 17 00:00:00 2001
From: Martin Porwoll <martin.porwoll@complexcaresolutions.de>
Date: Tue, 17 Feb 2026 09:48:39 +0000
Subject: [PATCH] docs: add tenant SMTP admin-save troubleshooting notes

---
 CLAUDE.md                |  1 +
 docs/CLAUDE_REFERENCE.md | 22 ++++++++++++++++++++++
 2 files changed, 23 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index a9039c7..f75c271 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -169,6 +169,7 @@ Beispiel: `src/migrations/20260109_020000_add_blogwoman_collections.ts`
 - **Admin Login:** Custom Route mit Audit-Logging (`src/app/(payload)/api/users/login/route.ts`)
 - **Queue Worker:** PM2 nutzt `node_modules/tsx/dist/cli.mjs` direkt (nicht `npx`), `exec_mode: 'fork'`
 - **PgBouncer:** Transaction-Mode kann Migrationen stören → `./scripts/db-direct.sh`
+- **Tenant SMTP Save (Stand 17.02.2026):** Bei conditional `email.smtp` keine Feld-`required` auf `host/user`; stattdessen Group-`validate` verwenden. Tenant-Audit-Hook darf Admin-Save nicht mit `await` blockieren.
 - **TRUST_PROXY=true:** PFLICHT hinter Reverse-Proxy, sonst funktionieren Rate-Limiting und IP-Allowlists nicht
 - **CSRF_SECRET:** PFLICHT in Production (oder PAYLOAD_SECRET) - Server startet nicht ohne
 
diff --git a/docs/CLAUDE_REFERENCE.md b/docs/CLAUDE_REFERENCE.md
index 89d0478..7ae7032 100644
--- a/docs/CLAUDE_REFERENCE.md
+++ b/docs/CLAUDE_REFERENCE.md
@@ -44,6 +44,28 @@ curl -X POST https://pl.porwoll.tech/api/send-email \
 - `src/lib/email/payload-email-adapter.ts` - Payload-Integration
 - `src/hooks/invalidateEmailCache.ts` - Cache-Invalidierung
 
+### Troubleshooting: Tenant SMTP Save hängt im Admin
+
+Stand: 17. Februar 2026
+
+**Symptom:**
+- Beim Speichern eines Tenants mit aktivem `email.useCustomSmtp` bleibt das Admin Panel bei "wird aktualisiert" hängen.
+- SMTP-Werte werden nicht zuverlässig in `tenants` persistiert.
+
+**Ursachen (behoben):**
+- Die SMTP-Felder lagen in einer conditional Group (`email.smtp`), während `required: true` auf Unterfeldern (`host`, `user`) serverseitig weiterhin greifen konnte.
+- Feld-Validierungen nutzten teilweise `siblingData` mit falschem Scope in der verschachtelten Struktur.
+- `afterChange` im Tenant-Audit-Log wartete synchron auf `payload.create()` für `audit-logs` und konnte die Admin-Response blockieren.
+
+**Implementierter Fix:**
+- Konditionale Pflichtvalidierung auf Gruppenebene `email.smtp.validate` verschoben (Prüfung gegen `email.useCustomSmtp`).
+- `required: true` von `email.smtp.host` und `email.smtp.user` entfernt; stattdessen explizite Group-Validierung.
+- Tenant-Audit-Hooks auf Fire-and-Forget umgestellt (`.catch(...)` statt `await`), analog zu User-Audit-Hooks.
+
+**Relevante Dateien:**
+- `src/collections/Tenants.ts`
+- `src/hooks/auditTenantChanges.ts`
+
 ## Newsletter (Double Opt-In)
 
 DSGVO-konformes Newsletter-System mit Double Opt-In.