# Frontend Migration Guide - API Umstrukturierung

**Datum:** 16. November 2025  
**Betrifft:** ALLE API-Aufrufe im Frontend  
**Status:** ⚠️ Aktion erforderlich - ALLE Routen prüfen!

---

## � BREAKING CHANGE: Konsistente `/api` Prefixes

**ALLE API-Routen haben sich geändert!**

### Vorher (inkonsistent):
```javascript
// Teils mit /api
fetch('/api/upload/batch')
fetch('/api/manage/xyz')

// Teils OHNE /api - FALSCH!
fetch('/groups/123')
fetch('/groups/123/approve')
fetch('/moderation/groups/123')
```

### Jetzt (konsistent):
```javascript
// ALLE Routen mit /api Prefix
fetch('/api/upload/batch')
fetch('/api/manage/xyz')
fetch('/api/groups/123')              // Public
fetch('/api/admin/groups/123/approve') // Admin
fetch('/api/admin/groups/123')        // Admin
```

---

## 🔒 Admin API Authentication

Alle Admin-Endpoints (`/api/admin/*` und `/api/system/*`) benötigen jetzt **Bearer Token Authentication**.

### Route-Hierarchie

1. **Public API**: `/api/*` 
   - Öffentlich zugänglich
   - `/api/upload`, `/api/groups`, `/api/download`, etc.

2. **Management API**: `/api/manage/*`
   - Token-basiert (UUID aus Upload-Response)
   - Für Gruppenbesitzer

3. **Admin API**: `/api/admin/*` ⚠️ **BEARER TOKEN ERFORDERLICH**
   - Moderation, Logs, Consents
   - `/api/admin/groups`, `/api/admin/deletion-log`, etc.

4. **System API**: `/api/system/migration/*` ⚠️ **BEARER TOKEN ERFORDERLICH**
   - Wartungsfunktionen

### Betroffene Admin-Endpoints

- `/api/admin/groups` - Gruppen auflisten
- `/api/admin/groups/:id` - Gruppe abrufen
- `/api/admin/groups/:id/approve` - Gruppe genehmigen
- `/api/admin/groups/:id` - Gruppe löschen
- `/api/admin/groups/:id/images/:imageId` - Bild löschen
- `/api/admin/groups/by-consent` - Nach Consent filtern
- `/api/admin/consents/export` - Consent-Export
- `/api/admin/social-media/platforms` - Plattformen auflisten
- `/api/admin/reorder/:groupId/images` - Bilder neu anordnen
- `/api/admin/deletion-log` - Deletion Log
- `/api/admin/cleanup/*` - Cleanup-Funktionen
- `/api/admin/rate-limiter/stats` - Rate-Limiter-Statistiken
- `/api/admin/management-audit` - Audit-Log

**System-Endpoints:**
- `/api/system/migration/migrate` - Migration ausführen
- `/api/system/migration/rollback` - Migration zurückrollen

---

## 📝 Erforderliche Änderungen

### 1. ALLE API-Routen prüfen und `/api` hinzufügen

**Schritt 1**: Finde alle API-Aufrufe im Frontend:

```bash
# Alle fetch/axios Aufrufe finden
grep -r "fetch\(" frontend/src/
grep -r "axios\." frontend/src/
```

**Schritt 2**: Prüfe jede Route und füge `/api` Prefix hinzu (falls fehlend):

```javascript
// ❌ FALSCH (alte Routen)
fetch('/groups/123')
fetch('/groups/123/approve')
fetch('/moderation/groups/123')

// ✅ RICHTIG (neue Routen)
fetch('/api/groups/123')                    // Public
fetch('/api/admin/groups/123/approve')      // Admin (+ Bearer Token!)
fetch('/api/admin/groups/123')              // Admin (+ Bearer Token!)
```

### 2. Environment Variable für Admin Token hinzufügen

```bash
# frontend/.env oder frontend/.env.local
REACT_APP_ADMIN_API_KEY=your-secure-admin-token-here
```

**Token generieren:**
```bash
# Linux/Mac:
openssl rand -hex 32

# Node.js:
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

**⚠️ Wichtig**: Gleiches Token in Backend `.env` als `ADMIN_API_KEY` eintragen!

### 3. API-Aufrufe für Admin-Endpoints anpassen

#### Vorher (ohne Auth):
```javascript
const response = await fetch('/api/admin/groups');
```

#### Nachher (mit Bearer Token):
```javascript
const response = await fetch('/api/admin/groups', {
  headers: {
    'Authorization': `Bearer ${process.env.REACT_APP_ADMIN_API_KEY}`,
    'Content-Type': 'application/json'
  }
});
```

### 3. Zentrale API-Helper-Funktion erstellen

**Empfohlen**: Erstelle eine zentrale Funktion für alle Admin-API-Calls:

```javascript
// src/services/adminApiService.js
const ADMIN_API_KEY = process.env.REACT_APP_ADMIN_API_KEY;

