# 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
- [x] **Drag-and-Drop Interface**: Bilder in ImageGallery können per Maus verschoben werden
- [x] **Visuelle Feedback**: Placeholder/Drop-Zone während des Ziehens anzeigen
- [x] **Persistierung**: Neue Reihenfolge wird in der Datenbank gespeichert
- [x] **Sofortige UI-Aktualisierung**: Änderungen sind sofort sichtbar ohne Page-Reload
- [x] **Slideshow-Integration**: Geänderte Reihenfolge wird in der Slideshow übernommen
- [x] **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:**
```bash
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**:
```json
{
  "imageIds": [123, 456, 789, 234]  // Neue Reihenfolge der Image-IDs
}
```

**Response**:
```json
{
  "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**
- [x] `GroupRepository.updateImageOrder()` implementieren
- [x] SQL-Transaction für Batch-Update der upload_order Werte
- [x] Error-Handling für ungültige imageIds oder groupId
- [x] 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**
- [x] Route `PUT /api/groups/:groupId/reorder` erstellen
- [x] Request-Validation (groupId muss existieren, imageIds müssen zur Gruppe gehören)
- [x] Aufruf der Repository-Methode
- [x] 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**
- [x] Manuelle API-Tests mit curl/Postman
- [x] Verifizierung der Datenbankänderungen
- [x] 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**
- [x] `@dnd-kit/core` und zugehörige Packages installieren
- [x] DragDropContext in ImageGallery einrichten
- [x] 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**
- [x] `enableReordering` Prop hinzufügen
- [x] Conditional Rendering für Drag-and-Drop Elements
- [x] `onReorder` Callback implementieren
- [x] 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**
- [x] Service-Funktion für Reordering-API erstellen
- [x] Loading-State während API-Call
- [x] Error-Handling mit User-Feedback (SweetAlert2)
- [x] 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**
- [x] ModerationGroupImagesPage: Reordering für Admins aktivieren
- [x] PublicGroupImagesPage: Reordering explizit DEAKTIVIERT für öffentliche User
- [x] 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**
- [x] SlideshowPage respektiert die neue upload_order automatisch
- [x] Getestet: Slideshow nach Reordering-Operationen
- [x] 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**
- [x] Manuelles Testing aller Drag-and-Drop Szenarien
- [x] API-Testing: Alle Error-Cases und Success-Cases
- [x] Touch-Support: Mobile-friendly drag handles implementiert
- [x] 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:
- [x] Alle 9 Aufgaben sind abgeschlossen
- [x] Code-Review ist durchgeführt
- [x] Manuelle Tests in allen Target-Browsern bestanden
- [x] Backend-API ist dokumentiert
- [x] README.md ist aktualisiert
- [x] 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