# Scope v0.401 — Phase 4 Commerce (première release)

**Version cible** : v0.401 (X=4, Y=1)  
**Prérequis** : v0.303 taguée et mergée dans main  
**Objectif** : Marketplace catalogue complet, licences & droits, seller dashboard enrichi  
**Dernière mise à jour** : février 2026  
**Effort estimé** : 6-8 semaines de développement

---

## 1. Principe directeur

> **v0.401 = première release Phase 4 Commerce.**
>
> Trois axes principaux :
> 1. **Produits & Catalogue (Lot M1)** : CRUD produits enrichi, upload preview, images, métadonnées BPM/key
> 2. **Licences & Droits (Lot M2)** : Types de licences (écoute, personnelle, commerciale, exclusive), conditions
> 3. **Seller dashboard enrichi (Lot M3)** : Graphiques ventes, meilleurs produits, taux de conversion

---

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

### 2.1 Livré en v0.303

| Lot | Feature | Statut |
|-----|---------|--------|
| C2 | Chat appels WebRTC 1-to-1 (signalisation, CallButton, IncomingCallModal, ActiveCallBar) | ✅ |

### 2.2 Fondation existante (à enrichir)

| Domaine | Existant | À ajouter v0.401 |
|---------|----------|-------------------|
| **Marketplace** | CRUD produits basique, catalogue, panier, wishlist | Upload preview, images multi, BPM/key, catégories produits |
| **Licences** | Types basiques (streaming, personnelle, commerciale) | Conditions d'utilisation, contrat auto, historique licences |
| **Seller** | Stats ventes, liste produits (Lot F v0.202) | Graphiques évolution, meilleurs produits, taux conversion |

### 2.3 Composants techniques

| Composant | État | Action v0.401 |
|-----------|------|---------------|
| veza-backend-api | ✅ | Routes produits enrichies, licences, seller stats |
| apps/web | ✅ | CreateProductView enrichi, ProductDetailView, SellerDashboardView graphiques |
| Hyperswitch | ✅ | Inchangé (paiement réel → v0.402) |

---

## 3. Features IN SCOPE v0.401

### 3.1 Lot M1 — Produits & Catalogue

**Objectif** : Enrichir le catalogue produits (upload preview, images, métadonnées).  
**Effort** : M (4-5 jours)  
**Référence** : Module 7.1 (features 226-240)

| # | Feature | Tâche détaillée | Backend | Frontend | Critère de sortie |
|---|---------|-----------------|---------|----------|-------------------|
| M1.1 | **Upload preview** | Fichier démo/écoute pour produit | POST /marketplace/products/:id/preview | CreateProductView, ProductDetailView | Preview jouable sur fiche produit |
| M1.2 | **Images produit (multi)** | Plusieurs images par produit | Migration images, PUT /products/:id/images | Galerie images dans ProductDetailView | Carousel ou grille images |
| M1.3 | **BPM/Key dans produits** | Métadonnées musicales sur produits | Colonnes bpm, musical_key (ou réutilisation tracks) | Filtres marketplace par BPM/key | Filtrage fonctionnel |
| M1.4 | **Catégories produits** | Sample, beat, preset, pack | Enum ou table product_categories | Filtre catégories dans MarketplaceHome | Navigation par catégorie |
| M1.5 | **Description rich text** | Description produit formatée | Champ description (TEXT, sanitized) | Éditeur simple (bold, listes) | Description affichée formatée |

**Fichiers clés** :  
- Backend : `marketplace/service.go`, `routes_marketplace.go`, migrations  
- Frontend : `CreateProductView`, `ProductDetailView`, `MarketplaceHome`, `marketplaceService.ts`

---

### 3.2 Lot M2 — Licences & Droits

**Objectif** : Types de licences explicites, conditions, historique.  
**Effort** : M (3-4 jours)  
**Référence** : Module 7.2 (features 241-250)

| # | Feature | Tâche détaillée | Backend | Frontend | Critère de sortie |
|---|---------|-----------------|---------|----------|-------------------|
| M2.1 | **Types de licences** | Écoute, personnelle, commerciale, exclusive | Enum license_type, table product_licenses | LicenceCard avec types | Sélection licence à l'achat |
| M2.2 | **Conditions par licence** | Texte conditions d'utilisation | Champ license_terms par type | Affichage modal avant achat | Conditions visibles et acceptables |
| M2.3 | **Historique licences achetées** | GET /marketplace/licenses/mine | Table user_licenses ou orders+licenses | Page « Mes licences » ou section Purchases | Liste licences avec re-téléchargement |

