# Scope v0.403 — Phase 4 Commerce (suite)

**Version cible** : v0.403 (X=4, Y=3)  
**Prérequis** : v0.402 taguée et mergée dans main  
**Objectif** : Payout vendeurs, reviews produits, factures, remboursements  
**Dernière mise à jour** : février 2026  
**Effort estimé** : 6-8 semaines de développement

---

## 1. Principe directeur

> **v0.403 = finalisation boucle commerce complète.**
>
> Quatre axes principaux :
> 1. **Payout vendeurs (Lot P3)** : Stripe Connect ou équivalent pour versements
> 2. **Reviews produits (Lot R1)** : Avis acheteurs sur produits achetés
> 3. **Factures (Lot F1)** : Génération PDF facture par commande
> 4. **Remboursements (Lot R2)** : Initiation remboursement par vendeur/admin

---

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

### 2.1 Livré en v0.402

| Lot | Feature | Statut |
|-----|---------|--------|
| P1 | Checkout Hyperswitch production-ready (return URL, success/error, webhook cancelled, CheckoutPaymentForm) | ✅ |
| P2 | Codes promo (promo_codes, ValidatePromoCode, PromoCodeModal connecté, OrderSummary) | ✅ |

### 2.2 Fondation existante (à enrichir)

| Domaine | Existant | À ajouter v0.403 |
|---------|----------|------------------|
| **Payout** | Orders, licences, Hyperswitch | Stripe Connect onboarding, transferts, balance vendeur |
| **Reviews** | Products, orders, licenses | Table product_reviews, notation, commentaire |
| **Factures** | Orders avec items, total, buyer | Génération PDF, stockage ou envoi email |
| **Remboursements** | Orders status completed/failed | Initiation remboursement, webhook refund |

### 2.3 Composants techniques

| Composant | État | Action v0.403 |
|-----------|------|---------------|
| veza-backend-api | ✅ | Routes payout, reviews, invoices, refunds |
| apps/web | ✅ | Seller payout dashboard, reviews UI, téléchargement facture |
| Hyperswitch / Stripe | ✅ | API refund, Connect si payout |
| Stream Server | ⚠️ | Hors scope (stabilisation séparée) |

---

## 3. Features IN SCOPE v0.403

### 3.1 Lot P3 — Payout vendeurs

**Objectif** : Permettre aux vendeurs de recevoir les revenus des ventes.  
**Effort** : L (5-7 jours)  
**Référence** : V0_402 HORS SCOPE

| # | Feature | Tâche détaillée | Backend | Frontend | Critère de sortie |
|---|---------|-----------------|---------|----------|-------------------|
| P3.1 | **Connect onboarding** | Lien Stripe Connect Express | POST /sell/connect/onboard, redirect Stripe | Bouton « Configurer les paiements » | Vendeur connecté à Stripe |
| P3.2 | **Balance vendeur** | Solde disponible, en attente | GET /sell/balance (depuis Stripe ou table) | Carte balance dans SellerDashboard | Balance affichée |
| P3.3 | **Transferts** | Payout automatique ou manuel | Hyperswitch/Stripe transfer après vente | — | Revenus transférés au vendeur |

**Fichiers clés** :  
- Backend : `sell_handlers.go`, `marketplace/service.go`, config Stripe Connect  
- Frontend : `SellerDashboardView`, `commerceService.ts`

**Note** : Si Stripe Connect trop complexe, MVP = afficher balance sans transfert automatique (report v0.404).

---

### 3.2 Lot R1 — Reviews produits

**Objectif** : Avis acheteurs sur produits achetés.  
**Effort** : M (3-4 jours)

| # | Feature | Tâche détaillée | Backend | Frontend | Critère de sortie |
|---|---------|-----------------|---------|----------|-------------------|
| R1.1 | **Table product_reviews** | Migration, modèle | product_id, buyer_id, order_id, rating (1-5), comment, created_at | — | Migration appliquée |
| R1.2 | **POST /marketplace/products/:id/reviews** | Créer avis (acheteur uniquement) | Vérifier license, 1 review par produit/acheteur | Formulaire avis dans ProductDetailView | Avis enregistré |
| R1.3 | **GET /marketplace/products/:id/reviews** | Liste avis paginée | Pagination, tri par date | Section avis dans ProductDetailView | Avis affichés |
| R1.4 | **Note moyenne** | Agréger ratings | Product.avg_rating ou computed | Badge étoiles sur ProductCard | Note affichée |