export const adminFetch = async (url, options = {}) => {
  const defaultHeaders = {
    'Authorization': `Bearer ${ADMIN_API_KEY}`,
    'Content-Type': 'application/json'
  };

  const response = await fetch(url, {
    ...options,
    headers: {
      ...defaultHeaders,
      ...options.headers
    }
  });

  if (response.status === 403) {
    throw new Error('Authentication failed - Invalid or missing admin token');
  }

  return response;
};

// Verwendung:
import { adminFetch } from './services/adminApiService';

const response = await adminFetch('/api/admin/groups');
const data = await response.json();
```

### 4. Error Handling erweitern

```javascript
try {
  const response = await adminFetch('/api/admin/groups');
  
  if (response.status === 403) {
    // Auth fehlt oder ungültig
    console.error('Admin authentication required');
    // Redirect zu Login oder Fehlermeldung anzeigen
  }
  
  if (response.status === 429) {
    // Rate Limit überschritten
    console.error('Too many requests');
  }
  
  const data = await response.json();
  // ...
} catch (error) {
  console.error('Admin API error:', error);
}
```

---

## 🔍 Betroffene Dateien finden

### Alle API-Calls prüfen (KRITISCH!)

```bash
cd frontend/src

# ALLE API-Calls finden (fetch + axios):
grep -rn "fetch(" --include="*.js" --include="*.jsx"
grep -rn "axios\." --include="*.js" --include="*.jsx"

# Spezifisch nach alten Routen OHNE /api suchen:
grep -rn "fetch('/groups" --include="*.js"
grep -rn "fetch('/moderation" --include="*.js"

