docs: Factory-Defaults Import/Export-Anleitung in READMEs

Haupt-README.md: neuer Abschnitt mit Abgrenzung zu Datenbank-Backup, Schritt- für-Schritt-Anleitung für Export und Import, Idempotenz-Hinweis, Berechtigungen. backend/factory-defaults/README.md: ausführliche Referenz mit Struktur-Beispielen aller JSON-Dateien (Provider, CancellationPeriod, ContractDuration, ContractCategory, PdfTemplate), Teil-Import-Anleitung, Merge-Beispiele. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-23 14:19:02 +02:00
parent 60dc98e265
commit 109f774d62
2 changed files with 358 additions and 30 deletions
@@ -916,6 +916,123 @@ Folgende Felder werden in Audit-Logs gefiltert:
 - API-Response wird nicht blockiert
 - Before/After-Werte über Prisma Middleware

+## Factory-Defaults: Stammdaten-Kataloge teilen
+
+Das **Factory-Defaults**-System erlaubt den Export und Import von
+Stammdaten-Katalogen (Anbieter, Tarife, PDF-Vorlagen usw.) zwischen verschiedenen
+OpenCRM-Installationen. Es ist bewusst **streng abgegrenzt** zu Datenbank-Backups:
+
+### Abgrenzung
+
+| | Factory-Defaults | Datenbank-Backup |
+|---|---|---|
+| Anbieter, Tarife, Kündigungsfristen, Laufzeiten, Kategorien | ✅ | ✅ |
+| PDF-Auftragsvorlagen (inkl. Dateien + Feldzuordnungen) | ✅ | ✅ |
+| **Kundendaten, Verträge, Dokumente** | ❌ | ✅ |
+| **Emails, SMTP-/IMAP-Zugangsdaten** | ❌ | ✅ |
+| **System-Einstellungen, Datenschutzerklärungen, Impressum** | ❌ | ✅ |
+| Zwischen verschiedenen Installationen teilbar | ✅ | ❌ (zu firmen-spezifisch) |
+
+> **Kurz:** Factory-Defaults = reine Kataloge, Backup = alles.
+
+### Export (Installation A → ZIP)
+
+1. **Einstellungen** → **Factory-Defaults** öffnen
+2. Übersicht prüfen (Anzahl pro Kategorie)
+3. Button **„Factory-Defaults exportieren"** klicken
+4. ZIP wird als `factory-defaults-YYYY-MM-DD.zip` heruntergeladen
+
+**ZIP-Struktur:**
+```
+factory-defaults-2026-04-23.zip
+├── manifest.json                      # Version + Datum + Counts
+├── providers/
+│   └── providers.json                 # Anbieter inkl. zugehöriger Tarife
+├── contract-meta/
+│   ├── cancellation-periods.json      # Kündigungsfristen (Code + Beschreibung)
+│   ├── contract-durations.json        # Laufzeiten (Code + Beschreibung)
+│   └── contract-categories.json       # Kategorien (Strom, Gas, DSL, ...)
+└── pdf-templates/
+    ├── pdf-templates.json             # Vorlagen-Metadaten + Feldzuordnungen
+    └── *.pdf                          # Die eigentlichen PDF-Dateien
+```
+
+Die ZIP kann an andere Installationen weitergegeben werden
+(Partner, Test-System, neue Installation).
+
+### Import (ZIP → Installation B)
+
+1. ZIP herunterladen bzw. erhalten
+2. Inhalt nach `backend/factory-defaults/` entpacken (Unterordnerstruktur beibehalten)
+3. Im Backend-Verzeichnis ausführen:
+   ```bash
+   npm run seed:defaults
+   ```
+
+**Beispiel-Output:**
+```
+📦 Factory-Defaults werden eingespielt...
+
+  ✓ Anbieter: 7, Tarife: 12
+  ✓ Kündigungsfristen: 5
+  ✓ Laufzeiten: 4
+  ✓ Vertragskategorien: 8
+  ✓ PDF-Vorlagen: 3
+
+✅ Factory-Defaults erfolgreich eingespielt.
+```
+
+### Mehrere ZIPs kombinieren
+
+Du kannst mehrere Exporte in `backend/factory-defaults/` übereinanderlegen –
+JSON-Dateien werden automatisch gemerged:
+
+```
+backend/factory-defaults/
+  providers/
+    verivox.json       # 40 Anbieter aus Verivox-Paket
+    check24.json       # 30 Anbieter aus Check24-Paket
+    eigene.json        # 5 eigene Anbieter
+```
+
+Das Import-Script liest **alle** `*.json` im jeweiligen Unterordner und merged per
+unique Key (letzter Eintrag gewinnt). Duplikate sind also unproblematisch.
+
+### Idempotenz
+
+Das Script nutzt ausschließlich Prisma `upsert`:
+- **Neue Einträge** werden angelegt
+- **Bestehende Einträge** (per unique Key: `name`, `code`) werden aktualisiert
+- Nichts wird gelöscht
+
+Du kannst `npm run seed:defaults` also beliebig oft ausführen, ohne Datenverlust
+oder Duplikate.
+
+### PDF-Dateien beim Import
+
+Beim Import werden PDF-Vorlagen aus `factory-defaults/pdf-templates/*.pdf` nach
+`uploads/pdf-templates/` kopiert und die Pfade in der DB entsprechend gesetzt.
+Beim Re-Import wird die alte Datei in `uploads/` entsorgt und durch die neue
+ersetzt.
+
+### Berechtigungen
+
+| Aktion | Berechtigung |
+|--------|--------------|
+| Factory-Defaults Vorschau | `settings:read` |
+| Factory-Defaults Export | `settings:update` |
+| Factory-Defaults Import (CLI) | Server-Zugang (SSH/Shell) |
+
+### Typischer Einsatzzweck
+
+- **Neue Installation aufsetzen**: Eine Kollegen-ZIP importieren und sofort mit
+  gepflegtem Anbieter- und Vorlagenkatalog loslegen
+- **Vorlagen-Paket teilen**: Eine ZIP mit nur PDF-Vorlagen weitergeben
+  (die anderen Ordner einfach aus der ZIP entfernen vor dem Entpacken)
+- **Anbieter-Paket teilen**: ZIP mit nur `providers/` weitergeben
+- **Versionskontrolle**: Die entpackten JSON-Dateien unter Versionskontrolle
+  stellen (außerhalb von `backend/factory-defaults/`, da der Ordner gitignored ist)
+
 ## Lizenz

 MIT