customer-installer/REGISTRATION_SETUP_GUIDE.md

# 🚀 BotKonzept - Registrierungs-Setup Guide

## 📋 Übersicht

Dieser Guide erklärt, wie Sie die Benutzerregistrierung für BotKonzept zum Laufen bringen.

---

## ✅ Was bereits vorhanden ist

### 1. Frontend (customer-frontend)
- ✅ Registrierungsformular (`index.html`)
- ✅ Formular-Validierung (`js/main.js`)
- ✅ Webhook-URL: `https://n8n.userman.de/webhook/botkonzept-registration`

### 2. Backend (customer-installer)
- ✅ `install.sh` - Erstellt LXC-Container automatisch
- ✅ `setup_nginx_proxy.sh` - Konfiguriert Reverse Proxy
- ✅ Datenbank-Schema (`sql/botkonzept_schema.sql`)

### 3. n8n Workflows
- ✅ `BotKonzept-Customer-Registration-Workflow.json`
- ✅ `BotKonzept-Trial-Management-Workflow.json`

---

## 🔧 Setup-Schritte

### Schritt 1: Datenbank einrichten

```bash
# Auf Ihrem Supabase/PostgreSQL Server
psql -U postgres -d botkonzept < customer-installer/sql/botkonzept_schema.sql
```

**Oder in Supabase Dashboard:**
1. Gehen Sie zu SQL Editor
2. Kopieren Sie den Inhalt von `sql/botkonzept_schema.sql`
3. Führen Sie das SQL aus

**Tabellen die erstellt werden:**
- `customers` - Kundendaten
- `instances` - LXC-Instanzen
- `emails_sent` - E-Mail-Tracking
- `subscriptions` - Abonnements
- `payments` - Zahlungen
- `usage_stats` - Nutzungsstatistiken
- `audit_log` - Audit-Trail

---

### Schritt 2: n8n Credentials einrichten

Sie benötigen folgende Credentials in n8n:

#### 2.1 PostgreSQL/Supabase Credential
**Name:** `Supabase Local`
**Typ:** Postgres
**Konfiguration:**
```
Host: localhost (oder Ihr Supabase Host)
Port: 5432
Database: botkonzept
User: postgres (oder service_role)
Password: [Ihr Passwort]
SSL: Enabled (für Supabase)
```

#### 2.2 SSH Credential für PVE20
**Name:** `PVE20`
**Typ:** SSH (Private Key)
**Konfiguration:**
```
Host: 192.168.45.20 (oder Ihre PVE20 IP)
Port: 22
Username: root
Private Key: [Ihr SSH Private Key]
```

**SSH Key generieren (falls noch nicht vorhanden):**
```bash
# Auf dem n8n Server
ssh-keygen -t ed25519 -C "n8n@botkonzept"

# Public Key auf PVE20 kopieren
ssh-copy-id root@192.168.45.20
```

#### 2.3 SMTP Credential für E-Mails
**Name:** `Postfix SES`
**Typ:** SMTP
**Konfiguration:**

**Option A: Amazon SES**
```
Host: email-smtp.eu-central-1.amazonaws.com
Port: 587
User: [Ihr SMTP Username]
Password: [Ihr SMTP Password]
From Email: noreply@botkonzept.de
```

**Option B: Postfix (lokal)**
```
Host: localhost
Port: 25
From Email: noreply@botkonzept.de
```

**Option C: Gmail (für Tests)**
```
Host: smtp.gmail.com
Port: 587
User: your-email@gmail.com
Password: [App-spezifisches Passwort]
From Email: your-email@gmail.com
```

---

### Schritt 3: n8n Workflows importieren

#### 3.1 Customer Registration Workflow

1. Öffnen Sie n8n: `https://n8n.userman.de`
2. Klicken Sie auf **"+"** → **"Import from File"**
3. Wählen Sie `BotKonzept-Customer-Registration-Workflow.json`
4. **Wichtig:** Passen Sie folgende Nodes an:

**Node: "Create Customer in DB"**
- Credential: `Supabase Local` auswählen
- Query anpassen falls nötig

