# Scope v0.202 — Phase 2 Contenu (suite)

**Version cible** : v0.202 (X=2, Y=2)  
**Prérequis** : v0.201 taguée et mergée dans main  
**Objectif** : Phase 2 Contenu — Recherche avancée, Analytics créateur, Seller dashboard, Player, Queue  
**Dernière mise à jour** : 20 février 2026  
**Effort estimé** : 5-7 semaines de développement

---

## 1. Principe directeur

> **v0.202 = suite Phase 2 (Contenu) après v0.201.**
>
> Cinq axes principaux :
> 1. **Recherche avancée (Lot G)** : Filtres, tri, autocomplete, facettes, historique
> 2. **Analytics créateur (Lot H)** : Stats, graphiques, export
> 3. **Seller dashboard (Lot F)** : Stats ventes, liste produits
> 4. **Player avancé (Lot C)** : Crossfade, gapless, PiP
> 5. **Queue avancée (Lot D)** : Autoplay, queue collaborative

---

## 2. Contexte — État post v0.201

### 2.1 Livré en v0.201

| Lot | Feature | Statut |
|-----|---------|--------|
| E1 | BPM | ✅ |
| E2 | Musical key | ✅ |
| E3 | Lyrics | ✅ |
| E4 | Tags suggérés | ✅ |

### 2.2 Fondation existante (à enrichir)

