vtuber-awards/docs/workflow-feedback-plan.md

# Workflow-Feedback: Planung und Ausarbeitung

Stand: 2026-06-27  
Quelle: `VTuber Star Awards Workflow.docx` inklusive Kommentaren, abgeglichen mit dem aktuellen VTubeAwards-Repo.

## Executive Summary

Die erste grosse Aenderung sollte den Core Workflow stabilisieren: Nominierung, Vorbereitung, Voting und Review/Auswertung. Das Feedback beschreibt weniger ein komplett neues Produktmodell als eine klarere Fuehrung durch bereits vorhandene Konzepte.

Die wichtigsten Produktentscheidungen:

- Kategorien mit Viewer-Groessen werden als einzelne Kategorien pro Unterkategorie abgebildet, gruppiert ueber `GroupName`.
- Viewer duerfen pro Hauptkategorie so viele Stream- oder Kanal-Links nominieren, wie in der Hauptkategorie als `MaxNomineesPerUser` konfiguriert ist. Der aktuelle Default bleibt drei.
- Eine Nominierung muss nicht fuer alle Kategorien abgegeben werden.
- Clip-Compilations werden nicht als Videodateien in der App gespeichert.
- Voting und Gewinnerbereiche nutzen externe YouTube-/Twitch-Links oder Embeds.
- Die Vorbereitung nach der Nominierung bleibt ein Admin-/Teamprozess mit manuellem Kontakt und Annahmestatus.
- Showacts und Sponsoren werden als admin-verwaltbare Folgefeatures geplant, aber nicht in Phase 1 umgesetzt.

## Feedback-Analyse

### Kategorien und Unterkategorien

Das Dokument beschreibt pro Award-Kategorie drei Unterkategorien nach Viewer-Groesse:

- Hidden Star: 1 bis 20 Viewer
- Rising Star: 21 bis 60 Viewer
- Shining Star: 61+ Viewer

Im aktuellen Datenmodell passt das am besten zu einzelnen `Category`-Datensaetzen pro Unterkategorie. Der uebergeordnete Award-Bereich, zum Beispiel `Gamer`, bleibt `GroupName`; die konkrete Unterkategorie wird `Name`, zum Beispiel `Hidden Star der Gamer`.

Damit entsteht kein paralleles Kategorienmodell. Admin- und Voting-Flows arbeiten weiter mit konkreten `CategoryId`s. Die Public-Nominierung wurde davon bewusst entkoppelt: User nominieren auf Hauptkategorie/`GroupName`, das passende Viewer-Tier wird danach ueber Tracker- und Admin-Review bestimmt.

Um die Pflege fuer Admins einfacher zu machen, bleibt die normale Hauptkategorie-Pflege erhalten, waehrend Unterkategorien zentral in einem Season-Modal konfiguriert werden. Ein Award-Bereich bleibt `GroupName`, Unterkategorien bleiben im Ausfuehrungsmodell normale `Category`-Datensaetze, werden aber aus der globalen Definition fuer alle Hauptkategorien synchron gehalten. Viewer-Range, Name, Slug und Reihenfolge werden pro Unterkategorie strukturiert gespeichert; ein separates Standard-Set wird nicht mehr angeboten.

### Nominierung

Das Feedback wuenscht pro Kategorie mehrere Nominierungen als Stream-/Kanal-Links. Namen sind nicht zwingend noetig, weil die Admins aus dem Link den finalen Kandidaten erstellen oder zuordnen koennen. Das konkrete Link-Limit kommt aus der Admin-Hauptkategorie.

Geplanter Zielzustand:

- Pro Hauptkategorie koennen ein bis zum konfigurierten Limit Links eingereicht werden.
- Doppelte Links innerhalb derselben Hauptkategorie werden blockiert.
- Leere Kategorien duerfen uebersprungen werden.
- Die Nominierungsoberflaeche wird wie ein Wizard aufgebaut: Kategorien links, Inhalt rechts, klare Weiter-Navigation.
- Clip-Einreichung wird aus dem Nominierungsformular entfernt oder deutlich getrennt, weil laut Feedback Clips in der Nominierungsphase eher Probleme verursachen.