**Node: "Create Customer Instance"**
- Credential: `PVE20` auswählen
- Command prüfen:
```bash
/root/customer-installer/install.sh \
  --storage local-zfs \
  --bridge vmbr0 \
  --ip dhcp \
  --vlan 90 \
  --apt-proxy http://192.168.45.2:3142 \
  --n8n-owner-email {{ $json.email }} \
  --n8n-owner-pass "{{ $('Generate Password & Trial Date').item.json.password }}"
```

**Node: "Send Welcome Email"**
- Credential: `Postfix SES` auswählen
- From Email anpassen: `noreply@botkonzept.de`

5. Klicken Sie auf **"Save"**
6. Klicken Sie auf **"Activate"** (oben rechts)

#### 3.2 Trial Management Workflow

1. Importieren Sie `BotKonzept-Trial-Management-Workflow.json`
2. Passen Sie die Credentials an
3. Aktivieren Sie den Workflow

---

### Schritt 4: Webhook-URL testen

#### 4.1 Webhook-URL ermitteln

Nach dem Import sollte die Webhook-URL sein:
```
https://n8n.userman.de/webhook/botkonzept-registration
```

**Prüfen Sie die URL:**
1. Öffnen Sie den Workflow
2. Klicken Sie auf den Node "Registration Webhook"
3. Kopieren Sie die "Production URL"

#### 4.2 Test mit curl

```bash
curl -X POST https://n8n.userman.de/webhook/botkonzept-registration \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Max",
    "lastName": "Mustermann",
    "email": "test@example.com",
    "company": "Test GmbH",
    "website": "https://example.com",
    "newsletter": true
  }'
```

**Erwartete Antwort:**
```json
{
  "success": true,
  "message": "Registrierung erfolgreich! Sie erhalten in Kürze eine E-Mail mit Ihren Zugangsdaten.",
  "customerId": "uuid-hier",
  "instanceUrl": "https://sb-XXXXX.userman.de"
}
```

---

## 🐛 Häufige Probleme & Lösungen

### Problem 1: "Credential not found"

**Lösung:**
- Stellen Sie sicher, dass alle Credentials in n8n angelegt sind
- Namen müssen exakt übereinstimmen: `Supabase Local`, `PVE20`, `Postfix SES`

### Problem 2: SSH-Verbindung schlägt fehl

**Lösung:**
```bash
# Auf n8n Server
ssh root@192.168.45.20

# Falls Fehler:
# 1. SSH Key generieren
ssh-keygen -t ed25519 -C "n8n@botkonzept"

# 2. Public Key kopieren
ssh-copy-id root@192.168.45.20

# 3. Testen
ssh root@192.168.45.20 "ls /root/customer-installer/"
```

### Problem 3: install.sh nicht gefunden

**Lösung:**
```bash
# Auf PVE20
cd /root
git clone https://backoffice.userman.de/MediaMetz/customer-installer.git

# Oder Pfad im Workflow anpassen
```

### Problem 4: Datenbank-Fehler

**Lösung:**
```bash
# Prüfen ob Tabellen existieren
psql -U postgres -d botkonzept -c "\dt"

# Falls nicht, Schema erneut ausführen
psql -U postgres -d botkonzept < sql/botkonzept_schema.sql
```

### Problem 5: E-Mail wird nicht versendet

**Lösung:**

**Für Amazon SES:**
1. Verifizieren Sie die Absender-E-Mail in AWS SES
2. Prüfen Sie SMTP-Credentials
3. Stellen Sie sicher, dass Sie aus dem Sandbox-Modus raus sind

**Für Postfix:**
```bash
# Auf dem Server
systemctl status postfix
journalctl -u postfix -f

# Test-E-Mail senden
echo "Test" | mail -s "Test" test@example.com
```

### Problem 6: Workflow wird nicht ausgeführt

**Lösung:**
1. Prüfen Sie ob Workflow aktiviert ist (grüner Toggle oben rechts)
2. Schauen Sie in die Execution History (linke Sidebar → Executions)
3. Prüfen Sie die Logs jedes Nodes

---

## 📊 Workflow-Ablauf im Detail

### Registration Workflow

