docs: add V0_402_RELEASE_SCOPE and PLAN_V0_402_IMPLEMENTATION

2026-02-22 14:26:19 +01:00 · 2026-02-22 14:26:19 +01:00 · 464a23e545
commit 464a23e545
parent fa4d141572
2 changed files with 254 additions and 0 deletions
--- a/docs/PLAN_V0_402_IMPLEMENTATION.md
+++ b/docs/PLAN_V0_402_IMPLEMENTATION.md
@ -0,0 +1,94 @@
+# Plan d'implémentation v0.402 — Phase 4 Commerce (checkout & codes promo)
+
+**Version cible** : v0.402  
+**Objectif** : Checkout Hyperswitch production-ready, codes promo/réductions  
+**Référence** : [V0_402_RELEASE_SCOPE.md](V0_402_RELEASE_SCOPE.md)  
+**Dernière mise à jour** : février 2026
+
+---
+
+## Diagramme de dépendances v0.402
+
+```mermaid
+flowchart TD
+    subgraph Backend [veza-backend-api]
+        P1_B[P1 Webhook robustesse + return URL]
+        P2_B[P2 Migrations promo_codes + routes]
+    end
+    subgraph Frontend [apps/web]
+        P1_F[CheckoutSuccessView CheckoutErrorView]
+        P2_F[PromoCodeModal connecté OrderSummary]
+    end
+    P1_B --> P1_F
+    P2_B --> P2_F
+```
+
+---
+
+## Phase 0 — Vérification préalable
+
+| # | Tâche | Fichiers | Commit suggéré |
+|---|-------|----------|----------------|
+| 0.1 | Vérifier flow Hyperswitch actuel (CreateOrder, webhook) | `marketplace/service.go`, handlers | — |
+| 0.2 | Vérifier routes checkout, return URL config | `routes_marketplace.go`, config | — |
+| 0.3 | Vérifier PromoCodeModal, OrderSummary, CartView | `apps/web/src/components/` | — |
+
+---
+
+## Phase 1 — Lot P1 (Checkout Hyperswitch production-ready)
+
+| # | Tâche | Fichiers | Commit suggéré |
+|---|-------|----------|----------------|
+| 1.1 | Return URL avec query params (order_id, status) | Config backend, Hyperswitch CreatePayment | `feat(checkout): add order_id to return URL` |
+| 1.2 | CheckoutSuccessView (page confirmation) | `CheckoutSuccessView.tsx`, route | `feat(checkout): add CheckoutSuccessView` |
+| 1.3 | CheckoutErrorView (page erreur) | `CheckoutErrorView.tsx`, route | `feat(checkout): add CheckoutErrorView` |
+| 1.4 | Webhook idempotence (status completed → skip) | `marketplace/service.go` ProcessPaymentWebhook | `fix(checkout): idempotent webhook processing` |
+| 1.5 | Webhook status cancelled/failed | Order status update | `feat(checkout): handle cancelled/failed in webhook` |
+| 1.6 | Flow checkout UI (Stripe Elements si client_secret) | CartView, checkout modal/page | `feat(checkout): integrate Stripe Elements in checkout` |
+
+**Validation** : `go test ./...`, `npm run build`, test manuel checkout E2E (ou simulateur Hyperswitch).
+
+---
+
+## Phase 2 — Lot P2 (Codes promo / réductions)
+
+| # | Tâche | Fichiers | Commit suggéré |
+|---|-------|----------|----------------|
+| 2.1 | Migration promo_codes | `migrations/099_*.sql` | `feat(marketplace): add promo_codes migration` |
+| 2.2 | Migration orders.discount_amount_cents, promo_code_id | `migrations/100_*.sql` | `feat(marketplace): add discount to orders` |
+| 2.3 | Route GET /commerce/promo/:code | Handler + service | `feat(marketplace): add validate promo endpoint` |
+| 2.4 | CreateOrder accepte promo_code | Réduction total, enregistrement | `feat(marketplace): apply promo discount in CreateOrder` |
+| 2.5 | commerceService.validatePromoCode | `commerceService.ts` | `feat(commerce): add validatePromoCode API` |
+| 2.6 | PromoCodeModal connecté à API | `PromoCodeModal.tsx` | `feat(commerce): connect PromoCodeModal to API` |
+| 2.7 | CartView passe promo au checkout | `CartView`, `OrderSummary` | `feat(commerce): apply promo in checkout flow` |
+
+**Validation** : Code promo valide → réduction affichée → order avec discount.
+
+---
+
+## Phase 3 — Finalisation
+
+| # | Tâche | Fichiers | Commit suggéré |
+|---|-------|----------|----------------|
+| 3.1 | MSW handlers (validate-promo, checkout success/error) | `apps/web/src/mocks/handlers*.ts` | `test(commerce): add MSW handlers for v0.402` |
+| 3.2 | Stories Storybook (CheckoutSuccessView, CheckoutErrorView) | Composants | `feat(checkout): add stories for success/error views` |
+| 3.3 | Mise à jour CHANGELOG v0.402 | `CHANGELOG.md` | `docs: update CHANGELOG for v0.402` |
+| 3.4 | Vérification SCOPE_CONTROL, FEATURE_STATUS | — | — |
+
+---
+
+## Ordre d'exécution recommandé
+
+1. **Phase 0** — Vérification (30 min)
+2. **Phase 1** — P1 Checkout (3-4 j)
+3. **Phase 2** — P2 Codes promo (3-4 j)
+4. **Phase 3** — Finalisation (0.5-1 j)
+
+---
+
+## Références
+
+- [V0_402_RELEASE_SCOPE.md](V0_402_RELEASE_SCOPE.md) — Scope détaillé
+- [veza-backend-api/internal/core/marketplace/](../veza-backend-api/internal/core/marketplace/) — Service marketplace
+- [apps/web/src/components/commerce/](../apps/web/src/components/commerce/) — Composants commerce
+- [STORYBOOK_CONTRACT.md](../apps/web/docs/STORYBOOK_CONTRACT.md) — Contrat Storybook
--- a/docs/V0_402_RELEASE_SCOPE.md
+++ b/docs/V0_402_RELEASE_SCOPE.md
@ -0,0 +1,160 @@
+# 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