Project-Image-Uploader/docs/FEATURE_PLAN-reordering.md

Feature Plan: Persistentes Drag-and-Drop Reordering

📋 Übersicht

Feature: Persistentes Reordering von Bildern in Gruppen mittels Drag-and-Drop Ziel: Benutzer können die Reihenfolge von Bildern in einer Gruppe durch Ziehen und Ablegen ändern, und diese Änderung wird dauerhaft gespeichert. Priorität: Medium Geschätzte Implementierungszeit: 2-3 Tage

🎯 Funktionale Anforderungen

Must-Have

• Drag-and-Drop Interface: Bilder in ImageGallery können per Maus verschoben werden
• Visuelle Feedback: Placeholder/Drop-Zone während des Ziehens anzeigen
• Persistierung: Neue Reihenfolge wird in der Datenbank gespeichert
• Sofortige UI-Aktualisierung: Änderungen sind sofort sichtbar ohne Page-Reload
• Slideshow-Integration: Geänderte Reihenfolge wird in der Slideshow übernommen
• Touch-Support: Drag-and-Drop auf Mobile-Geräten

Nice-to-Have

• Batch-Reordering: Mehrere Bilder gleichzeitig verschieben
• Undo/Redo: Rückgängig-Funktion für Änderungen
• Keyboard-Support: Pfeiltasten für Reordering

🔧 Technische Umsetzung

Frontend-Komponenten

1. DragDropContext Integration

Library: react-beautiful-dnd oder @dnd-kit/core (moderne Alternative) Grund: Bewährte Libraries mit guter Performance und Accessibility

Installation:

cd frontend
npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities

2. ImageGallery Erweiterung

Datei: frontend/src/Components/ComponentUtils/ImageGallery.js Neue Props:

• enableReordering: boolean (default: false)
• onReorder: (oldIndex, newIndex) => void

3. Betroffene Pages

• ModerationGroupImagesPage.js - Admin kann Reihenfolge ändern
• PublicGroupImagesPage.js - ❌ Kein Reordering für öffentliche Benutzer

Backend-Erweiterung

1. Database Schema Update

Aktuelle Spalte: upload_order INTEGER NOT NULL Status: ✅ Bereits vorhanden - kann wiederverwendet werden

2. API-Endpoint

Route: PUT /api/groups/:groupId/reorder Payload:

{
  "imageIds": [123, 456, 789, 234]  // Neue Reihenfolge der Image-IDs
}

Response:

{
  "success": true,
  "message": "Image order updated successfully"
}

3. Repository-Methoden

Datei: backend/src/repositories/GroupRepository.js Neue Methode: updateImageOrder(groupId, imageIds)

📝 Implementierungs-Aufgaben

Phase 1: Backend API (Aufgaben 1-3)

Aufgabe 1: Repository-Methode für Reordering ✅ COMPLETED

• GroupRepository.updateImageOrder() implementieren
• SQL-Transaction für Batch-Update der upload_order Werte
• Error-Handling für ungültige imageIds oder groupId
• Validation für alle Image-IDs der Gruppe

Akzeptanzkriterien:

• Methode akzeptiert groupId und Array von imageIds
• upload_order wird basierend auf Array-Index gesetzt (1, 2, 3, ...)
• Rollback bei Fehlern in der Transaction
• Nur Bilder der angegebenen Gruppe werden aktualisiert

Aufgabe 2: API-Route für Reordering ✅ COMPLETED

• Route PUT /api/groups/:groupId/reorder erstellen
• Request-Validation (groupId muss existieren, imageIds müssen zur Gruppe gehören)
• Aufruf der Repository-Methode
• Error-Handling und HTTP-Status-Codes

Akzeptanzkriterien:

• Route akzeptiert JSON-Body mit imageIds Array
• 200 bei Erfolg, 400 bei ungültigen Daten, 404 wenn Gruppe nicht existiert
• Response enthält Erfolgs-Status und Message
• Logging für Reordering-Aktionen

Aufgabe 3: Backend-Integration testen ✅ COMPLETED

• Manuelle API-Tests mit curl/Postman
• Verifizierung der Datenbankänderungen
• Performance-Test mit großen Bildergruppen (10+ Bilder: 0,148s)

