diff --git a/docs/PLAN_V0_402_IMPLEMENTATION.md b/docs/PLAN_V0_402_IMPLEMENTATION.md new file mode 100644 index 000000000..3260d0fcc --- /dev/null +++ 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 diff --git a/docs/V0_402_RELEASE_SCOPE.md b/docs/V0_402_RELEASE_SCOPE.md new file mode 100644 index 000000000..f964ba10b --- /dev/null +++ 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