Skrift-Kofnigurator/skrift-configurator/BACKEND_INTEGRATION.md

# Backend Integration - WordPress Plugin

Anleitung zur Integration des Node.js Backends mit dem WordPress Konfigurator-Plugin.

## Überblick

Das WordPress Plugin kommuniziert mit dem Node.js Backend über eine REST API. Das Backend generiert die handgeschriebenen SVG-Dateien und speichert die finalen Bestellungen.

## WordPress Admin-Einstellungen

Nach der Installation des Plugins in WordPress:

1. Gehe zu **Einstellungen → Skrift Konfigurator**
2. Scrolle nach unten zum Abschnitt **"Backend-Verbindung"**

### Erforderliche Einstellungen

#### 1. API URL / Domain
**Beispiel:** `https://backend.deine-domain.de`

Die vollständige URL zu deinem Backend-Server (ohne trailing slash).

- ✅ `https://backend.example.com`
- ✅ `http://localhost:4000` (nur für lokale Tests)
- ❌ `https://backend.example.com/` (kein Slash am Ende!)

#### 2. API Token / Authentifizierung
**Optional** - Aktuell nicht implementiert, für zukünftige Erweiterungen vorbereitet.

Lasse dieses Feld erstmal leer.

#### 3. Order Webhook URL
**Beispiel:** `https://n8n.deine-domain.de/webhook/order`

URL die aufgerufen wird, nachdem eine Bestellung abgeschickt wurde.

**Wird aufgerufen:**
- **Business-Kunden:** Sofort nach Klick auf "Jetzt kostenpflichtig bestellen"
- **Privat-Kunden:** Nach erfolgreicher PayPal-Zahlung (später implementiert)

**Webhook-Payload:**
```json
{
  "orderNumber": "SK-2026-01-03-001",
  "customer_type": "business",
  "product": "businessbriefe",
  "quantity": 100,
  "format": "A4",
  "shipping_mode": "direct",
  "envelope": "yes",
  "customer_data": {
    "firstName": "Max",
    "lastName": "Mustermann",
    "company": "Beispiel GmbH",
    "email": "max@example.com",
    ...
  },
  "quote": {
    "total": 250.00,
    ...
  },
  "backend_result": {
    "path": "/var/skrift-output/SK-2026-01-03-001",
    "files": [...],
    "summary": {...}
  },
  "timestamp": "2026-01-03T..."
}
```

**Verwendung:**
- N8N Workflow triggern
- CRM-System benachrichtigen
- Interne Benachrichtigungen versenden

#### 4. Redirect URL Geschäftskunden
**Beispiel:** `https://deine-domain.de/danke-business`

Wohin Business-Kunden nach dem Klick auf "Jetzt kostenpflichtig bestellen" weitergeleitet werden.

**Query-Parameter:**
- `orderNumber` - Die generierte Bestellnummer

**Beispiel-Redirect:**
```
https://deine-domain.de/danke-business?orderNumber=SK-2026-01-03-001
```

#### 5. Redirect URL Privatkunden
**Beispiel:** `https://deine-domain.de/danke-privat`

Wohin Privat-Kunden nach erfolgreicher PayPal-Zahlung weitergeleitet werden.

**Query-Parameter:**
- `orderNumber` - Die generierte Bestellnummer

## Backend-API Endpunkte

Das Plugin nutzt folgende Backend-Endpunkte:

### 1. Health Check
```
GET /health
```

**Response:**
```json
{
  "status": "ok",
  "timestamp": "2026-01-03T..."
}
```

### 2. Preview Batch
```
POST /api/preview/batch
```

**Request:**
```json
{
  "sessionId": "session-1234567890-abc",
  "letters": [
    {
      "text": "Liebe Oma, ...",
      "font": "tilda",
      "format": "A4",
      "placeholders": {},
      "envelope": null
    }
  ]
}
```

**Response:**
```json
{
  "sessionId": "session-1234567890-abc",
  "previews": [
    {
      "index": 0,
      "url": "/api/preview/session-1234567890-abc/0"
    }
  ],
  "batchInfo": {
    "totalLetters": 1,
    "batchSize": 30
  }
}
```

### 3. Generate Order
```
POST /api/order/generate
```

**Request:**
```json
{
  "orderNumber": "SK-2026-01-03-001",
  "letters": [...],
  "envelopes": [...],
  "metadata": {
    "customer": {...},
    "orderDate": "2026-01-03T..."
  }
}
```

**Response:**
```json
{
  "orderNumber": "SK-2026-01-03-001",
  "path": "/var/skrift-output/SK-2026-01-03-001",
  "files": [
    "letter_000.svg",
    "envelope_000.svg",
    "order-metadata.json",
    "placeholders.csv"
  ],
  "summary": {
    "totalLetters": 100,
    "totalEnvelopes": 100,
    "fonts": ["tilda"],
    "formats": ["A4"]
  }
}
```

## Workflow

### Für Business-Kunden

```
1. Kunde füllt Konfigurator aus
2. Kunde klickt "Jetzt kostenpflichtig bestellen"
3. WordPress Plugin → Backend API (generateOrder)
4. Backend generiert SVG-Dateien
5. Backend speichert in /var/skrift-output/SK-...
6. WordPress Plugin → Webhook aufrufen
7. WordPress Plugin → Redirect zu Business-Danke-Seite
```

### Für Privat-Kunden (später)

