From 0b9f5609abd86636b530aab899f582fbaef54285 Mon Sep 17 00:00:00 2001 From: senke Date: Sun, 22 Feb 2026 14:02:24 +0100 Subject: [PATCH] docs(v0.401): add V0_401_RELEASE_SCOPE and PLAN_V0_401_IMPLEMENTATION MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- docs/PLAN_V0_401_IMPLEMENTATION.md | 112 ++++++++++++++++++ docs/V0_401_RELEASE_SCOPE.md | 180 +++++++++++++++++++++++++++++ 2 files changed, 292 insertions(+) create mode 100644 docs/PLAN_V0_401_IMPLEMENTATION.md create mode 100644 docs/V0_401_RELEASE_SCOPE.md diff --git a/docs/PLAN_V0_401_IMPLEMENTATION.md b/docs/PLAN_V0_401_IMPLEMENTATION.md new file mode 100644 index 000000000..4ade7de15 --- /dev/null +++ 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 diff --git a/docs/V0_401_RELEASE_SCOPE.md b/docs/V0_401_RELEASE_SCOPE.md new file mode 100644 index 000000000..100d014f4 --- /dev/null +++ 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