From 0a840f9033ae5cb377fdfaa343af995201c81570 Mon Sep 17 00:00:00 2001 From: Martin Porwoll Date: Fri, 9 Jan 2026 01:37:22 +0000 Subject: [PATCH] docs: add critical guidance for adding new collections Document the payload_locked_documents_rels system table requirement: - Every new collection needs a column in this system table - Without it, RSC render errors occur after login - Include SQL template for migrations - Add guidance for array fields requiring extra tables Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 41 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 40 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 8a13378..97527e5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -287,6 +287,45 @@ scripts/backup/setup-backup.sh # Backup-System einricht 2. `git add src/migrations/` - Migration committen 3. Auf PROD nach Deployment: `./scripts/sync-schema.sh` wird automatisch ausgeführt +### ⚠️ KRITISCH: Neue Collections hinzufügen + +Beim Hinzufügen einer neuen Collection müssen **System-Tabellen** manuell aktualisiert werden! + +**Problem:** Payload CMS verwendet `payload_locked_documents_rels` um Document-Locks über alle Collections zu tracken. Diese Tabelle benötigt eine `{collection}_id` Spalte für JEDE Collection. Ohne diese Spalte tritt nach dem Login ein RSC-Fehler auf: +``` +Error: An error occurred in the Server Components render +caused by: column payload_locked_documents_rels.{collection}_id does not exist +``` + +**Lösung:** Die Migration für eine neue Collection MUSS folgendes enthalten: + +```sql +-- 1. Collection-Tabellen erstellen (normal) +CREATE TABLE IF NOT EXISTS "{collection}" (...); +CREATE TABLE IF NOT EXISTS "{collection}_rels" (...); -- falls benötigt +CREATE TABLE IF NOT EXISTS "{collection}_locales" (...); -- falls lokalisiert + +-- 2. KRITISCH: System-Tabelle aktualisieren! +ALTER TABLE "payload_locked_documents_rels" + ADD COLUMN IF NOT EXISTS "{collection}_id" integer + REFERENCES {collection}(id) ON DELETE CASCADE; + +CREATE INDEX IF NOT EXISTS "payload_locked_documents_rels_{collection}_idx" + ON "payload_locked_documents_rels" ("{collection}_id"); +``` + +**Beispiel-Migration:** `src/migrations/20260109_020000_add_blogwoman_collections.ts` + +**Array-Felder:** Collections mit Array-Feldern (z.B. `hours_structured` in Locations) benötigen zusätzliche Tabellen: +```sql +CREATE TABLE IF NOT EXISTS "{collection}_{array_field}" ( + "id" serial PRIMARY KEY NOT NULL, + "_order" integer NOT NULL, + "_parent_id" integer NOT NULL REFERENCES {collection}(id) ON DELETE CASCADE, + -- Array-Feld-Spalten hier +); +``` + ## Bekannte Besonderheiten - **ES Modules:** package.json hat `"type": "module"`, daher PM2 Config als `.cjs` @@ -1177,4 +1216,4 @@ ssh payload@162.55.85.18 ### Scripts & Backup - `scripts/backup/README.md` - Backup-System Dokumentation -*Letzte Aktualisierung: 29.12.2025* +*Letzte Aktualisierung: 09.01.2026*