hobbyhimmel/Project-Image-Uploader
8
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
6332b82c6a
Project-Image-Uploader/README.dev.md
matthias.lotz 6332b82c6a Feature Request: admin session security 
- replace bearer auth with session+CSRF flow and add admin user directory

- update frontend moderation flow, force password change gate, and new CLI

- refresh changelog/docs/feature plan + ensure swagger dev experience
2025-11-23 21:18:42 +01:00

14 KiB
Raw Blame History

Development Setup

⚠️ Wichtige Hinweise für Frontend-Entwickler

🔴 BREAKING CHANGES - API-Umstrukturierung (November 2025)

Im Rahmen der OpenAPI-Auto-Generation wurden massive Änderungen an der API-Struktur vorgenommen:

  • Authentication: Admin-Endpoints laufen jetzt über serverseitige Sessions + CSRF Tokens
  • Route-Struktur: Einige Pfade haben sich geändert (Single Source of Truth: routeMappings.js)
  • Error Handling: Neue HTTP-Status-Codes (403 für Auth-Fehler)

📖 Siehe:

  • frontend/MIGRATION-GUIDE.md - Detaillierte Migrations-Anleitung für Frontend
  • backend/src/routes/README.md - Vollständige API-Route-Dokumentation
  • AUTHENTICATION.md - Auth-System-Setup und Verwendung

Geschätzter Migrations-Aufwand: 2-3 Stunden

Schnellstart

Starten (Development Environment)

# Mit Script (empfohlen):
./dev.sh

# Oder manuell:
docker compose -f docker/dev/docker-compose.yml up -d

Zugriff

Logs verfolgen

# Alle Services:
docker compose -f docker/dev/docker-compose.yml logs -f

# Nur Frontend:
docker compose -f docker/dev/docker-compose.yml logs -f frontend-dev

# Nur Backend:
docker compose -f docker/dev/docker-compose.yml logs -f backend-dev

API-Entwicklung

⚠️ BREAKING CHANGES - Frontend Migration erforderlich

Massive API-Änderungen im November 2025:

  • Session + CSRF Authentication für alle Admin-Endpoints
  • Route-Pfade umstrukturiert (siehe routeMappings.js)
  • Neue Error-Response-Formate

📖 Frontend Migration Guide: frontend/MIGRATION-GUIDE.md

Route-Struktur

Die API verwendet eine Single Source of Truth für Route-Mappings:

📄 backend/src/routes/routeMappings.js - Zentrale Route-Konfiguration

Siehe auch: backend/src/routes/README.md für vollständige API-Übersicht

