# Scope v0.402 — Phase 4 Commerce (checkout & codes promo)

**Version cible** : v0.402 (X=4, Y=2)  
**Prérequis** : v0.401 taguée et mergée dans main  
**Objectif** : Checkout Hyperswitch production-ready, codes promo/réductions  
**Dernière mise à jour** : février 2026  
**Effort estimé** : 4-6 semaines de développement

---

## 1. Principe directeur

> **v0.402 = finalisation paiement réel et codes promo.**
>
> Deux axes principaux :
> 1. **Checkout Hyperswitch production-ready (Lot P1)** : UX success/error, webhook robustesse, flow complet
> 2. **Codes promo / réductions (Lot P2)** : Backend promo codes, connecter PromoCodeModal, OrderSummary discount

---

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

### 2.1 Livré en v0.401

| Lot | Feature | Statut |
|-----|---------|--------|
| M1 | Produits & Catalogue (BPM, key, previews, images, filtres, rich text) | ✅ |
| M2 | Licences & Droits (product_licenses, GET /licenses/mine, LicensesView) | ✅ |
| M3 | Seller dashboard enrichi (evolution chart, top products, real sales) | ✅ |

### 2.2 Fondation existante (à enrichir)

| Domaine | Existant | À ajouter v0.402 |
|---------|----------|-----------------|
| **Checkout** | Hyperswitch intégré, CreateOrder, webhook ProcessPaymentWebhook | UX success/error, retry, annulation, robustesse webhook |
| **Codes promo** | PromoCodeModal (UI décorative), OrderSummary WithDiscount | Backend promo_codes, validation, application au panier |

### 2.3 Composants techniques

| Composant | État | Action v0.402 |
|-----------|------|---------------|
| veza-backend-api | ✅ | Routes promo, amélioration webhook, gestion erreurs checkout |
| apps/web | ✅ | CheckoutSuccessView, CheckoutErrorView, PromoCodeModal connecté |
| Hyperswitch | ✅ | Flow complet, gestion états payment |

---

## 3. Features IN SCOPE v0.402

### 3.1 Lot P1 — Checkout Hyperswitch production-ready

**Objectif** : Finaliser le flow paiement réel, UX claire, robustesse.  
**Effort** : M (3-4 jours)  
**Référence** : Module 7.3 (features 251-265)

| # | Feature | Tâche détaillée | Backend | Frontend | Critère de sortie |
|---|---------|-----------------|---------|----------|-------------------|
| P1.1 | **Success/Error pages** | Pages dédiées après redirect Hyperswitch | Query params order_id, status dans return URL | CheckoutSuccessView, CheckoutErrorView | Utilisateur voit confirmation ou erreur claire |
| P1.2 | **Webhook robustesse** | Idempotence, retry, logs | ProcessPaymentWebhook idempotent, status déjà completed → skip | Logs structurés | Pas de double-création licences |
| P1.3 | **Annulation paiement** | Gérer cancelled/failed | Webhook status cancelled/failed → order status updated | Lien « Réessayer » ou retour panier | Order reflète l'état réel |
| P1.4 | **Flow checkout UI** | Intégration Stripe Elements (client_secret) | Inchangé (CreateOrder retourne client_secret) | CartView → checkout modal/page avec Stripe Elements | Paiement carte fonctionnel E2E |

**Fichiers clés** :  
- Backend : `marketplace/service.go`, `marketplace/handlers.go`, webhook handler  
- Frontend : `CartView`, `CheckoutSuccessView`, `CheckoutErrorView`, `commerceService.ts`

---

### 3.2 Lot P2 — Codes promo / réductions

**Objectif** : Backend promo codes, connecter PromoCodeModal, application au panier.  
**Effort** : M (3-4 jours)  
**Référence** : Module 7.3 (feature 255), Module 7.4 (feature 274)

| # | Feature | Tâche détaillée | Backend | Frontend | Critère de sortie |
|---|---------|-----------------|---------|----------|-------------------|
| P2.1 | **Table promo_codes** | Migration, modèle | code, discount_type (percent/fixed), discount_value, valid_from, valid_until, max_uses, used_count | — | Migration appliquée |
| P2.2 | **Validation promo** | POST /commerce/cart/validate-promo ou GET /commerce/promo/:code | Vérifier validité, dates, max_uses | PromoCodeModal appelle API | Code valide → discount retourné |
| P2.3 | **Application au checkout** | CreateOrder accepte promo_code | Réduire totalAmount si promo valide, enregistrer dans order | CartView passe code au checkout | Montant réduit dans order |
| P2.4 | **PromoCodeModal connecté** | Remplacer mock par API | — | commerceService.validatePromoCode, onApply avec discount | Réduction affichée dans OrderSummary |

**Fichiers clés** :  
- Backend : `migrations/`, `marketplace/service.go`, `marketplace/handlers.go`  
- Frontend : `PromoCodeModal.tsx`, `CartView`, `OrderSummary`, `commerceService.ts`

---

## 4. Récapitulatif par lot

| Lot | Priorité | Effort | Dépendances |
|-----|----------|--------|-------------|
| P1 | Haute | M (3-4 j) | Aucune |
| P2 | Haute | M (3-4 j) | P1 (checkout flow) — peut être en parallèle si équipes séparées |

**Ordre recommandé** : P1 → P2 (ou P1 et P2 en parallèle).

---

## 5. Features HORS SCOPE v0.402

| Feature | Raison | Version cible |
|---------|--------|----------------|
| Payout automatique (Stripe Connect) | Infra externe complexe | v0.403 |
| Seller dashboard complet (reviews, promotions) | Priorité moindre | v0.403 |
| Dispute / réclamation | Scope support | v0.403+ |
| Facture automatique PDF | Dépend checkout mature | v0.403 |
| Remboursement automatisé | Politique produit | v0.403+ |
| Stream Server (imports) | Stabilisation infra, hors commerce | v0.402 ou ticket séparé |

---

## 6. Migrations et schémas

| Migration | Description |
|-----------|-------------|
| 099 | promo_codes (code UNIQUE, discount_type, discount_value_cents, valid_from, valid_until, max_uses, used_count, created_at) |
| 100 | orders.promo_code_id (FK nullable), orders.discount_amount_cents |

*À ajuster selon schéma DB existant et numérotation migrations.*

---

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

- [ ] Lot P1 : Success/Error pages, webhook robustesse, annulation, flow checkout UI complet
- [ ] Lot P2 : Table promo_codes, validation API, application au checkout, PromoCodeModal connecté
- [ ] 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.401
- [ ] SCOPE_CONTROL.md référence V0_402_RELEASE_SCOPE.md
- [ ] FEATURE_STATUS.md mis à jour
- [ ] CHANGELOG v0.402
- [ ] MSW handlers pour nouvelles routes (validate-promo, checkout success/error)
- [ ] Stories Storybook pour CheckoutSuccessView, CheckoutErrorView (Loading, Error selon STORYBOOK_CONTRACT)

---

## 9. Transition vers v0.403

À l'issue de v0.402 :
- Checkout production-ready avec Hyperswitch
- Codes promo fonctionnels
- Prochaine version : **v0.403** — Payout, reviews, factures, remboursements
- Document de scope : `V0_403_RELEASE_SCOPE.md` (à créer après tag v0.402)

---

## Références

- [V0_401_RELEASE_SCOPE.md](V0_401_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