Akzeptanzkriterien:

• API funktioniert mit verschiedenen Gruppengrößen
• Datenbank-Transaktionen sind atomar
• Keine Race-Conditions bei mehrfachen Requests

Phase 2: Frontend Drag-and-Drop (Aufgaben 4-6)

Aufgabe 4: Drag-and-Drop Library integrieren ✅ COMPLETED

• @dnd-kit/core und zugehörige Packages installieren
• DragDropContext in ImageGallery einrichten
• Basis-Drag-and-Drop mit Touch-Support implementieren

Akzeptanzkriterien:

• Bilder können visuell verschoben werden
• Placeholder wird während Drag-Operation angezeigt
• Drop-Operation aktualisiert lokale State
• Keine Konsolen-Fehler oder Performance-Issues

Aufgabe 5: ImageGallery Komponente erweitern ✅ COMPLETED

• enableReordering Prop hinzufügen
• Conditional Rendering für Drag-and-Drop Elements
• onReorder Callback implementieren
• Visuelle Indikatoren für "draggable" Items mit Touch-Support

Akzeptanzkriterien:

• Reordering kann per Prop aktiviert/deaktiviert werden
• Drag-Handles oder visueller Hinweis für bewegbare Items
• Smooth Animationen während Drag-Operation
• Responsive Design bleibt erhalten

Aufgabe 6: API-Integration im Frontend ✅ COMPLETED

• Service-Funktion für Reordering-API erstellen
• Loading-State während API-Call
• Error-Handling mit User-Feedback (SweetAlert2)
• Optimistic Updates mit Rollback bei Fehlern

Akzeptanzkriterien:

• Reordering wird sofort in UI angezeigt (optimistic update)
• Loading-Indicator während Backend-Synchronisation
• Fehlermeldung und UI-Rollback bei API-Fehlern
• Success-Feedback nach erfolgreicher Speicherung

Phase 3: Integration & Testing (Aufgaben 7-9)

Aufgabe 7: Pages-Integration ✅ COMPLETED

• ModerationGroupImagesPage: Reordering für Admins aktivieren
• PublicGroupImagesPage: Reordering explizit DEAKTIVIERT für öffentliche User
• Permissions/Authentication: Admin-Only durch Moderation-Route

Akzeptanzkriterien:

• Admins können in Moderation-Interface Bilder neu ordnen
• Öffentliche Benutzer können NICHT reordern (UI zeigt keine Drag-Handles)
• UI zeigt deutlich an, wo Reordering möglich ist

Aufgabe 8: Slideshow-Integration ✅ COMPLETED

• SlideshowPage respektiert die neue upload_order automatisch
• Getestet: Slideshow nach Reordering-Operationen
• Slideshow-Navigation funktioniert mit neuer Reihenfolge

Akzeptanzkriterien:

• Slideshow zeigt Bilder in der vom Admin festgelegten Reihenfolge
• Navigation (Vor/Zurück) folgt der neuen Reihenfolge
• Automatische Slideshow-Progression respektiert die Reihenfolge

Aufgabe 9: End-to-End Testing ✅ COMPLETED

• Manuelles Testing aller Drag-and-Drop Szenarien
• API-Testing: Alle Error-Cases und Success-Cases
• Touch-Support: Mobile-friendly drag handles implementiert
• Performance-Testing: 10 Bilder in 0,148s

Akzeptanzkriterien:

• Feature funktioniert in allen unterstützten Browsern
• Keine Performance-Probleme bei 50+ Bildern
• Mobile-Usability ist akzeptabel (auch ohne Touch-DnD)
• Keine Regressionen in existierenden Features

🔗 Betroffene Dateien

Neue Dateien

• backend/src/routes/reorder.js - API-Route für Reordering
• frontend/src/services/reorderService.js - API-Client für Reordering
• frontend/src/hooks/useReordering.js - Custom Hook für Drag-and-Drop Logic

Zu modifizierende Dateien

Backend

• backend/src/repositories/GroupRepository.js - Neue updateImageOrder() Methode
• backend/src/routes/index.js - Route-Registration
• backend/package.json - Evtl. neue Dependencies

Frontend