**Fichiers clés** :  
- Backend : `migrations/101_product_reviews.sql`, `marketplace/service.go`, handlers  
- Frontend : `ProductDetailView`, `ProductCard`, `marketplaceService.ts`

---

### 3.3 Lot F1 — Factures

**Objectif** : Génération PDF facture par commande.  
**Effort** : M (2-3 jours)

| # | Feature | Tâche détaillée | Backend | Frontend | Critère de sortie |
|---|---------|-----------------|---------|----------|-------------------|
| F1.1 | **GET /marketplace/orders/:id/invoice** | Générer PDF | Lib PDF (gopdf, gofpdf), template facture | Lien « Télécharger facture » dans PurchasesView | PDF téléchargeable |
| F1.2 | **Contenu facture** | Order, items, total, promo, buyer, seller | Données order + product titles | — | Facture lisible |

**Fichiers clés** :  
- Backend : `marketplace/handlers.go`, lib PDF, template  
- Frontend : `PurchasesView`, `LicensesView`, lien download

---

### 3.4 Lot R2 — Remboursements

**Objectif** : Initiation remboursement par vendeur ou admin.  
**Effort** : M (2-3 jours)

| # | Feature | Tâche détaillée | Backend | Frontend | Critère de sortie |
|---|---------|-----------------|---------|----------|-------------------|
| R2.1 | **POST /marketplace/orders/:id/refund** | Initier remboursement | Hyperswitch/Stripe refund API, order status = refunded | Bouton « Rembourser » (admin/seller) | Remboursement traité |
| R2.2 | **Webhook refund** | Mise à jour order | ProcessRefundWebhook si fourni | — | Order reflète refund |
| R2.3 | **Révocation licence** | Invalider license si refund | License status ou soft delete | — | License non téléchargeable |

**Fichiers clés** :  
- Backend : `marketplace/service.go`, webhook handler  
- Frontend : `SellerDashboardView` (sales), bouton refund

---

## 4. Récapitulatif par lot

| Lot | Priorité | Effort | Dépendances |
|-----|----------|--------|-------------|
| P3 | Haute | L (5-7 j) | Stripe Connect config |
| R1 | Haute | M (3-4 j) | Aucune |
| F1 | Moyenne | M (2-3 j) | Aucune |
| R2 | Moyenne | M (2-3 j) | Hyperswitch refund API |

**Ordre recommandé** : R1 (reviews) → F1 (factures) → R2 (remboursements) → P3 (payout). P3 peut être reporté si Stripe Connect non prêt.

---

## 5. Features HORS SCOPE v0.403

| Feature | Raison | Version cible |
|---------|--------|---------------|
| Appels de groupe (3+) | Scope Chat, v0.303 fait | v0.304+ |
| Chiffrement E2E messages | Effort majeur | v0.404+ |
| Stream Server (imports) | Stabilisation infra séparée | Ticket dédié |
| Promotions dynamiques (flash sales) | Priorité moindre | v0.404 |
| Dispute / réclamation client | Scope support | v0.404+ |

---

## 6. Migrations et schémas

| Migration | Description |
|-----------|-------------|
| 101 | product_reviews (product_id, buyer_id, order_id, rating, comment, created_at) — UNIQUE(product_id, buyer_id) |

*Payout : pas de migration si Stripe Connect gère les données. Sinon table seller_stripe_accounts.*

---

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

- [ ] Lot P3 : Payout vendeurs (onboarding, balance) ou reporté avec ticket
- [ ] Lot R1 : Reviews produits (création, liste, note moyenne)
- [ ] Lot F1 : Facture PDF téléchargeable par commande
- [ ] Lot R2 : Remboursement initiable, webhook, révocation licence
- [ ] 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.402
- [ ] SCOPE_CONTROL.md référence V0_403_RELEASE_SCOPE.md
- [ ] FEATURE_STATUS.md mis à jour
- [ ] CHANGELOG v0.403
- [ ] MSW handlers pour nouvelles routes (reviews, invoice, refund)
- [ ] Stories Storybook pour composants nouveaux (Loading, Error selon STORYBOOK_CONTRACT)

---

## 9. Transition vers v0.404

À l'issue de v0.403 :
- Boucle commerce complète (achat, promo, facture, remboursement, payout)
- Prochaine version : **v0.404** — à définir (promotions, disputes, E2E chat, etc.)
- Document de scope : `V0_404_RELEASE_SCOPE.md` (à créer après tag v0.403)

---

## Références

- [V0_402_RELEASE_SCOPE.md](V0_402_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