Wichtige Route-Gruppen:

  • /api/upload, /api/download - Öffentliche Upload/Download-Endpoints
  • /api/manage/:token - Self-Service Management Portal (UUID-Token)
  • /api/admin/* - Admin-Endpoints (Session + CSRF Authentication)
  • /api/system/migration/* - Datenbank-Migrationen

⚠️ Express Route-Reihenfolge beachten: Router mit spezifischen Routes vor generischen Routes mounten!

// ✅ RICHTIG: Spezifisch vor generisch
{ router: 'consent', prefix: '/api/admin' },  // /groups/by-consent
{ router: 'admin', prefix: '/api/admin' },    // /groups/:groupId

// ❌ FALSCH: Generisch fängt alles ab
{ router: 'admin', prefix: '/api/admin' },    // /groups/:groupId matched auf 'by-consent'!
{ router: 'consent', prefix: '/api/admin' },  // Wird nie erreicht

Authentication

Zwei Auth-Systeme parallel:

  1. Admin API (Session + CSRF):

    # .env konfigurieren:
ADMIN_SESSION_SECRET=$(openssl rand -hex 32)

# Initialen Admin anlegen (falls benötigt)
curl -c cookies.txt http://localhost:5001/auth/setup/status
curl -X POST -H "Content-Type: application/json" \
  -c cookies.txt -b cookies.txt \
  -d '{"username":"admin","password":"SuperSicher123"}' \
  http://localhost:5001/auth/setup/initial-admin

# Login + CSRF Token holen
curl -X POST -H "Content-Type: application/json" \
  -c cookies.txt -b cookies.txt \
  -d '{"username":"admin","password":"SuperSicher123"}' \
  http://localhost:5001/auth/login
CSRF=$(curl -sb cookies.txt http://localhost:5001/auth/csrf-token | jq -r '.csrfToken')

# Authentifizierter Admin-Request
curl -b cookies.txt -H "X-CSRF-Token: $CSRF" \
  http://localhost:5001/api/admin/groups

  2. Management Portal (UUID Token):

    # Automatisch beim Upload generiert
GET /api/manage/550e8400-e29b-41d4-a716-446655440000

📖 Vollständige Doku: AUTHENTICATION.md

Admin-Hinweise: Logout & neue Nutzer

  • Logout: Bis ein eigener Button im UI existiert, kann die Session jederzeit über den vorhandenen Endpoint beendet werden, z. B. in der Browser-Konsole: 
    await fetch('/auth/logout', { method: 'POST', credentials: 'include' });
    Alternativ per CLI: curl -b cookies.txt -X POST http://localhost:5001/auth/logout. Danach ist das sid-Cookie entfernt und die Moderationsseite zeigt wieder den Login.
  • Weiterer Admin: npm run create-admin -- --username zweiteradmin --password 'SuperPasswort123!' [--role admin --require-password-change] oder alternativ ./scripts/create_admin_user.sh --username zweiteradmin --password 'SuperPasswort123!' [...] ruft das Skript (backend/src/scripts/createAdminUser.js) auf und legt einen weiteren User an. Das Skript prüft Duplikate, nutzt dieselben Bcrypt-Runden wie das Backend und kann bei Bedarf weiterhin über die DB nachvollzogen werden. Falls du lieber manuell arbeitest, kannst du wie bisher einen Hash erzeugen und direkt in admin_users einfügen.

OpenAPI-Spezifikation

Die OpenAPI-Spezifikation wird automatisch beim Backend-Start generiert:

# Generiert: backend/docs/openapi.json
# Swagger UI: http://localhost:5001/api/docs/

# Manuelle Generierung:
cd backend
node src/generate-openapi.js

Swagger-Annotationen in Routes:

router.get('/example', async (req, res) => {
    /* 
        #swagger.tags = ['Example']
        #swagger.summary = 'Get example data'
        #swagger.responses[200] = { description: 'Success' }
    */
});

Entwicklung

Frontend-Entwicklung

  • Code in frontend/src/ editieren → Hot Module Reload übernimmt Änderungen
  • Volumes: Source-Code wird live in Container gemountet
  • Container-Namen: image-uploader-frontend-dev

Wichtige Komponenten:

  • Components/Pages/MultiUploadPage.js - Upload-Interface mit Consent-Management
  • Components/ComponentUtils/MultiUpload/ConsentCheckboxes.js - GDPR-konforme Consent-UI
  • Components/Pages/ModerationGroupsPage.js - Moderation mit Consent-Filtern
  • services/reorderService.js - Drag-and-Drop Logik
  • hooks/useImagePreloader.js - Slideshow-Preloading

Backend-Entwicklung

  • Code in backend/src/ editieren → Nodemon übernimmt Änderungen automatisch
  • Container-Namen: image-uploader-backend-dev
  • Environment: NODE_ENV=development

Wichtige Module:

  • routes/routeMappings.js - Single Source of Truth für Route-Konfiguration
  • repositories/GroupRepository.js - Consent-Management & CRUD
  • repositories/SocialMediaRepository.js - Plattform- & Consent-Verwaltung
  • routes/batchUpload.js - Upload mit Consent-Validierung
  • middlewares/session.js - Express-Session + SQLite Store
  • middlewares/auth.js - Admin Session-Guard & CSRF-Pflicht
  • database/DatabaseManager.js - Automatische Migrationen
  • services/GroupCleanupService.js - 7-Tage-Cleanup-Logik

