# Datenbank-Handling: Exports, Imports, Backups & Datensicherung

Dieses Dokument beschreibt, wie die PowerOn-Plattform ihre Datenbanken verwaltet — von der strukturierten Datensicherung über flexible Export- und Import-Werkzeuge bis hin zur sicheren Wiederherstellung.

---

## 1. Datenbankübersicht

Die Plattform betreibt **13 separate Datenbanken** auf dem Datenbankserver `db.poweron.swiss`. Jede Datenbank gehört einem fachlichen Bereich:

| Datenbank | Inhalt |
|---|---|
| `poweron_app` | Benutzer, Mandate, Berechtigungen, Features — Kern der Plattform |
| `poweron_management` | Workflows, Prompts, Verbindungen (Connections) |
| `poweron_billing` | Abonnements, Rechnungen, Stripe-Daten |
| `poweron_chat` | Chat-Konversationen und Nachrichten |
| `poweron_chatbot` | Chatbot-Feature: Konversationen, Logs |
| `poweron_knowledge` | RAG-Wissensdatenbank, Dokumentenindizes |
| `poweron_workspace` | Workspace-Daten |
| `poweron_trustee` | Treuhand-spezifische Daten |
| `poweron_realestate` | Immobilien-Daten |
| `poweron_commcoach` | CommCoach-Feature |
| `poweron_neutralization` | Content-Neutralisierung |
| `poweron_teamsbot` | Microsoft Teams Bot |
| `poweron_test` | Testdaten (wird bei Exports ausgeschlossen) |

---

## 2. Export

Ein Export erstellt eine vollständige Kopie aller Daten in einem lesbaren JSON-Format. Er dient als Grundlage für Backups, Migrationen zwischen Umgebungen (z. B. Prod → Int) und als Sicherungspunkt vor grösseren Änderungen.

### 2.1 Export via Admin-UI (empfohlen)

Im SysAdmin-Bereich der Plattform gibt es einen integrierten Export-Button. Er erzeugt eine JSON-Datei, die direkt heruntergeladen wird.

- **Zugriff:** Nur für SysAdmins (höchste Berechtigungsstufe)
- **Umfang:** Alle Datenbanken oder einzelne auswählbar
- **Dateiname:** `migration_backup_YYYY-MM-DD_HH-MM.json`
- **Rate-Limit:** Max. 2 Exports pro Minute (Schutzmassnahme gegen versehentliche Mehrfachausführung)

Auch sehr grosse Datenbanken werden sicher übertragen, ohne dass der Server dabei überlastet wird.

### 2.2 Export via Script (für Entwickler / Server-Zugriff)

Direkt auf dem Server kann das Export-Script ausgeführt werden:

```bash
ssh ubuntu@api.poweron.swiss
cd /srv/gateway/current
source .venv/bin/activate

# Alle Datenbanken exportieren
python scripts/script_db_export_migration.py --pretty

# Nur bestimmte Datenbanken
python scripts/script_db_export_migration.py --db poweron_app,poweron_management

# Ohne Metadaten (kleiner, für Archivierung)
python scripts/script_db_export_migration.py --exclude Token,AuthEvent

# Mit Zusammenfassung (zeigt Tabellen- und Zeilenanzahl)
python scripts/script_db_export_migration.py --summary
```

Das Script erstellt automatisch zwei Dateien:
- `migration_export_TIMESTAMP.json` — vollständige Daten
- `migration_export_TIMESTAMP_structure.json` — nur Tabellenstruktur, keine Daten

### 2.3 Was wird beim Export ausgeschlossen?

Aus Sicherheits- und Datenschutzgründen werden folgende Tabellen **nie** exportiert:
- `Token` (aktive Login-Sessions)
- `AuthEvent` (Login-Protokoll)
- `poweron_test` (Testdatenbank)

---

## 3. Import

Ein Import spielt einen zuvor erstellten Export wieder ein. Typische Anwendungsfälle:
- Wiederherstellung eines früheren Datenstands
- Migration zwischen Umgebungen (z. B. Produktionsdaten auf die Testumgebung übertragen)
- Initialisierung einer neuen Instanz

### 3.1 Zwei Import-Modi

**Replace (Ersetzen):**
Löscht alle bestehenden Daten (ausser geschützte System-Objekte, siehe unten) und schreibt den Backup-Stand vollständig neu. Verwenden bei vollständiger Wiederherstellung.

**Merge (Zusammenführen):**
Fügt nur Datensätze ein, die noch nicht existieren (anhand ID). Bestehende Daten bleiben unverändert. Verwenden wenn nur fehlende Daten ergänzt werden sollen.

