Initial commit
This commit is contained in:
s4luorth
388
skrift-configurator/BACKEND_INTEGRATION.md
Normal file
388
skrift-configurator/BACKEND_INTEGRATION.md
Normal file
@@ -0,0 +1,388 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user