```
1. Kunde füllt Konfigurator aus
2. Kunde klickt "Jetzt kostenpflichtig bestellen"
3. WordPress Plugin → PayPal Checkout
4. PayPal → Zahlung erfolgreich
5. PayPal Webhook → WordPress
6. WordPress Plugin → Backend API (generateOrder)
7. Backend generiert SVG-Dateien
8. WordPress Plugin → Webhook aufrufen
9. WordPress Plugin → Redirect zu Privat-Danke-Seite
```

## Datenmapping

### Fonts

| Frontend | Backend |
|----------|---------|
| tilda    | tilda (PremiumUltra79) |
| alva     | alva (PremiumUltra23) |
| ellie    | ellie (PremiumUltra39) |

### Formate

| Frontend | Backend |
|----------|---------|
| a4       | A4 |
| a6p      | A6_PORTRAIT |
| a6l      | A6_LANDSCAPE |

### Envelope-Formate

| Brief-Format | Envelope-Format |
|--------------|-----------------|
| A4           | DIN_LANG |
| A6           | C6 |

## JavaScript Integration

### API Client laden

Das Plugin lädt automatisch:
- `configurator-api.js` - Backend API Client
- `configurator-backend-integration.js` - Integration Logic

### Globale Instanz

```javascript
// Verfügbar in allen Konfigurator-Scripts
const api = window.SkriftBackendAPI;

// Health-Check
const isHealthy = await api.healthCheck();

// Preview generieren
const result = await api.generatePreviewBatch(letters);

// Order generieren
const order = await api.generateOrder(orderNumber, letters, envelopes, metadata);
```

## Testing

### 1. Backend Health-Check

```javascript
// In Browser-Console auf Konfigurator-Seite:
const api = window.SkriftBackendAPI;
const healthy = await api.healthCheck();
console.log('Backend healthy:', healthy);
```

### 2. Test-Order generieren

```javascript
const api = window.SkriftBackendAPI;

const result = await api.generateOrder(
  api.generateOrderNumber(),
  [
    {
      text: 'Test Brief',
      font: 'tilda',
      format: 'A4',
      placeholders: {}
    }
  ],
  [],
  {
    customer: {
      type: 'business',
      firstName: 'Test',
      lastName: 'User',
      email: 'test@example.com'
    }
  }
);

console.log('Order result:', result);
```

## Troubleshooting

### Fehler: "Backend ist nicht erreichbar"

**Lösung:**
1. Prüfe Backend-URL in WordPress-Einstellungen
2. Teste Health-Check: `curl https://backend.deine-domain.de/health`
3. Prüfe Nginx Proxy Manager Konfiguration
4. Prüfe Backend-Container: `docker compose logs -f`

### Fehler: "CORS Error"

**Lösung:**
Nginx Proxy Manager muss CORS-Header setzen:

```nginx
# In Custom Nginx Configuration (Advanced Tab)
add_header Access-Control-Allow-Origin "https://deine-wordpress-domain.de" always;
add_header Access-Control-Allow-Methods "GET, POST, OPTIONS" always;
add_header Access-Control-Allow-Headers "Content-Type, Authorization" always;

if ($request_method = 'OPTIONS') {
    return 204;
}
```

### Fehler: "Order generation failed"

**Lösung:**
1. Prüfe Backend-Logs: `docker compose logs -f`
2. Prüfe `/var/skrift-output` Verzeichnis existiert
3. Prüfe Fonts sind vorhanden in `/app/fonts`
4. Prüfe `.env` hat `SCRIPTALIZER_ERR_FREQUENCY=0`

### Webhook wird nicht aufgerufen

**Lösung:**
1. Prüfe Webhook-URL in WordPress-Einstellungen
2. Teste Webhook manuell mit curl
3. Prüfe N8N/Webhook-Service Logs
4. Webhook-Fehler werden ignoriert (soft fail) - Order wird trotzdem erstellt

## Weitere Entwicklung

### Preview-System (TODO)

Aktuell wird direkt die finale Order generiert. Zukünftig:
1. Kunde füllt Schritt 1-4 aus
2. Preview generieren mit `/api/preview/batch`
3. Kunde sieht Vorschau der Briefe
4. Kunde bestätigt → Order finalisieren mit `/api/order/finalize`

### PayPal-Integration (TODO)

Für Privatkunden:
1. PayPal SDK laden
2. Order-ID an PayPal übergeben
3. Nach Zahlung Webhook empfangen
4. Backend-Order generieren
5. Weiterleitung

## Support

Bei Problemen:
1. Browser-Console öffnen (F12)
2. Logs prüfen (nach `[API]` oder `[Backend Integration]` filtern)
3. Backend-Logs prüfen: `docker compose logs -f`
4. WordPress Debug-Log prüfen: `wp-content/debug.log`

## Checkliste nach Installation

- [ ] Backend deployed und erreichbar
- [ ] Health-Check erfolgreich: `https://backend.domain.de/health`
- [ ] WordPress Admin-Einstellungen konfiguriert
  - [ ] API URL gesetzt
  - [ ] Order Webhook URL gesetzt (optional)
  - [ ] Redirect URLs gesetzt
- [ ] Test-Bestellung generiert
- [ ] Dateien in `/var/skrift-output` erstellt
- [ ] Webhook wurde aufgerufen (falls konfiguriert)
- [ ] Keine durchgestrichenen Wörter in SVGs
- [ ] Handschrift-Variationen sichtbar (Wortabstände, Rotation)