### 3.2 Import via Admin-UI

1. JSON-Datei hochladen
2. Validation läuft automatisch (prüft Format-Version, Struktur, System-Objekte)
3. Import-Modus wählen: `replace` oder `merge`
4. Import starten — Ergebnis zeigt Anzahl eingespielter Datensätze pro Tabelle

Auch sehr grosse Backup-Dateien können problemlos importiert werden, ohne den Server zu überlasten.

### 3.3 Geschützte System-Objekte

Beim Import werden drei kritische Objekte **nie gelöscht oder überschrieben**, unabhängig vom Import-Modus:
- Root-Mandat
- Admin-Benutzer
- Event-Benutzer

Falls diese Objekte im Backup andere interne Kennungen hatten als in der Zielumgebung, passt das System alle betroffenen Verknüpfungen **automatisch** an. Das verhindert inkonsistente Daten nach dem Import.

### 3.4 Import via Script

```bash
ssh ubuntu@api.poweron.swiss
cd /srv/gateway/current
source .venv/bin/activate
sudo systemctl stop gateway

# Import-Script (Pendant zum Export-Script)
# Datei übergeben, Modus wählen
python scripts/script_db_export_migration.py --help  # zeigt alle Optionen

sudo systemctl start gateway
```

---

## 4. Backups & Datensicherung

### 4.1 Backup-Strategie

Die Plattform verfügt über ein durchdachtes, mehrschichtiges Sicherungskonzept:

**Infrastruktur-Ebene:** Der Datenbankserver läuft auf der Infomaniak Public Cloud, die Snapshot-Funktionalitäten für Managed Databases bereitstellt.

**Anwendungs-Ebene:** Über die integrierte Admin-UI kann jederzeit ein vollständiger Export aller Datenbanken erstellt werden — on-demand, gezielt pro Datenbank oder als Gesamtexport. Die Backup-Dateien sind vollständig portabel und können auf jedem Speicher archiviert werden.

### 4.2 Empfohlene Backup-Praxis

| Zeitpunkt | Aktion |
|---|---|
| Vor jedem Deployment | Export via Admin-UI, Datei lokal speichern |
| Vor Datenbank-Migrationen | Export erstellen und beschriftet archivieren |
| Wöchentlich | Export als Archiv-Backup ablegen |

---

## 5. Datenbankmigrationen (Struktur-Änderungen)

Wenn sich das Datenmodell weiterentwickelt — z. B. durch neue Felder oder Tabellen — stellt die Plattform dedizierte Hilfsprogramme bereit, die Datenbankstruktur kontrolliert und sicher anzupassen:

| Programm | Zweck |
|---|---|
| `script_db_adapt_to_models.py` | Passt die Datenbankstruktur automatisch an den aktuellen Code an (mit Vorschau-Modus ohne Änderungen) |
| `script_db_audit_legacy_state.py` | Analysiert den Datenbankzustand vor einem Bereinigungsschritt |
| `script_db_migrate_*.py` | Datenmigrations-Programme für spezifische Features |
| `script_db_init_automation2.py` | Erstellt die Datenbankstruktur für das Automation-Feature |
| `script_db_init_chatbot.py` | Erstellt die Datenbankstruktur für das Chatbot-Feature |

Beim Start der Anwendung prüft die Plattform ausserdem automatisch, ob alle benötigten Tabellen vorhanden sind, und legt fehlende selbstständig an.

---

## 6. Datenschutz-Hinweise

- Export-Dateien enthalten **alle Kundendaten** (Mandate, Benutzer, Chats, Dokumente, etc.) und sind entsprechend zu behandeln
- Dateien dürfen **nicht auf unsicheren Speichern** (persönliche Dropbox, E-Mail, etc.) abgelegt werden
- Export-Dateien sollten nach Nutzung gelöscht werden wenn sie nicht mehr benötigt werden
- Der Zugriff auf Export/Import ist auf SysAdmins beschränkt und wird serverseitig geloggt

---

## Zusammenfassung: Datenbankoperationen im Überblick

| Aufgabe | Wie |
|---|---|
| Fehlende Tabellen beim Start anlegen | Automatisch beim Plattform-Start |
| Datenbank-Export / Backup | Admin-UI (ein Klick) oder Entwickler-Script |
| Datenbank-Import / Wiederherstellung | Admin-UI mit geführtem Prozess oder Entwickler-Script |
| Infrastruktur-Snapshots | Infomaniak Cloud (Serverebene) |
| Struktur-Anpassungen bei Updates | Kontrolliert durch Entwickler-Hilfsprogramme |
| Datenbankpflege & Bereinigung | Admin-UI |