Project-Image-Uploader/frontend/MIGRATION-GUIDE.md

# Frontend Migration Guide - Admin API Authentication

**Datum:** 16. November 2025  
**Betrifft:** Alle Admin-API-Aufrufe im Frontend  
**Status:** ⚠️ Aktion erforderlich

---

## 🔒 Was hat sich geändert?

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

### Betroffene 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. Environment Variable 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!

### 2. API-Aufrufe 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

Such nach allen Admin-API-Aufrufen:

```bash
cd frontend/src

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

# Alle Fetch-Calls in spezifischen Komponenten:
grep -r "fetch.*admin" Components/Pages/
```

**Wahrscheinlich betroffene Komponenten:**
- `Components/Pages/ModerationGroupsPage.js`
- `Components/Pages/ModerationGroupImagesPage.js`
- `Components/ComponentUtils/ConsentManager.js` (wenn im moderate-Modus)
- `services/reorderService.js` (Admin-Reorder)
- Jede andere Komponente, die Admin-Funktionen aufruft

---

## ✅ Checkliste

- [ ] `REACT_APP_ADMIN_API_KEY` in `.env` hinzugefügt
- [ ] Token im Backend als `ADMIN_API_KEY` konfiguriert
- [ ] Zentrale `adminFetch` Funktion erstellt
- [ ] Alle Admin-API-Calls gefunden (grep)
- [ ] Authorization Header zu allen Admin-Calls hinzugefügt
- [ ] 403 Error Handling implementiert
- [ ] Frontend lokal getestet
- [ ] 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)