Backendseitig speichert `Nomination` jetzt `CategoryGroupName` statt eine Tier-Kategorie als primaere Zuordnung. `CategoryId` bleibt als nullable Legacy-Feld erhalten. Twitch-Links werden best-effort ueber TwitchTracker angereichert; Nicht-Twitch-Links bleiben erlaubt und werden im Admin-Review manuell einem Tier zugeordnet.

### Vorbereitung

Nach der Nominierungsphase prueft das Team die Nominierungen, zaehlt aus und kontaktiert VTuber, ob sie die Nominierung annehmen. Erst danach werden Clip-Compilations relevant.

Geplanter Zielzustand:

- Admins sehen pro Review-Fall genug Signal, um Kandidaten zuzuordnen.
- Admins sehen Nominierungen gruppiert nach Hauptkategorie und Streamer-Identitaet.
- Das System zeigt Trackerstatus, durchschnittliche Viewer, Tier-Vorschlag und Tally der eindeutigen User.
- Beim Uebernehmen entsteht der Kandidat im vorgeschlagenen oder manuell gewaelten Tier.
- Final ausgewaehlte Nominierte bekommen einen Annahmestatus.
- Admins koennen pro Kandidat eine externe Clip-Compilation-URL pflegen.
- Es wird keine Upload-Infrastruktur fuer Videodateien gebaut.
- Ungelistete YouTube-Videos oder Twitch-Clips koennen verlinkt oder eingebettet werden.

Das haelt die Verantwortung fuer Hosting, Speicher, Copyright und Transcoding ausserhalb der App.

### Voting

Das Feedback zum Voting betrifft vor allem Bedienung und Sicherheit vor unvollstaendigen Abgaben.

Geplanter Zielzustand:

- Das Voting bleibt ein gefuehrter Picker mit Kategorienavigation.
- Es gibt einen klaren Weiter-Button unten rechts.
- Das Modal behaelt eine stabile Groesse, damit beim Kategorienwechsel nichts springt.
- Vor dem Absenden wird angezeigt, in welchen Kategorien noch keine Stimme gesetzt wurde.
- Nutzer koennen Votes bearbeiten, solange die Votingphase aktiv ist.

Backendseitig ist das Bearbeiten bereits angelegt: ein bestehendes Ballot wird beim erneuten Speichern ersetzt. Das sollte im UI bewusst als Feature kommuniziert werden.

### Review und Auswertung

Das Dokument nennt zwei interne Regeln:

- Eine Person kann maximal zwei Mal nominiert werden.
- Eine Person kann maximal ein Mal gewinnen.

Diese Regeln sollten nicht still im Public UI verschwinden, sondern als Admin-Guard und Review-Hilfe geplant werden.

Geplanter Zielzustand:

- Admins koennen final maximal vier Nominierte pro Unterkategorie festlegen.
- Streamer-Identitaet wird zentral ueber Plattform/Login modelliert, damit dieselbe Person ueber Kategorien hinweg erkannt werden kann.
- Admins sehen Warnungen oder Blocker, wenn eine Person zu oft nominiert oder als Gewinner markiert wird.
- Die App blockiert riskante finale Veroeffentlichungen oder verlangt eine bewusste Admin-Bestaetigung.
- Gewinner werden pro Unterkategorie bestimmt; bei Gleichstand oder Sonderfaellen entscheidet das Team manuell.

### Website Extras

Showacts und Sponsoren sind sinnvoll, aber nicht Teil der ersten Core-Workflow-Aenderung.

Folgeplanung:

- Showact-Bewerbungen werden als eigenes Website-Formular geplant, mit Admin-Liste zur Sichtung.
- Sponsoren werden admin-verwaltbar, inklusive Logo, Link, Sichtbarkeit, Sortierung und optionaler Tier-Stufe.
- Sponsorendarstellung kann als Landingpage-Banner, Karussell oder dedizierter Abschnitt umgesetzt werden.

## Priorisierte Umsetzung

### Phase 1: Public Nominierungs- und Voting-UX

Ziel: Der Public Flow entspricht dem Feedback: Nominierung auf Hauptkategorie, Voting weiter auf Tier-Kategorie.

Umsetzung:

- Nominierungsmodal zu einem Wizard umbauen.
- Pro Hauptkategorie bis zum konfigurierten `MaxNomineesPerUser`-Limit Link-Felder anbieten.
- Hauptkategorien als linke Navigation anzeigen.
- Hauptkategorien ohne Eingaben erlauben.
- Doppelte Links clientseitig validieren und Backend-Fehler sauber anzeigen.
- Clip-Einreichung aus dem Nominierungsflow entfernen oder als separaten, weniger prominenten Flow belassen.
- Voting-Wizard um Weiter-Button und fehlende-Stimmen-Hinweis erweitern.
- Vote-Bearbeitung sichtbar kommunizieren, wenn bereits gespeicherte Stimmen geladen wurden.

Akzeptanz:

- Eine Hauptkategorie kann mit einem oder mehreren Links bis zum konfigurierten Limit eingereicht werden.
- Doppelte Links in derselben Hauptkategorie werden blockiert.
- Ein leerer Kategorienblock verhindert nicht das Absenden anderer Kategorien.
- Voting kann gespeichert und in derselben Phase erneut geaendert werden.

### Phase 2: Admin-Vorbereitung und Clip-Compilation-Links

Ziel: Das Team kann aus Review-Signalen finale Nominierte vorbereiten und externe Compilations pflegen.

Umsetzung:

- Admin-Review um einen klaren Schritt "finale Nominierte auswaehlen" erweitern.
- Annahmestatus je finalem Nominee planen: offen, angefragt, angenommen, abgesagt.
- Externe Clip-Compilation-URL, Titel und Plattform je Kandidat oder Kandidaten-Kategorie-Zuordnung pflegen.
- Keine Videodateien speichern.
- Optional Embed-Vorschau fuer YouTube/Twitch anzeigen, wenn technisch sicher moeglich.

Akzeptanz:

- Admins koennen sehen, welche Kandidaten fuer eine Unterkategorie final vorbereitet sind.
- Externe Clip-Links erscheinen im Voting.
- Fehlende Clips blockieren die App nicht, werden aber sichtbar markiert.

### Phase 3: Review, Gewinner und Archiv

Ziel: Auswertung und Gewinnerdarstellung folgen den internen Regeln.

Umsetzung:

- Gewinner pro Unterkategorie verwalten.
- Guard fuer "eine Person gewinnt maximal ein Mal" einplanen.
- Konfigurierbare Regel "Gewinner braucht Clip-Link" einplanen; Standard blockiert Gewinner ohne gepflegte YouTube-/Twitch-Compilation.
- Guard oder Warnung fuer "eine Person maximal zwei Mal nominiert" einplanen.
- Gewinnerbilder im Archiv groesser und ruhiger darstellen.
- Clip-Compilation im Archiv anzeigen; Standard ist externer Link oder Embed, kein Upload.
- Countdown auf der Landingpage visuell groesser und prominenter gestalten.

Akzeptanz:

- Admins koennen Gewinner nicht versehentlich doppelt vergeben, ohne Warnung oder bewusste Bestaetigung.
- Admins koennen steuern, ob Gewinner ohne Clip-Link blockiert oder nur gewarnt werden.
- Archiv zeigt vorhandene Gewinner-Clips eingebettet an und bleibt bei fehlenden Clips stabil.
- Countdown ist auf Desktop und Mobile gut lesbar.

### Phase 4: Showacts und Sponsoren

Ziel: Website Extras werden admin-verwaltbar statt ueber externe Workarounds gepflegt.

Umsetzung:

- Showact-Bewerbungsformular als Public Feature umsetzen; Aktivierung laeuft ueber optionale Workflow-Einstellungen.
- Admin-Ansicht fuer Showact-Bewerbungen umsetzen, inklusive Status `pending`, `shortlisted`, `accepted`, `rejected` und Review-Notiz.
- Sponsorendatenmodell umsetzen: Name, Logo, URL, Tier, Sortierung, Sichtbarkeit, Saison.
- Sponsorverwaltung im Admin-Panel umsetzen und Sponsorendarstellung auf der Landingpage an `SponsorsVisible` koppeln.
- Public-Showact-Submit blockiert sauber, wenn Bewerbungen geschlossen sind, und nutzt den konfigurierbaren Admin-Hinweis.

Akzeptanz:

- Showact-Bewerbungen koennen ohne Google Form gesammelt werden.
- Sponsoren koennen ohne Codeaenderung pro Saison gepflegt und sortiert werden.
- Toggles fuer Showact-Bewerbungen und Sponsoren-Sichtbarkeit liegen im eigenen Modal fuer optionale Workflows.