```
1. Webhook empfängt POST-Request
   ↓
2. Validierung (E-Mail, Name, etc.)
   ↓
3. Passwort generieren (16 Zeichen)
   ↓
4. Kunde in DB anlegen (customers Tabelle)
   ↓
5. SSH zu PVE20 → install.sh ausführen
   ↓
6. JSON-Output parsen (CTID, URLs, Credentials)
   ↓
7. Instanz in DB speichern (instances Tabelle)
   ↓
8. Willkommens-E-Mail senden
   ↓
9. E-Mail-Versand loggen (emails_sent Tabelle)
   ↓
10. Success-Response an Frontend
```

**Dauer:** Ca. 2-5 Minuten (abhängig von LXC-Erstellung)

### Trial Management Workflow

```
1. Cron-Trigger (täglich 9:00 Uhr)
   ↓
2. Alle Trial-Kunden abrufen (0-8 Tage alt)
   ↓
3. Für jeden Kunden:
   - Tag 3? → 30% Rabatt-E-Mail
   - Tag 5? → 15% Rabatt-E-Mail
   - Tag 7? → Letzte Chance-E-Mail
   - Tag 8? → Instanz löschen + Goodbye-E-Mail
   ↓
4. E-Mail-Versand loggen
```

---

## 🧪 Testing-Checkliste

### Frontend-Test
- [ ] Formular öffnen: `http://192.168.0.20:8000`
- [ ] Alle Felder ausfüllen
- [ ] Absenden klicken
- [ ] Erfolgsmeldung erscheint

### Backend-Test
- [ ] n8n Execution History prüfen
- [ ] Datenbank prüfen: `SELECT * FROM customers ORDER BY created_at DESC LIMIT 1;`
- [ ] PVE20 prüfen: `pct list | grep sb-`
- [ ] E-Mail erhalten?

### End-to-End-Test
- [ ] Registrierung durchführen
- [ ] E-Mail mit Zugangsdaten erhalten
- [ ] In n8n Dashboard einloggen
- [ ] PDF hochladen
- [ ] Chatbot testen

---

## 📈 Monitoring

### n8n Executions überwachen

```bash
# In n8n UI
Sidebar → Executions → Filter: "Failed"
```

### Datenbank-Queries

```sql
-- Neue Registrierungen heute
SELECT COUNT(*) FROM customers WHERE DATE(created_at) = CURRENT_DATE;

-- Aktive Trials
SELECT COUNT(*) FROM customers WHERE status = 'trial';

-- Versendete E-Mails heute
SELECT email_type, COUNT(*) 
FROM emails_sent 
WHERE DATE(sent_at) = CURRENT_DATE 
GROUP BY email_type;

-- Trials die bald ablaufen
SELECT * FROM trials_expiring_soon;
```

### Logs prüfen

```bash
# n8n Logs
docker logs -f n8n

# install.sh Logs
ls -lh /root/customer-installer/logs/

# Postfix Logs
journalctl -u postfix -f
```

---

## 🔐 Sicherheit

### Wichtige Punkte

1. **Credentials verschlüsseln**
   - n8n verschlüsselt Credentials automatisch
   - Encryption Key sichern: `N8N_ENCRYPTION_KEY`

2. **SSH Keys schützen**
   ```bash
   chmod 600 ~/.ssh/id_ed25519
   ```

3. **Datenbank-Zugriff**
   - Verwenden Sie `service_role` Key für n8n
   - Niemals `anon` Key für Backend-Operationen

4. **E-Mail-Sicherheit**
   - SPF, DKIM, DMARC konfigurieren
   - Absender-Domain verifizieren

---

## 📚 Weitere Ressourcen

- **n8n Dokumentation:** https://docs.n8n.io
- **Supabase Docs:** https://supabase.com/docs
- **Proxmox Docs:** https://pve.proxmox.com/wiki/Main_Page

---

## 🆘 Support

Bei Problemen:

1. **Logs prüfen** (siehe Monitoring-Sektion)
2. **n8n Execution History** ansehen
3. **Datenbank-Queries** ausführen
4. **Workflow Schritt für Schritt testen**

**Kontakt:**
- E-Mail: support@botkonzept.de
- Dokumentation: Dieses Dokument

---

**Version:** 1.0.0  
**Letzte Aktualisierung:** 26.01.2025  
**Autor:** MediaMetz