# 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