veza/docs/archive/V0_501_RELEASE_SCOPE.md

> **ARCHIVED — Completed 2026-02-22**

# V0_501_RELEASE_SCOPE.md — Phase 5 : Streaming & Cloud

**Phase** : 5 — Streaming & Cloud (redéfinie, ex-Education/Gear)
**Version précédente** : v0.404 (Stabilisation post-audit)
**Version suivante** : v0.502
**Prérequis** : v0.404 taguée (sécurité critique résolue, stream server intégré, CI/CD fonctionnel)

---

## 1. Contexte & Redéfinition de la Phase 5

### Pourquoi redéfinir ?

La Phase 5 était initialement « Education / Gear ». Le module Education a été **supprimé** (voir FEATURE_STATUS.md : dossier supprimé, 0/30 features). La Phase 5 doit être redéfinie autour des axes stratégiques restants.

### Choix stratégique

Veza est une **plateforme audio**. Le streaming (HLS, live) est le différenciateur produit. Après la stabilisation v0.404 (qui intègre le stream server et active HLS), la Phase 5 doit consolider cette fondation et ajouter les fonctionnalités cloud qui font de Veza un outil de travail pour les musiciens, pas seulement une vitrine.

### Nouvelle définition Phase 5

> **Phase 5 — Streaming & Cloud** : Rendre le streaming audio production-ready, ajouter le stockage cloud pour les musiciens, et compléter le module Gear.

### Plan Phase 5 complet

| Version | Focus | Lots |
|---------|-------|------|
| **v0.501** | HLS production + Cloud storage MVP + Gear avancé | S1, C1, G1 |
| **v0.502** | Live streaming (Go Live) + Traitement audio | S2, A1 |
| **v0.503** | Cloud avancé + Collaboration fichiers | C2, C3 |

---

## 2. Périmètre v0.501

### Lot S1 — HLS Streaming production-ready

**Prérequis** : v0.404 INT-02 terminé (stream server intégré, gRPC connecté, 1 flux E2E validé).

Le Lot S1 prend le relais pour rendre le streaming fiable et performant en production.

| ID | Feature | Frontend | Backend | Effort |
|----|---------|----------|---------|--------|
| S1.1 | **Transcoding adaptatif** — générer automatiquement 3 variantes HLS (128k, 256k, 320k) à l'upload. Manifest master.m3u8 avec les 3 qualités. | Sélecteur qualité dans le player | Stream server : FFmpeg pipeline multi-bitrate, stockage segments | L |
| S1.2 | **Playback adaptatif (ABR)** — le player sélectionne automatiquement la qualité selon la bande passante. Fallback progressif si un segment échoue. | hls.js intégré au player avec ABR activé | Endpoint `/hls/:track_id/master.m3u8` avec variantes | M |
| S1.3 | **Cache CDN segments HLS** — configurer des headers de cache sur les segments (.ts). Redis cache pour les manifests. TTL configurable. | — | Stream server : headers `Cache-Control`, Redis cache manifest | M |
| S1.4 | **Monitoring streaming** — métriques Prometheus : latence transcodage, erreurs segments, connexions actives, bande passante servie. Dashboard Grafana dédié. | — | Stream server : `/metrics` endpoint, compteurs Prometheus | M |
| S1.5 | **Waveform generation** — générer un fichier waveform JSON à l'upload (FFmpeg audiowaveform). Affichage dans le player et dans TrackDetailPage. | Composant WaveformDisplay, intégration player progress bar | Backend : job async waveform generation, endpoint GET `/tracks/:id/waveform` | L |

### Lot C1 — Cloud Storage MVP

> Permettre aux musiciens de stocker et organiser leurs fichiers audio dans un espace cloud personnel.