# Admin-API-Calls finden:
grep -rn "/api/admin" --include="*.js" --include="*.jsx"
```

**Bekannte betroffene Dateien:**

### Routen ohne `/api` Prefix (MÜSSEN GEFIXT WERDEN):
- `Components/Pages/ModerationGroupsPage.js`
  - ❌ `/groups/${groupId}/approve` → ✅ `/api/admin/groups/${groupId}/approve`
  - ❌ `/groups/${groupId}` (DELETE) → ✅ `/api/admin/groups/${groupId}`
  - ❌ `/api/social-media/platforms` → ✅ `/api/admin/social-media/platforms`

- `Components/Pages/ModerationGroupImagesPage.js`
  - ❌ `/moderation/groups/${groupId}` → ✅ `/api/admin/groups/${groupId}`

- `Components/Pages/PublicGroupImagesPage.js`
  - ❌ `/groups/${groupId}` → ✅ `/api/groups/${groupId}`

### Admin-Endpoints (benötigen Bearer Token):
- `Components/Pages/ModerationGroupsPage.js` - Alle Admin-Calls
- `Components/Pages/ModerationGroupImagesPage.js` - Gruppe laden + Bilder löschen
- `Components/ComponentUtils/DeletionLogSection.js` - Deletion Log
- `Components/ComponentUtils/ConsentManager.js` - Consent Export (wenn Admin)
- `services/reorderService.js` - Admin-Reorder (wenn vorhanden)

### Public/Management Endpoints (nur Pfad prüfen):
- `Utils/batchUpload.js` - Bereits korrekt (`/api/...`)
- `Components/Pages/ManagementPortalPage.js` - Bereits korrekt (`/api/manage/...`)
- `Utils/sendRequest.js` - Bereits korrekt (axios)

---

## ✅ Checkliste

### Phase 1: Route-Prefixes (ALLE Dateien)
- [ ] Alle `fetch()` und `axios` Calls gefunden (grep)
- [ ] Alle Routen ohne `/api` Prefix identifiziert
- [ ] `/api` Prefix zu Public-Routen hinzugefügt (`/api/groups`, `/api/upload`)
- [ ] Admin-Routen auf `/api/admin/*` geändert
- [ ] Management-Routen auf `/api/manage/*` geprüft (sollten schon korrekt sein)

### Phase 2: Admin Authentication
- [ ] `REACT_APP_ADMIN_API_KEY` in `.env` hinzugefügt
- [ ] Token im Backend als `ADMIN_API_KEY` konfiguriert
- [ ] Zentrale `adminFetch` Funktion erstellt
- [ ] Authorization Header zu ALLEN `/api/admin/*` Calls hinzugefügt
- [ ] Authorization Header zu `/api/system/*` Calls hinzugefügt (falls vorhanden)
- [ ] 403 Error Handling implementiert

### Phase 3: Testing & Deployment
- [ ] Frontend lokal getestet (alle Routen)
- [ ] Admin-Funktionen getestet (Approve, Delete, etc.)
- [ ] Public-Routen getestet (Gruppe laden, Upload)
- [ ] Production `.env` aktualisiert

---

## 🧪 Testing

### Lokales Testing

1. Backend mit Admin-Key starten:
   ```bash
   cd backend
   echo "ADMIN_API_KEY=test-key-12345" >> .env
   npm run dev
   ```

2. Frontend mit Admin-Key starten:
   ```bash
   cd frontend
   echo "REACT_APP_ADMIN_API_KEY=test-key-12345" >> .env.local
   npm start
   ```

3. Moderation-Seite öffnen und Admin-Funktionen testen

### Test-Fälle

- ✅ Admin-Funktionen funktionieren mit gültigem Token
- ✅ 403 Error bei fehlendem/falschem Token
- ✅ Consent-Export funktioniert
- ✅ Gruppen löschen funktioniert
- ✅ Bilder neu anordnen funktioniert

---

## 📚 Weitere Dokumentation

- **Backend Auth-Doku**: `AUTHENTICATION.md`
- **API Route-Übersicht**: `backend/src/routes/README.md`
- **Route-Konfiguration**: `backend/src/routes/routeMappings.js`
- **OpenAPI Spec**: `backend/docs/openapi.json`
- **Swagger UI**: http://localhost:5001/api/docs (dev only)

---

## 🆘 Troubleshooting

### Problem: "403 Forbidden" Fehler

**Ursachen:**
1. `REACT_APP_ADMIN_API_KEY` nicht gesetzt
2. Token falsch konfiguriert (Frontend ≠ Backend)
3. Token enthält Leerzeichen/Zeilenumbrüche

**Lösung:**
```bash
# Frontend .env prüfen:
cat frontend/.env | grep ADMIN_API_KEY

# Backend .env prüfen:
cat backend/.env | grep ADMIN_API_KEY

# Beide müssen identisch sein!
```

### Problem: "ADMIN_API_KEY not configured" (500 Error)

**Ursache:** Backend hat `ADMIN_API_KEY` nicht in `.env`

**Lösung:**
```bash
cd backend
echo "ADMIN_API_KEY=$(openssl rand -hex 32)" >> .env
```

### Problem: Token wird nicht gesendet

**Prüfen in Browser DevTools:**
1. Network Tab öffnen
2. Admin-API-Request auswählen
3. "Headers" Tab prüfen
4. Sollte enthalten: `Authorization: Bearer <token>`

### Problem: CORS-Fehler

**Ursache:** Backend CORS-Middleware blockiert Authorization-Header

**Lösung:** Bereits implementiert in `backend/src/middlewares/cors.js`:
```javascript
allowedHeaders: ['Content-Type', 'Authorization']
```

---

## 🚀 Deployment

### Production Checklist

- [ ] Sicheren Admin-Token generiert (min. 32 Bytes hex)
- [ ] Token in Backend `.env` als `ADMIN_API_KEY`
- [ ] Token in Frontend Build-Environment als `REACT_APP_ADMIN_API_KEY`
- [ ] Token NICHT in Git committed (in `.gitignore`)
- [ ] HTTPS verwendet (Token über unverschlüsselte HTTP ist unsicher)
- [ ] Token-Rotation-Prozess dokumentiert
- [ ] Backup des Tokens an sicherem Ort gespeichert

### Docker Deployment

```yaml
# docker-compose.yml
services:
  backend:
    environment:
      - ADMIN_API_KEY=${ADMIN_API_KEY}
  
  frontend:
    environment:
      - REACT_APP_ADMIN_API_KEY=${ADMIN_API_KEY}
```

```bash
# .env (nicht in Git!)
ADMIN_API_KEY=your-production-token-here
```

---

**Fragen?** Siehe `AUTHENTICATION.md` für detaillierte Backend-Dokumentation.

**Status der Backend-Changes:** ✅ Vollständig implementiert und getestet (45/45 Tests passing)