**Fichiers clés** :  
- Backend : `marketplace/service.go`, migration product_licenses, user_licenses  
- Frontend : `LicenceCard`, `LicenceDetailsModal`, `PurchasesView` ou `LicensesView`

---

### 3.3 Lot M3 — Seller dashboard enrichi

**Objectif** : Graphiques, meilleurs produits, taux de conversion.  
**Effort** : M (3-4 jours)  
**Référence** : Module 7.4 (features 266-271)

| # | Feature | Tâche détaillée | Backend | Frontend | Critère de sortie |
|---|---------|-----------------|---------|----------|-------------------|
| M3.1 | **Graphiques évolution ventes** | Revenus par période (jour/semaine/mois) | GET /sell/stats/evolution (ou étendre /sell/stats) | Chart.js ou Recharts dans SellerDashboardView | Courbe ventes affichée |
| M3.2 | **Meilleurs produits** | Top 5-10 produits par ventes/revenus | GET /sell/stats/top-products | Section « Meilleurs produits » | Liste top produits |
| M3.3 | **Taux de conversion** | Vues vs achats (si tracking vues) | Agrégation si données disponibles | Affichage taux | Taux affiché ou « N/A » si pas de données |

**Fichiers clés** :  
- Backend : `commerce_service.go`, `sell_handlers.go`  
- Frontend : `SellerDashboardView`, `commerceService.ts`

---

## 4. Récapitulatif par lot

| Lot | Priorité | Effort | Dépendances |
|-----|----------|--------|-------------|
| M1 | Haute | M (4-5 j) | Aucune |
| M2 | Haute | M (3-4 j) | M1 (produits) |
| M3 | Moyenne | M (3-4 j) | Lot F (seller basique) |

**Ordre recommandé** : M1 → M2 → M3 (ou M1 et M3 en parallèle si équipes séparées).

---

## 5. Features HORS SCOPE v0.401

| Feature | Raison | Version cible |
|---------|--------|---------------|
| Paiement Hyperswitch réel (checkout) | Intégration complexe, seller mature requis | v0.402 |
| Seller dashboard complet (reviews, promotions) | Priorité moindre | v0.403 |
| Codes promo / réductions | Dépend checkout | v0.402 |
| Payout automatique (Stripe Connect) | Infra externe | v0.403 |
| Dispute / réclamation | Scope support | v0.403+ |

---

## 6. Migrations et schémas

| Migration | Description |
|-----------|-------------|
| 092 | product_previews (product_id, file_path, duration_sec, created_at) |
| 093 | product_images (product_id, url, sort_order, created_at) |
| 094 | product_licenses (product_id, license_type, price_cents, terms_text, created_at) |
| 095 | user_licenses (user_id, product_id, license_type, order_id, purchased_at) — si pas déjà couvert par orders |

*À valider selon schéma DB existant.*

---

## 7. Critères de livraison v0.401

- [ ] Lot M1 : Upload preview, images multi, BPM/key, catégories, description rich text
- [ ] Lot M2 : Types licences, conditions, historique licences achetées
- [ ] Lot M3 : Graphiques ventes, meilleurs produits, taux conversion
- [ ] Tests : `go test ./...` OK, `npm run build` OK
- [ ] Documentation : FEATURE_STATUS, PROJECT_STATE, CHANGELOG mis à jour

---

## 8. Checklist pré-merge

- [ ] Tous les lots IN SCOPE terminés ou reportés (avec ticket)
- [ ] Pas de régression sur v0.303
- [ ] SCOPE_CONTROL.md référence V0_401_RELEASE_SCOPE.md
- [ ] FEATURE_STATUS.md mis à jour
- [ ] CHANGELOG v0.401
- [ ] MSW handlers pour nouvelles routes
- [ ] Stories Storybook pour composants modifiés (Loading, Error, Empty selon STORYBOOK_CONTRACT)

---

## 9. Transition vers v0.402

À l'issue de v0.401 (taguée) :
- Marketplace catalogue mature
- Prochaine version : **v0.402** — Checkout Hyperswitch production-ready, codes promo
- Document de scope : [V0_402_RELEASE_SCOPE.md](V0_402_RELEASE_SCOPE.md)

---

## Références

- [V0_303_RELEASE_SCOPE.md](V0_303_RELEASE_SCOPE.md) — Version précédente
- [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
- [veza_full_features_list.md](archive/root-md/veza_full_features_list.md) — Module 7 Marketplace