Datenbank-Entwicklung

Migrationen erstellen

# Neue Migration anlegen:
touch backend/src/database/migrations/XXX_description.sql

# Migrationen werden automatisch beim Backend-Start ausgeführt
# Manuell: docker compose -f docker/dev/docker-compose.yml restart backend-dev

Datenbank-Zugriff

# SQLite Shell:
docker compose -f docker/dev/docker-compose.yml exec backend-dev sqlite3 /usr/src/app/src/data/db/image_uploader.db

# Schnellabfragen:
docker compose -f docker/dev/docker-compose.yml exec backend-dev sqlite3 /usr/src/app/src/data/db/image_uploader.db "SELECT * FROM groups LIMIT 5;"

# Schema anzeigen:
docker compose -f docker/dev/docker-compose.yml exec backend-dev sqlite3 /usr/src/app/src/data/db/image_uploader.db ".schema"

Migrationen debuggen

# Migration-Status prüfen:
docker compose -f docker/dev/docker-compose.yml exec backend-dev sqlite3 /usr/src/app/src/data/db/image_uploader.db "SELECT * FROM schema_migrations;"

# Backend-Logs mit Migration-Output:
docker compose -f docker/dev/docker-compose.yml logs backend-dev | grep -i migration

Konfiguration anpassen

  • Frontend: docker/dev/frontend/config/.env
  • Backend: docker/dev/backend/config/.env
  • Nginx: docker/dev/frontend/nginx.conf

Testing

Automatisierte Tests

Das Backend verfügt über eine umfassende Test-Suite mit 45 Tests:

# Alle Tests ausführen:
cd backend
npm test

# Einzelne Test-Suite:
npm test -- tests/api/admin.test.js

# Mit Coverage-Report:
npm test -- --coverage

# Watch-Mode (während Entwicklung):
npm test -- --watch

Test-Struktur:

  • tests/unit/ - Unit-Tests (z.B. Auth-Middleware)
  • tests/api/ - Integration-Tests (API-Endpoints)
  • tests/setup.js - Globale Test-Konfiguration
  • tests/testServer.js - Test-Server-Helper

Test-Features:

  • Jest + Supertest Framework
  • In-Memory SQLite Database (isoliert)
  • Singleton Server Pattern (schnell)
  • 100% Test-Success-Rate (45/45 passing)
  • ~10 Sekunden Ausführungszeit
  • Coverage: 26% Statements, 15% Branches

Test-Umgebung:

  • Verwendet /tmp/test-image-uploader/ für Upload-Tests
  • Eigene Datenbank :memory: (kein Konflikt mit Dev-DB)
  • Environment: NODE_ENV=test
  • Automatisches Cleanup nach Test-Run

Neue Tests hinzufügen:

// tests/api/example.test.js
const { getRequest } = require('../testServer');

describe('Example API', () => {
  it('should return 200', async () => {
    const response = await getRequest()
      .get('/api/example')
      .expect(200);
    
    expect(response.body).toHaveProperty('data');
  });
});

Manuelles Testing

Consent-System testen

# 1. Upload mit und ohne Workshop-Consent
# 2. Social Media Checkboxen testen (Facebook, Instagram, TikTok)
# 3. Moderation-Filter prüfen:
#    - Alle Gruppen
#    - Nur Werkstatt
#    - Facebook / Instagram / TikTok
# 4. Export-Funktion (CSV/JSON) testen

Cleanup-System testen

# Test-Script verwenden:
./tests/test-cleanup.sh

# Oder manuell:
# 1. Upload ohne Approval
# 2. Gruppe zurückdatieren (Script verwendet)
# 3. Preview: GET http://localhost:5001/api/admin/cleanup/preview
# 4. Trigger: POST http://localhost:5001/api/admin/cleanup/trigger
# 5. Log prüfen: GET http://localhost:5001/api/admin/deletion-log

API-Tests

# Consent-Endpoints:
curl http://localhost:5001/api/social-media/platforms
curl http://localhost:5001/api/groups/by-consent?workshopConsent=true
curl http://localhost:5001/api/admin/consents/export