| ID | Feature | Frontend | Backend | Effort |
|----|---------|----------|---------|--------|
| C1.1 | **Migration stockage** — table `user_files` (id, user_id, filename, path, size_bytes, mime_type, folder_id, created_at). Table `user_folders` (id, user_id, name, parent_id). | — | Migration, modèles UserFile + UserFolder | S |
| C1.2 | **Upload fichiers cloud** — `POST /cloud/files` (multipart), validation type (audio/*, zip, midi, project files). Limite 500MB/fichier, quota 5GB/user (configurable). | Dropzone upload dans CloudPage | Handler, service, stockage S3-compatible (MinIO en dev) | L |
| C1.3 | **File browser** — arborescence de dossiers, navigation, renommage, déplacement, suppression. Tri par nom, date, taille. | CloudBrowserView : tree sidebar + file list + breadcrumbs | CRUD endpoints : `GET/POST/PUT/DELETE /cloud/folders`, `GET /cloud/files` (avec filtres folder_id, sort) | L |
| C1.4 | **Prévisualisation audio** — lecture inline des fichiers audio depuis le cloud sans les ajouter à la bibliothèque publique. Player minimal intégré au file browser. | Mini player inline dans CloudBrowserView | `GET /cloud/files/:id/stream` (auth, range requests) | M |
| C1.5 | **Publier depuis le cloud** — bouton « Publier comme track » qui crée un track à partir d'un fichier cloud, sans re-upload. Lien symbolique vers le fichier existant. | Bouton dans CloudBrowserView → modale CreateTrack pré-remplie | `POST /cloud/files/:id/publish` → crée un track lié au fichier | M |

### Lot G1 — Gear avancé

> Le module Gear (inventaire équipement) est partiellement implémenté (CRUD basique). Le compléter.

| ID | Feature | Frontend | Backend | Effort |
|----|---------|----------|---------|--------|
| G1.1 | **Catégorisation** — catégories prédéfinies (instruments, microphones, interfaces, DAW, plugins, accessoires). Filtrage par catégorie. | Select catégorie dans GearForm, filtres dans GearListView | Champ `category` dans gear, migration, enum validation | S |
| G1.2 | **Images équipement** — upload photo par item (max 3). Affichage galerie dans le détail. | Upload image dans GearForm, galerie dans GearDetailView | `POST /inventory/gear/:id/images`, stockage, migration `gear_images` | M |
| G1.3 | **Gear sur profil public** — section « Mon setup » sur le profil public, affichant les items marqués comme publics. | Section GearShowcase dans ProfilePage | `GET /users/:username/gear` (items publics), champ `is_public` sur gear | M |
| G1.4 | **Recherche Gear** — recherche textuelle dans le nom et la description des items. | SearchBar dans GearListView | Intégration au SearchService existant (type `gear`) | S |

---

## 3. Périmètre HORS SCOPE v0.501

| Élément | Raison | Version cible |
|---------|--------|---------------|
| Live streaming (Go Live, RTMP) | Nécessite infrastructure RTMP, complexité élevée | v0.502 Lot S2 |
| Collaboration fichiers cloud (partage, commentaires) | Dépend de C1 stabilisé | v0.503 Lot C2 |
| Versioning fichiers cloud | Feature avancée | v0.503 Lot C3 |
| Traitement audio (normalisation, trim, fade) | Dépend du stream server stabilisé | v0.502 Lot A1 |
| Gamification | TIER 2, hors priorité MVP | v0.801+ |
| Web3 / tokens | TIER 2, hors priorité MVP | v0.901+ |
| Migration React 19 | Évaluation en v0.501, migration en v0.602 | v0.602 |

---

## 4. Prérequis techniques

| Prérequis | Source | Statut attendu à l'entrée v0.501 |
|-----------|--------|-----------------------------------|
| Stream server intégré (gRPC fonctionnel) | v0.404 INT-02 | ✅ Fait |
| HLS activé (`HLS_STREAMING=true`) | v0.404 INT-02 | ✅ Fait |
| Pipeline CD fonctionnel | v0.404 SEC-01 | ✅ Fait |
| Auth stream token endpoint | v0.404 SEC-03 | ✅ Fait |
| Staging compose complet | v0.404 INF-07 | ✅ Fait |
| Object storage (MinIO/S3) | **Nouveau** — configurer en v0.501 | À faire |

**Note** : Le Lot C1 introduit MinIO (S3-compatible) pour le stockage de fichiers. C'est la **seule nouvelle dépendance infra** de v0.501. En production, remplaçable par AWS S3, GCS, ou Cloudflare R2.

---

## 5. Migrations prévues

| # | Table | Description |
|---|-------|-------------|
| 101 | `user_folders` | Dossiers cloud utilisateur (id, user_id, name, parent_id, created_at) |
| 102 | `user_files` | Fichiers cloud (id, user_id, folder_id, filename, path, size_bytes, mime_type, created_at) |
| 103 | `tracks` (alter) | Ajouter `waveform_url` (nullable, chemin vers waveform JSON) |
| 104 | `gear` (alter) | Ajouter `category` (enum), `is_public` (bool default false) |
| 105 | `gear_images` | Images équipement (id, gear_id, image_url, position, created_at) |
| 106 | `user_storage_quotas` | Quotas stockage (user_id, max_bytes, used_bytes) |

---

## 6. Nouvelles routes API

### Streaming (Lot S1)

| Méthode | Route | Auth | Description |
|---------|-------|------|-------------|
| GET | `/hls/:track_id/master.m3u8` | Stream token | Manifest HLS multi-bitrate |
| GET | `/tracks/:id/waveform` | Optionnel | Waveform JSON |

### Cloud (Lot C1)

| Méthode | Route | Auth | Description |
|---------|-------|------|-------------|
| GET | `/cloud/files` | Requis | Lister fichiers (filtres: folder_id, sort, page) |
| POST | `/cloud/files` | Requis | Upload fichier (multipart) |
| GET | `/cloud/files/:id` | Requis (owner) | Détail fichier |
| DELETE | `/cloud/files/:id` | Requis (owner) | Supprimer fichier |
| GET | `/cloud/files/:id/stream` | Requis (owner) | Stream audio (range requests) |
| POST | `/cloud/files/:id/publish` | Requis (owner) | Publier comme track |
| GET | `/cloud/folders` | Requis | Lister dossiers |
| POST | `/cloud/folders` | Requis | Créer dossier |
| PUT | `/cloud/folders/:id` | Requis (owner) | Renommer/déplacer dossier |
| DELETE | `/cloud/folders/:id` | Requis (owner) | Supprimer dossier (+ contenu) |
| GET | `/cloud/quota` | Requis | Quota utilisateur |

### Gear (Lot G1)

| Méthode | Route | Auth | Description |
|---------|-------|------|-------------|
| POST | `/inventory/gear/:id/images` | Requis (owner) | Upload image équipement |
| DELETE | `/inventory/gear/:id/images/:img_id` | Requis (owner) | Supprimer image |
| GET | `/users/:username/gear` | Optionnel | Gear public d'un utilisateur |

---

## 7. Nouvelles pages/composants frontend

| Page/Composant | Route | Lot |
|----------------|-------|-----|
| CloudPage | `/cloud` | C1 |
| CloudBrowserView | — (dans CloudPage) | C1 |
| CloudUploadModal | — | C1 |
| CloudFolderTree | — | C1 |
| CloudFilePreview (mini player) | — | C1 |
| WaveformDisplay | — (dans player + TrackDetailPage) | S1 |
| QualitySelector | — (dans player) | S1 |
| GearCategoryFilter | — (dans GearListView) | G1 |
| GearImageGallery | — (dans GearDetailView) | G1 |
| GearShowcase | — (dans ProfilePage) | G1 |

---

## 8. Estimation d'effort

| Lot | Features | Effort total estimé | Répartition |
|-----|----------|--------------------| ------------|
| S1 — HLS production | 5 | ~3 semaines | 60% backend/stream server, 40% frontend |
| C1 — Cloud MVP | 5 | ~3 semaines | 50% backend, 30% frontend, 20% infra (MinIO) |
| G1 — Gear avancé | 4 | ~1 semaine | 50/50 |

**Durée totale estimée v0.501** : ~7 semaines (parallélisable à ~5 semaines si S1 et C1 avancent en parallèle)

---

## 9. Critères de succès v0.501

| Critère | Seuil |
|---------|-------|
| Un track uploadé est jouable en HLS multi-bitrate | 3 qualités sélectionnables |
| ABR fonctionne (bascule automatique de qualité) | Vérifié sur connexion throttlée |
| Waveform visible dans le player | Sur 100% des nouveaux tracks |
| Cloud : upload + navigation + preview + publish fonctionnels | Flux E2E validé |
| Quota stockage respecté | Upload refusé au-delà du quota |
| Gear : catégories, images, profil public | Visible sur `/u/:username` |
| Aucune régression sur les 14 features E2E de v0.404 | Smoke test staging |
| Score maturité produit estimé | ≥ 5/10 (vs 3/10 post-audit) |

---

## 10. Risques v0.501

| Risque | Probabilité | Impact | Mitigation |
|--------|-------------|--------|-----------|
| FFmpeg transcoding lent sur gros fichiers | Élevée | UX dégradée (upload → playback long) | Job async + notification quand prêt. Progress bar. Limiter à 200MB initialement. |
| MinIO setup complexe en prod | Moyenne | Retard infra | Commencer avec stockage local en dev, MinIO en staging, S3 en prod. Abstraction storage interface. |
| Quota stockage contournable | Faible | Coûts imprévus | Vérification atomique (transaction DB) avant tout upload. Rate limiting sur upload. |
| Cloud browser UX complexe | Moyenne | Feature sous-utilisée | MVP minimaliste (flat list + 1 niveau dossiers). Tree view en v0.503. |

---

## 11. Impact sur les métriques globales

| Métrique | Avant v0.501 | Après v0.501 (estimé) |
|----------|-------------|----------------------|
| Features E2E fonctionnelles | 14 | ~22 (+8) |
| TIER 0 complétude | 44% (83/190) | ~49% (93/190) |
| Score maturité produit | 3/10 | ~5/10 |
| Module 4 (Streaming) | 36% | ~55% |
| Module 9 (Cloud) | 0% | ~30% |
| Module 11 (Gear) | ~40% | ~60% |

---

## 12. Référence

| Document | Rôle |
|----------|------|
| [V0_404_RELEASE_SCOPE.md](archive/V0_404_RELEASE_SCOPE.md) | Version précédente (stabilisation, archivée) |
| [AUDIT_TECHNIQUE_2026-02-22.md](../AUDIT_TECHNIQUE_2026-02-22.md) | Audit de référence |
| [PLAN_ACTION_AUDIT.md](PLAN_ACTION_AUDIT.md) | Plan d'action détaillé |
| [SCOPE_CONTROL.md](SCOPE_CONTROL.md) | Processus anti-scope-creep |
| [FEATURE_STATUS.md](FEATURE_STATUS.md) | Statut features |

---

## 13. Roadmap Phase 5 complète (preview)

```
v0.501 (ce document)
├── S1 — HLS production (transcoding, ABR, cache, monitoring, waveform)
├── C1 — Cloud MVP (upload, browser, preview, publish)
└── G1 — Gear avancé (catégories, images, profil public)

v0.502
├── S2 — Live streaming (Go Live RTMP → HLS, chat live, modération)
└── A1 — Traitement audio (normalisation, trim, fade-in/out, bounce)

v0.503
├── C2 — Cloud partage (partager fichier/dossier, permissions, lien public)
└── C3 — Cloud avancé (versioning fichiers, historique, restore, corbeille)
```