## Interface- und Datenentscheidungen

### Beibehalten

- `CategoryId` bleibt die zentrale Einheit fuer Voting, Kandidaten und Gewinner.
- `GroupName` bleibt die Gruppierung fuer uebergeordnete Award-Bereiche.
- Die Nominierungs-API bleibt grundsaetzlich erhalten, nimmt aber `CategoryGroupName` als neues Zielfeld; `CategoryId` bleibt Legacy-Fallback.
- Die Voting-API bleibt grundsaetzlich erhalten.
- Wiederholtes Vote-Speichern bleibt erlaubt und wird als Bearbeiten behandelt.

### Erweitern

- Kandidaten oder Kandidaten-Kategorie-Zuordnungen brauchen externe Clip-Compilation-Metadaten, falls die vorhandene Clip-Zuordnung nicht ausreicht:
  - URL
  - Titel
  - Plattform
  - optionaler Embed-Status
- Admin-Review braucht Statusinformationen fuer final ausgewaehlte Nominierte.
- `Nomination` speichert Tracker-/Review-Metadaten: `ResolvedChannel`, `ResolvedPlatform`, `AvgViewers`, `SuggestedCategoryId`, `StreamerIdentityId`, `TrackerStatus`.
- `StreamerIdentity` wird als eigene Entity fuer Plattform/Login/Normalisierung eingefuehrt.
- Gewinnerverwaltung braucht Guards fuer interne Regeln, inklusive "maximal ein Gewinnerplatz" und "Clip-Link fuer Gewinner erforderlich".

### Nicht bauen

- Kein eigener Video-Upload.
- Kein Speichern von Videodateien.
- Kein paralleles Unterkategorienmodell neben `Category`.
- Kein verpflichtendes Komplett-Ausfuellen aller Kategorien.

## Offene Produktfragen

Diese Fragen muessen nicht vor Phase 1 beantwortet werden, sollten aber vor Phase 2 oder 3 geklaert sein:

- Wird der Annahmestatus pro Kandidat global oder pro Kategorie gepflegt?
- Soll eine abgesagte Person automatisch durch die naechste Review-Auswahl ersetzt werden koennen?
- Soll die "maximal zwei Nominierungen"-Regel hart blockieren oder nur warnen?
- Soll die "maximal ein Gewinner"-Regel hart blockieren oder Admin-Override erlauben?
- Werden Sponsor-Tiers oeffentlich benannt oder nur intern zur Sortierung genutzt?
- Welche Pflichtfelder braucht das Showact-Formular final?

## Test Plan

### Build und statische Checks

- `npm run build` in `/Users/azu/Desktop/VTubeAwards/frontend`
- `dotnet build Backend/Backend.csproj` in `/Users/azu/Desktop/VTubeAwards`

### Browserpruefung lokal

- Nominierung mit einem Link in einer Kategorie.
- Nominierung mit zwei Links in einer Kategorie.
- Nominierung mit drei Links in einer Kategorie.
- Doppelte Links in derselben Kategorie.
- Leere Kategorien ueberspringen.
- Voting-Kategorie wechseln.
- Weiter-Button im Voting verwenden.
- Fehlende-Stimmen-Hinweis vor dem Absenden pruefen.
- Vote speichern, erneut oeffnen, aendern und erneut speichern.
- Mobile Layout bei 360px, 390px und 768px ohne horizontales Overflow pruefen.

### API-Smoke-Checks

- `GET /api/public/overview`
- `GET /api/public/seasons/{year}/categories`
- `GET /api/public/seasons/{year}/me`
- `POST /api/public/nominations` mit authentifizierter Session.
- `POST /api/public/votes` mit authentifizierter Session.

## Umsetzungshinweise

- Phase 1 sollte moeglichst frontendlastig bleiben und bestehende Backend-Faehigkeiten nutzen.
- Wenn Datenmodell-Migrationen noetig werden, sollten sie erst mit Phase 2 eingefuehrt werden.
- Alle Public-UI-Aenderungen muessen gegen echte Backenddaten laufen, nicht gegen Demo-State.
- Fuer echte UI-Aenderungen reicht ein Build nicht aus; der Flow muss im Browser geprueft werden.
- Kleine Vue-Komponenten bevorzugen, besonders beim Umbau des Nominierungs- und Votingmodals.