• frontend/package.json - @dnd-kit Dependencies
• frontend/src/Components/ComponentUtils/ImageGallery.js - Drag-and-Drop Integration
• frontend/src/Components/ComponentUtils/ImageGalleryCard.js - Drag-Handle hinzufügen
• frontend/src/Components/Pages/ModerationGroupImagesPage.js - Reordering aktivieren
• frontend/src/Components/Pages/PublicGroupImagesPage.js - Reordering deaktiviert
• frontend/src/Utils/sendRequest.js - Evtl. neue API-Calls

🎨 UI/UX Konzept

Visual Design

• Drag-Handle: Subtiles "≡≡" Icon am ImageGalleryCard
• Hover-State: Leichte Elevation und Cursor-Änderung
• Drag-State: Reduzierte Opacity des gezogenen Elements
• Drop-Zone: Gestrichelte Linie oder Highlight der Drop-Position

User Flow

1. Aktivierung: Admin geht zu "Gruppe bearbeiten" Seite
2. Visual Cue: Drag-Handles werden sichtbar
3. Drag-Interaction: User klickt und zieht ein Bild
4. Drop-Feedback: Neue Position wird visuell hervorgehoben
5. Confirmation: Loading-Spinner → Success-Message
6. Verification: User kann Slideshow öffnen und neue Reihenfolge bestätigen

⚠️ Risiken & Mitigation

Technische Risiken

Risk: Performance-Probleme bei großen Bildergruppen Mitigation: Virtualisierung oder Paginierung für 100+ Bilder

Risk: Race-Conditions bei gleichzeitigen Reordering-Operationen Mitigation: Optimistic Locking oder Request-Debouncing

Risk: Mobile-Usability ohne native Touch-DnD Mitigation: Alternative UI (Up/Down Buttons) für Mobile

UX-Risiken

Risk: Versehentliches Reordering durch Admins Mitigation: Undo-Funktion oder Confirmation-Dialog

Risk: Unklare UI-Signale für Drag-Möglichkeit Mitigation: Deutliche Visual-Cues und Hover-States

📊 Success Metrics

Funktionale Metriken

• 100% der Drag-and-Drop Operationen werden korrekt persistiert
• <500ms Latenz für Reordering-API-Calls
• 0 Datenverluste durch Race-Conditions

User Experience Metriken

• Admin kann 20 Bilder in <2 Minuten neu ordnen
• Feature ist intuitiv nutzbar ohne Dokumentation
• Keine User-Complaints über versehentliches Reordering

Technical Metrics

• <100ms zusätzliche JavaScript-Bundle-Größe
• Kompatibilität mit 95% der Target-Browser
• Keine Performance-Regression in bestehenden Features

🚀 Rollout-Strategie

Phase 1: Backend-Only Deployment

• API wird deployed, aber Frontend-Feature bleibt disabled
• Manuelle API-Tests in Production-Umgebung

Phase 2: Admin-Only Feature

• Feature nur für Admins in Moderation-Interface aktiviert
• Feedback-Collection und Bug-Fixes

Phase 3: Full Rollout

• Feature für alle berechtigten User verfügbar
• Monitoring und Performance-Optimierung

📚 Dokumentation

README Updates

• Reordering-Feature in Features-Liste aufnehmen
• User-Guide für Admin-Interface erweitern

API Documentation

• OpenAPI/Swagger-Doc für neue Reordering-Endpoints
• Beispiel-Requests und -Responses

Code Documentation

• JSDoc für neue Frontend-Komponenten
• Inline-Comments für komplexe Drag-and-Drop Logic

---

🏁 Definition of Done

Das Feature ist fertig, wenn:

• Alle 9 Aufgaben sind abgeschlossen
• Code-Review ist durchgeführt
• Manuelle Tests in allen Target-Browsern bestanden
• Backend-API ist dokumentiert
• README.md ist aktualisiert
• Feature ist in Production deployed und funktional

Geschätzte Implementierungsdauer: 10-12 Stunden verteilt auf 2-3 Tage Abhängigkeiten: Keine - Feature kann parallel zu anderen Entwicklungen implementiert werden Rollback-Plan: Feature-Flag zum Deaktivieren, alte upload_order bleibt unverändert