# Feature-Konzept: Gruppenfoto zu Mitgliedsfotos

## Ziel

Trainer sollen ein Gruppenfoto hochladen oder mit der Kamera aufnehmen können und daraus per manuell gezogenem Rahmen einzelne Mitgliedsfotos erstellen. Die ausgeschnittenen Bilder werden wie normale Mitgliedsfotos gespeichert.

Zusätzlich soll ein Gruppenfoto für spätere Bearbeitung gespeichert werden können. So kann der Trainer im Training schnell ein Foto aufnehmen und die eigentliche Zuordnung und Bearbeitung später, zum Beispiel zuhause, erledigen.

## Nutzerfluss

1. Trainer öffnet `/members`.
2. Trainer klickt auf `Gruppenfoto verarbeiten`.
3. Ein Dialog öffnet sich mit drei Einstiegen:
   - `Foto aufnehmen`
   - `Foto hochladen`
   - `Gespeichertes Foto öffnen`
4. Bei einem neuen Foto entscheidet der Trainer:
   - `Nur jetzt verarbeiten`
   - `Für spätere Bearbeitung speichern`
5. Das Gruppenfoto wird groß angezeigt.
6. Trainer zieht einen Rahmen um eine Person oder ein Gesicht.
7. Trainer wählt das passende Mitglied aus.
8. Trainer klickt `Als Mitgliedsfoto speichern`.
9. Der Ausschnitt wird gespeichert.
10. Trainer kann direkt den nächsten Ausschnitt aus demselben Gruppenfoto markieren.

## Erster Funktionsumfang

- Gruppenfoto hochladen.
- Gruppenfoto mobil per Kamera aufnehmen.
- Gruppenfoto optional dauerhaft für spätere Bearbeitung speichern.
- Gespeicherte Gruppenfotos pro Verein auflisten.
- Gespeichertes Gruppenfoto später wieder öffnen.
- Manuelle Rahmenauswahl auf dem Gruppenfoto.
- Mitgliedsauswahl mit Suche.
- Ausschnitt-Vorschau vor dem Speichern.
- Ausschnitt als neues Mitgliedsfoto speichern.
- Optionaler Schalter `Als Hauptfoto verwenden`.
- Mehrere Ausschnitte nacheinander aus demselben Gruppenfoto erstellen.
- Gruppenfoto löschen, ohne bereits erzeugte Mitgliedsfotos zu löschen.

## Nicht im ersten Wurf

- Automatische Gesichtserkennung.
- Automatische Zuordnung zu Mitgliedern.
- Mehrfachrahmen gleichzeitig.
- Speichern unfertiger Crop-Rahmen als Entwurf.
- Statusverwaltung pro markiertem Ausschnitt.
- Nachträgliche Bearbeitung bereits erzeugter Mitgliedsfotos.

Diese Punkte können später ergänzt werden. Für die erste Version bleibt das Feature bewusst manuell und kontrollierbar.

## UI-Konzept

Auf `/members` wird ein neuer Button im Aktionsbereich ergänzt:

```text
Gruppenfoto verarbeiten
```

Der Dialog startet mit:

```text
Gruppenfoto verarbeiten

[Foto aufnehmen]
[Foto hochladen]
[Gespeichertes Foto öffnen]
```

Nach Fotoauswahl:

```text
[ ] Für spätere Bearbeitung speichern
Titel: Training 15.04.2026
Datum: 15.04.2026
Notiz: optional
```

Der Bearbeitungsdialog besteht aus:

- links: großes Gruppenfoto mit ziehbarem Crop-Rahmen
- rechts: Ausschnitt-Vorschau
- rechts: Mitgliedersuche
- rechts: Checkbox `Als Hauptfoto verwenden`
- rechts: Button `Als Mitgliedsfoto speichern`
- rechts: Statusmeldung, zum Beispiel `Foto gespeichert für Max Mustermann`

Für mobile Ansicht:

- Bild oben
- Vorschau darunter
- Mitgliedersuche darunter
- Speichern-Aktion am unteren Rand

## Gespeicherte Gruppenfotos

Unter `Gespeichertes Foto öffnen` wird eine Liste angezeigt:

- Titel
- Aufnahmedatum oder Erstelldatum
- optional Notiz
- Button `Öffnen`
- Button `Löschen`

Ein gelöschtes Gruppenfoto entfernt nur das Original-Gruppenfoto. Bereits erstellte Mitgliedsfotos bleiben erhalten.

## Crop-Verhalten

Empfehlung für Mitgliedsfotos:

- Standard-Seitenverhältnis `1:1`
- Mindestgröße zum Beispiel `160 x 160 px`
- Exportgröße zum Beispiel `600 x 600 px`
- JPEG-Qualität etwa `0.9`
- Warnung bei sehr kleinen Ausschnitten:

```text
Der Ausschnitt ist sehr klein und kann unscharf wirken.
```

Optional später:

- Umschalter `Freier Ausschnitt`
- Zoom und Pan für große Gruppenfotos
- Tastatursteuerung für Feinkorrektur

## Technische Umsetzung

### Frontend

Neue Komponente:

```text
frontend/src/components/members/GroupPhotoCropDialog.vue
```

Einbindung in:

```text
frontend/src/views/MembersView.vue
```

Technischer Ablauf:

1. Bilddatei per Dateiinput oder Kamera laden.
2. Bild im Browser anzeigen.
3. Crop-Koordinaten erfassen.
4. Ausschnitt per Canvas in ein neues Canvas zeichnen.
5. Canvas als `Blob` exportieren.
6. Blob per `FormData` an die bestehende Mitgliedsfoto-API hochladen.
7. Optional danach das Bild als Hauptfoto setzen.

Kameraaufnahme kann pragmatisch über einen Dateiinput starten:

```html
<input type="file" accept="image/*" capture>
```

### Bestehender Mitgliedsfoto-Upload

Wenn möglich wird die bestehende Route genutzt:

```text
POST /api/clubmembers/image/:clubId/:memberId
```

Falls `Als Hauptfoto verwenden` aktiv ist, wird danach die bestehende Primary-Route genutzt:

```text
POST /api/clubmembers/image/:clubId/:memberId/:imageId/primary
```

Der Blob kann als Datei `group-photo-crop.jpg` gesendet werden.

## Backend für gespeicherte Gruppenfotos

Für dauerhaft gespeicherte Gruppenfotos wird eine neue Tabelle empfohlen:

```text
member_group_photo
```

Minimal benötigte Felder:

- `id`
- `club_id`
- `title`
- `photo_path`
- `taken_at`
- `created_by_user_id`
- `created_at`
- `updated_at`

Sinnvolle weitere Felder:

- `description`
- `original_file_name`
- `mime_type`
- `file_size`
- `width`
- `height`
- `status`, zum Beispiel `open`, `in_progress`, `done`, `archived`
- `processed_at`
- `archived_at`

## API-Vorschlag

```text
GET    /api/member-group-photos/:clubId
POST   /api/member-group-photos/:clubId
GET    /api/member-group-photos/:clubId/:photoId/image
PUT    /api/member-group-photos/:clubId/:photoId
DELETE /api/member-group-photos/:clubId/:photoId
```

Beschreibung:

- `GET /:clubId`: listet gespeicherte Gruppenfotos des Vereins.
- `POST /:clubId`: speichert ein neues Gruppenfoto.
- `GET /:clubId/:photoId/image`: liefert das Originalbild für spätere Bearbeitung.
- `PUT /:clubId/:photoId`: aktualisiert Titel, Datum oder Notiz.
- `DELETE /:clubId/:photoId`: löscht das gespeicherte Gruppenfoto.

Alle Routen müssen authentifiziert sein und Vereinszugriff prüfen.

## Speicherort

Empfohlener Speicherort, getrennt von normalen Mitgliedsbildern:

```text
uploads/member-group-photos/:clubId/:photoId/original.jpg
```

Falls das Projekt bereits andere Upload-Konventionen nutzt, sollte der Pfad daran angepasst werden.

## Datenschutz und Berechtigungen

Wenn komplette Gruppenfotos gespeichert werden, können darauf auch Personen zu sehen sein, deren Einzelbild nicht gespeichert werden soll. Deshalb sollte im Dialog ein klarer Hinweis stehen:

```text
Dieses Gruppenfoto wird gespeichert und kann andere Personen enthalten. Bitte nur speichern, wenn die Nutzung im Verein zulässig ist.
```

Empfehlungen:

- Gruppenfotos nur für berechtigte Vereinsnutzer sichtbar machen.
- Keine öffentliche Bild-URL ohne Authentifizierung.
- Bildauslieferung nur über geschützte API.
- Löschfunktion direkt in der Gruppenfoto-Liste anbieten.
- Das Speichern eines Gruppenfotos ändert keine bestehenden Einwilligungen, zum Beispiel `picsInInternetAllowed`.
- Die Zuordnung eines Ausschnitts zu einem Mitglied bleibt eine bewusste Trainerentscheidung.

## Späterer Ausbau: Crop-Entwürfe

Wenn später auch unfertige Rahmen gespeichert werden sollen, kann eine zweite Tabelle ergänzt werden:

```text
member_group_photo_crop
```

Mögliche Felder:

- `id`
- `group_photo_id`
- `member_id`
- `x`
- `y`
- `width`
- `height`
- `status`
- `created_at`
- `updated_at`

Mögliche Statuswerte:

- `open`
- `assigned`
- `saved`
- `discarded`

Das ist nicht Teil der ersten Version, wäre aber die Grundlage für Mehrfachrahmen und spätere Weiterbearbeitung.

## Fehlerfälle

- Kein Foto gewählt: Bearbeitung nicht möglich.
- Kein Rahmen gezogen: Speichern deaktivieren.
- Kein Mitglied gewählt: Speichern deaktivieren.
- Ausschnitt zu klein: Warnung anzeigen oder Speichern deaktivieren.
- Upload schlägt fehl: Fehlermeldung anzeigen, Auswahl beibehalten.
- Gruppenfoto kann nicht geladen werden: Fehlermeldung und Rückkehr zur Liste.
- Gruppenfoto wurde gelöscht: Liste aktualisieren.

## Akzeptanzkriterien

- Trainer kann ein Gruppenfoto hochladen.
- Trainer kann ein Gruppenfoto mobil aufnehmen.
- Trainer kann ein Gruppenfoto für spätere Bearbeitung speichern.
- Gespeicherte Gruppenfotos werden pro Verein aufgelistet.
- Ein gespeichertes Gruppenfoto kann später geöffnet und bearbeitet werden.
- Trainer kann per Rahmen einen Ausschnitt markieren.
- Ausschnitt wird als Vorschau angezeigt.
- Trainer kann ein Mitglied suchen und auswählen.
- Ausschnitt wird als Mitgliedsfoto gespeichert.
- Optional kann der Ausschnitt als Hauptfoto gesetzt werden.
- Mehrere Mitglieder können nacheinander aus demselben Gruppenfoto versorgt werden.
- Gruppenfoto kann gelöscht werden.
- Löschen eines Gruppenfotos löscht keine bereits erstellten Mitgliedsfotos.
- Gruppenfoto ist nur für berechtigte Nutzer des Vereins abrufbar.
- Das vollständige Gruppenfoto wird nur gespeichert, wenn der Trainer dies bewusst auswählt.
- Frontend-Build läuft ohne Fehler.