# Upload testen (mit Consents):
curl -X POST http://localhost:5001/api/upload-batch \
  -F "images=@test.jpg" \
  -F "year=2025" \
  -F "title=Test" \
  -F "name=Developer" \
  -F 'consents={"workshopConsent":true,"socialMediaConsents":[{"platformId":1,"consented":true}]}'

Container-Management

# Status anzeigen:
docker compose -f docker/dev/docker-compose.yml ps

# Container neustarten:
docker compose -f docker/dev/docker-compose.yml restart

# Container neu bauen (nach Package-Updates):
docker compose -f docker/dev/docker-compose.yml build --no-cache

# Stoppen:
docker compose -f docker/dev/docker-compose.yml down

# Mit Volumes löschen (ACHTUNG: Löscht Datenbank!):
docker compose -f docker/dev/docker-compose.yml down -v

Shell-Zugriff

# Frontend Container:
docker compose -f docker/dev/docker-compose.yml exec frontend-dev bash

# Backend Container:
docker compose -f docker/dev/docker-compose.yml exec backend-dev bash

# Datenbank-Shell:
docker compose -f docker/dev/docker-compose.yml exec backend-dev sqlite3 /usr/src/app/src/data/db/image_uploader.db

Debugging

Backend Debugging

# Live-Logs:
docker compose -f docker/dev/docker-compose.yml logs -f backend-dev

# Nodemon Restart:
# → Änderungen in backend/src/** werden automatisch erkannt

# Fehlerhafte Migration fixen:
# 1. Migration-Eintrag löschen:
docker compose -f docker/dev/docker-compose.yml exec backend-dev sqlite3 /usr/src/app/src/data/db/image_uploader.db "DELETE FROM schema_migrations WHERE migration_name='XXX.sql';"
# 2. Backend neustarten:
docker compose -f docker/dev/docker-compose.yml restart backend-dev

Frontend Debugging

# React DevTools im Browser verwenden
# Network Tab für API-Calls prüfen
# Console für Fehler checken

# Nginx-Reload (bei Konfig-Änderungen):
docker compose -f docker/dev/docker-compose.yml exec frontend-dev nginx -s reload

Datenbank-Backup & Restore

# Backup:
docker cp image-uploader-backend-dev:/usr/src/app/src/data/db/image_uploader.db ./backup.db

# Restore:
docker cp ./backup.db image-uploader-backend-dev:/usr/src/app/src/data/db/image_uploader.db
docker compose -f docker/dev/docker-compose.yml restart backend-dev

Häufige Probleme

"Migration failed" Fehler

Problem: Inline-Kommentare in SQL-Statements
Lösung: DatabaseManager entfernt diese automatisch (seit Commit 8e62475)

"No such column: display_in_workshop"

Problem: Migration 005 nicht ausgeführt
Lösung: Backend neu starten oder manuell Migration ausführen

Port 3000 bereits belegt

Problem: Anderer Prozess nutzt Port 3000
Lösung:

lsof -ti:3000 | xargs kill -9
# Oder Port in docker/dev/docker-compose.yml ändern

Consent-Filter zeigt nichts

Problem: display_in_workshop fehlt in groupFormatter
Lösung: Bereits gefixt (Commit f049c47)

Git Workflow

# Feature Branch erstellen:
git checkout -b feature/my-feature

# Änderungen committen:
git add .
git commit -m "feat: Add new feature"

# Vor Merge: Code testen!
# - Upload-Flow mit Consents
# - Moderation mit Filtern
# - Slideshow-Funktionalität
# - Cleanup-System

# Push:
git push origin feature/my-feature

Nützliche Befehle

# Alle Container-IDs:
docker ps -a

# Speicherplatz prüfen:
docker system df

# Ungenutztes aufräumen:
docker system prune -a

# Logs durchsuchen:
docker compose -f docker/dev/docker-compose.yml logs | grep ERROR

# Performance-Monitoring:
docker stats