docs(v0.401): add V0_401_RELEASE_SCOPE and PLAN_V0_401_IMPLEMENTATION

- V0_401_RELEASE_SCOPE: Phase 4 Commerce (M1 produits, M2 licences, M3 seller) - PLAN_V0_401_IMPLEMENTATION: phases 0-4, diagramme Mermaid, commits suggérés
2026-02-22 14:02:24 +01:00 · 2026-02-22 14:02:24 +01:00 · 0b9f5609ab
commit 0b9f5609ab
parent 8644ed6d5e
2 changed files with 292 additions and 0 deletions
--- a/docs/PLAN_V0_401_IMPLEMENTATION.md
+++ b/docs/PLAN_V0_401_IMPLEMENTATION.md
@ -0,0 +1,112 @@
+# Plan d'implémentation v0.401 — Phase 4 Commerce
+
+**Version cible** : v0.401  
+**Objectif** : Marketplace catalogue complet, licences & droits, seller dashboard enrichi  
+**Référence** : [V0_401_RELEASE_SCOPE.md](V0_401_RELEASE_SCOPE.md)  
+**Dernière mise à jour** : février 2026
+
+---
+
+## Diagramme de dépendances v0.401
+
+```mermaid
+flowchart TD
+    subgraph Backend [veza-backend-api]
+        M1_B[M1 Migrations + routes produits]
+        M2_B[M2 Tables licences + routes]
+        M3_B[M3 Routes /sell/stats enrichies]
+    end
+    subgraph Frontend [apps/web]
+        M1_F[CreateProductView ProductDetailView MarketplaceHome]
+        M2_F[LicenceCard LicenceDetailsModal LicensesView]
+        M3_F[SellerDashboardView graphiques]
+    end
+    M1_B --> M1_F
+    M1_B --> M2_B
+    M2_B --> M2_F
+    M3_B --> M3_F
+```
+
+---
+
+## Phase 0 — Vérification préalable
+
+| # | Tâche | Fichiers | Commit suggéré |
+|---|-------|----------|----------------|
+| 0.1 | Vérifier schéma DB marketplace existant | `veza-backend-api/migrations/` | — |
+| 0.2 | Vérifier routes marketplace/sell actuelles | `routes_marketplace.go`, `sell_handlers.go` | — |
+| 0.3 | Vérifier CreateProductView, SellerDashboardView | `apps/web/src/components/` | — |
+
+---
+
+## Phase 1 — Lot M1 (Produits & Catalogue)
+
+| # | Tâche | Fichiers | Commit suggéré |
+|---|-------|----------|----------------|
+| 1.1 | Migration product_previews | `migrations/092_*.sql` | `feat(marketplace): add product_previews migration` |
+| 1.2 | Migration product_images | `migrations/093_*.sql` | `feat(marketplace): add product_images migration` |
+| 1.3 | Route POST /products/:id/preview | `marketplace/service.go`, handlers | `feat(marketplace): add product preview upload` |
+| 1.4 | BPM/Key, catégories dans produits | Migration ou alter, service | `feat(marketplace): add bpm, musical_key, category to products` |
+| 1.5 | CreateProductView : upload preview, catégories | `CreateProductView.tsx` | `feat(marketplace): enrich CreateProductView` |
+| 1.6 | ProductDetailView : galerie images, preview jouable | `ProductDetailView.tsx` | `feat(marketplace): add images and preview to ProductDetailView` |
+| 1.7 | MarketplaceHome : filtres BPM, key, catégorie | `MarketplaceHome.tsx`, `marketplaceService.ts` | `feat(marketplace): add filters to MarketplaceHome` |
+
+**Validation** : `go test ./...`, `npm run build`, test manuel upload preview.
+
+---
+
+## Phase 2 — Lot M2 (Licences & Droits)
+
+| # | Tâche | Fichiers | Commit suggéré |
+|---|-------|----------|----------------|
+| 2.1 | Migration product_licenses, user_licenses | `migrations/094_*.sql`, `095_*.sql` | `feat(marketplace): add licenses migrations` |
+| 2.2 | Service licences (types, conditions) | `marketplace/service.go` | `feat(marketplace): add license types and terms` |
+| 2.3 | Route GET /marketplace/licenses/mine | Handler + service | `feat(marketplace): add user licenses endpoint` |
+| 2.4 | LicenceCard : types, conditions | `LicenceCard.tsx`, `LicenceDetailsModal.tsx` | `feat(marketplace): enrich LicenceCard with types` |
+| 2.5 | Page ou section « Mes licences » | `LicensesView` ou `PurchasesView` | `feat(marketplace): add LicensesView` |
+
+**Validation** : Achat (ou mock) → licence enregistrée → re-téléchargement visible.
+
+---
+
+## Phase 3 — Lot M3 (Seller dashboard enrichi)
+
+| # | Tâche | Fichiers | Commit suggéré |
+|---|-------|----------|----------------|
+| 3.1 | GET /sell/stats/evolution (revenus par période) | `commerce_service.go`, `sell_handlers.go` | `feat(seller): add stats evolution endpoint` |
+| 3.2 | GET /sell/stats/top-products | Idem | `feat(seller): add top products endpoint` |
+| 3.3 | SellerDashboardView : graphique évolution | Recharts ou Chart.js | `feat(seller): add sales evolution chart` |
+| 3.4 | Section « Meilleurs produits » | `SellerDashboardView.tsx` | `feat(seller): add top products section` |
+| 3.5 | Taux de conversion (si données) | Backend + frontend | `feat(seller): add conversion rate` |
+
+**Validation** : Données réelles ou MSW → graphiques affichés.
+
+---
+
+## Phase 4 — Finalisation
+
+| # | Tâche | Fichiers | Commit suggéré |
+|---|-------|----------|----------------|
+| 4.1 | MSW handlers pour nouvelles routes | `apps/web/src/mocks/handlers.ts` | `test(marketplace): add MSW handlers for v0.401` |
+| 4.2 | Stories Storybook (Loading, Error, Empty) | Composants modifiés | `feat(marketplace): add stories for v0.401 components` |
+| 4.3 | Mise à jour CHANGELOG v0.401 | `CHANGELOG.md` | `docs: update CHANGELOG for v0.401` |
+| 4.4 | Vérification SCOPE_CONTROL, FEATURE_STATUS | — | — |
+
+---
+
+## Ordre d'exécution recommandé
+
+1. **Phase 0** — Vérification (30 min)
+2. **Phase 1** — M1 Produits & Catalogue (4-5 j)
+3. **Phase 2** — M2 Licences (3-4 j)
+4. **Phase 3** — M3 Seller enrichi (3-4 j)
+5. **Phase 4** — Finalisation (0.5-1 j)
+
+---
+
+## Références
+
+- [V0_401_RELEASE_SCOPE.md](V0_401_RELEASE_SCOPE.md) — Scope détaillé
+- [veza-backend-api/internal/core/marketplace/](../veza-backend-api/internal/core/marketplace/) — Service marketplace
+- [apps/web/src/components/seller/](../apps/web/src/components/seller/) — Composants seller
+- [STORYBOOK_CONTRACT.md](../apps/web/docs/STORYBOOK_CONTRACT.md) — Contrat Storybook
--- a/docs/V0_401_RELEASE_SCOPE.md
+++ b/docs/V0_401_RELEASE_SCOPE.md
@ -0,0 +1,180 @@
+# 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 :
+- Marketplace catalogue mature
+- Prochaine version : **v0.402** — Paiement Hyperswitch réel, checkout, codes promo
+- Document de scope : `V0_402_RELEASE_SCOPE.md` (à créer après tag v0.401)
+
+---
+
+## 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