| Domaine | Existant | À ajouter v0.202 |
|---------|----------|-------------------|
| **Recherche tracks** | `TrackSearchService`, GET /tracks/search, filtres BPM/durée/genre/format/date, tri (popularity, title, created_at) | musical_key, autocomplete, unification search unifiée, historique |
| **Search unifiée** | GET /search (q, type=track|user|playlist), SearchService | Filtres, tri, pagination |
| **Analytics** | Routes /api/v1/analytics/*, playback_analytics | Route créateur, graphiques, export |
| **Player** | MediaSession, usePlayer | Crossfade, gapless, PiP |
| **Queue** | Queue sync, PlayerQueue | Autoplay, queue collaborative |

---

## 3. Features IN SCOPE v0.202

### 3.1 Lot G — Recherche avancée (priorité haute)

**Objectif** : Enrichir la recherche existante.  
**Effort** : L (5-7 jours)  
**Référence** : Module 11 (veza_full_features_list)

| # | Feature | Tâche détaillée | Backend | Frontend | Critère de sortie |
|---|---------|-----------------|---------|----------|-------------------|
| G1 | **Filtres recherche** | musical_key manquant ; tags déjà dans TrackSearchParams | Ajouter `musical_key` à TrackSearchParams + handler | Vérifier UI SearchPage/TrackSearch utilise tous les filtres | Filtres appliqués, résultats mis à jour |
| G2 | **Tri avancé** | Tri pertinence, date, popularité, alphabétique | Déjà : sort_by, sort_order. Ajouter "relevance" si full-text | Dropdown tri dans SearchPage | Tri fonctionnel |
| G3 | **Autocomplete** | Suggestions pendant la frappe | Route GET /search/suggestions?q=… (tracks, users, playlists) ou extension GET /search avec limit=5 | Input avec dropdown debounced | Suggestions affichées, clic → recherche |
| G4 | **Recherche par type** | Tracks, artistes, playlists, utilisateurs | SearchService : param `type` existant. Vérifier cohérence | Onglets/facettes dans SearchPage | Résultats par catégorie |
| G5 | **Historique recherche** | Mémoriser les dernières recherches | Optionnel : table search_history. Sinon localStorage | Section "Récent" | Dernières recherches cliquables |

**Fichiers clés** :  
- Backend : `track_search_service.go`, `search_service.go`, `search_handlers.go`, `routes_search.go`, `routes_tracks.go`  
- Frontend : `TrackSearch.tsx`, `TrackSearchFilters`, `trackSearchService.ts`, `SearchPage`

---

### 3.2 Lot H — Analytics créateur (priorité haute)

**Objectif** : Dashboard analytics pour créateurs.  
**Effort** : L (5-7 jours)  
**Référence** : Module 12.1

| # | Feature | Tâche détaillée | Backend | Frontend | Critère de sortie |
|---|---------|-----------------|---------|----------|-------------------|
| H1 | **Stats d'écoute** | Plays par track, période, durée moyenne | Agrégation playback_analytics, route GET /analytics/creator/stats | Page /analytics ou section créateur | Chiffres affichés |
| H2 | **Graphiques** | Évolution plays, top tracks | Route GET /analytics/creator/charts | Charts (recharts ou équivalent) | Graphiques lisibles |
| H3 | **Taux de complétion** | % d'écoute complète par track | Calcul backend (plays complètes / total) | Affichage dans dashboard | Métrique visible |
| H4 | **Export données** | Export CSV/JSON des stats | Route GET /analytics/creator/export?format=csv|json | Bouton export | Fichier téléchargé |

**Fichiers clés** :  
- Backend : `playback_analytics_handler.go`, `routes`, modèles analytics  
- Frontend : Page Analytics, composants charts, export

---

### 3.3 Lot F — Seller dashboard (priorité moyenne)

**Objectif** : Dashboard vendeur fonctionnel.  
**Effort** : M (3-4 jours)  
**Référence** : Module 7.4

| # | Feature | Tâche détaillée | Backend | Frontend | Critère de sortie |
|---|---------|-----------------|---------|----------|-------------------|
| F1 | **Stats ventes** | Nombre ventes, revenus, période | Route GET /sell/stats ou agrégation Hyperswitch/marketplace | Page /sell | Chiffres affichés |
| F2 | **Liste produits** | Tracks/albums en vente par l'utilisateur | Extension catalogue existant | Liste dans seller dashboard | Produits listés |

---

### 3.4 Lot C — Player avancé (priorité moyenne)

**Objectif** : Améliorer l'expérience d'écoute.  
**Effort** : M (2-4 jours)  
**Référence** : Module 4.1

| # | Feature | Tâche détaillée | Backend | Frontend | Critère de sortie |
|---|---------|-----------------|---------|----------|-------------------|
| C1 | **Crossfade** | Transition en fondu entre tracks | N/A | Logique player (gain, overlap) | Transition fluide 1-10s configurable |
| C2 | **Gapless playback** | Lecture sans silence entre tracks | N/A | Préchargement audio, Web Audio API ou HTMLMediaElement | Pas de coupure |
| C3 | **PiP** | Picture-in-Picture (si supporté) | N/A | Media Session + PiP API (document.pictureInPictureEnabled) | Fenêtre flottante |

**Fichiers clés** : `GlobalPlayer.tsx`, `AudioPlayer.tsx`, `usePlayer.ts`, `playerStore.ts`

---

### 3.5 Lot D — Queue avancée (priorité basse)

**Objectif** : Queue collaborative et autoplay.  
**Effort** : M (3-4 jours)  
**Référence** : Module 4.2

| # | Feature | Tâche détaillée | Backend | Frontend | Critère de sortie |
|---|---------|-----------------|---------|----------|-------------------|
| D1 | **Queue collaborative** | Partager queue en session | Modèle session queue partagée, routes queue | UI partage | Plusieurs users, même queue |
| D2 | **Autoplay** | Recommandations quand queue vide | Route GET /recommendations ou extension playlists | Section "À écouter ensuite" | Suggestions, ajout 1 clic |

---

## 4. Récapitulatif par lot

| Lot | Nom | Priorité | Effort | Features |
|-----|-----|----------|--------|----------|
| **G** | Recherche avancée | Haute | L | 5 |
| **H** | Analytics créateur | Haute | L | 4 |
| **F** | Seller dashboard | Moyenne | M | 2 |
| **C** | Player avancé | Moyenne | M | 3 |
| **D** | Queue avancée | Basse | M | 2 |
| | **TOTAL** | | **16-27j** | **16** |

---

## 5. Features HORS SCOPE v0.202

| Feature | Raison | Version cible |
|---------|--------|---------------|
| Recherche phonétique, booléenne | Complexité | v0.203+ |
| Collaborative filtering | Nécessite historique riche | v0.203+ |
| Social Trending API | Dépend recommandations | v0.203+ |
| 2FA SMS, Passkeys | v0.104 dédié | v0.104 |
| Go Live vidéo | v0.703 | v0.703 |

---

## 6. Ordre de livraison recommandé

| Semaine | Lots | Activités |
|---------|------|-----------|
| **S1** | G (Recherche) | G1–G5 : filtres musical_key, tri, autocomplete, facettes, historique |
| **S2** | H (Analytics) | H1–H4 : stats, graphiques, taux complétion, export |
| **S3** | F (Seller) | F1–F2 : stats ventes, liste produits |
| **S4** | C (Player) | C1–C3 : crossfade, gapless, PiP |
| **S5** | D (Queue) | D1–D2 : autoplay, queue collaborative |
| **S6** | Stabilisation | Tests, docs, polish |

---

## 7. Branche et workflow

- **Branche** : `release/v0.202`
- **Format commit** : `feat(scope): description` (ex: `feat(search): add musical_key filter`)
- **Référence scope** : [SCOPE_CONTROL.md](SCOPE_CONTROL.md) → v0.202
- **PR** : `gh pr create --base main --head release/v0.202 --title "Release v0.202"`

---

## 8. Critères de stabilité v0.202

### 8.1 Build & compilation
- [ ] `go build ./...` — 0 erreur
- [ ] `npm run build` — 0 erreur
- [ ] `npx tsc --noEmit` — 0 erreur

### 8.2 Tests
- [ ] `go test ./...` — pas de régression
- [ ] `npm test -- --run` — pas de régression
- [ ] E2E : recherche, analytics, seller (si applicable)

### 8.3 Documentation
- [ ] FEATURE_STATUS.md mis à jour
- [ ] CHANGELOG v0.202
- [ ] MSW handlers pour nouveaux endpoints

---

## Références

- [V0_201_RELEASE_SCOPE.md](V0_201_RELEASE_SCOPE.md) — Version précédente (Lot E livré)
- [SCOPE_CONTROL.md](SCOPE_CONTROL.md) — Processus anti-scope-creep
- [FEATURE_STATUS.md](FEATURE_STATUS.md) — Statut des features
- [PROJECT_STATE.md](PROJECT_STATE.md) — État actuel du projet