# V0.901 Release Scope — Marketplace Complet & Analytics Avancés

**Statut** : Planifié
**Phase** : 9 (v1.0 Launch — Lot 1)
**Prérequis** : v0.803 (taguée)
**Date cible** : TBD
**Estimation** : ~3 sprints (15 jours ouvrés)
**Précédente** : [v0.803](archive/V0_803_RELEASE_SCOPE.md)

---

## 1. Objectif

Première version de la Phase 9. Complète le module **Marketplace** (wishlist, promotions/flash sales, dispute/réclamation, réponses aux reviews, re-téléchargement illimité, informations fiscales) et les **Analytics avancés** (géographie auditeurs, démographie, devices, sources de trafic, projections revenus, analytics admin). Ces fonctionnalités finalisent le volet commerce et données pour la v1.0.

---

## 2. État actuel (post-v0.803)

| Composant | État | Détail |
|-----------|------|--------|
| **Produits & Catalogue** | ✅ Livré v0.401 | CRUD, filtres, images, previews |
| **Licences & Droits** | ✅ Livré v0.401 | Types, conditions, LicenceCard |
| **Checkout Hyperswitch** | ✅ Livré v0.402 | Production-ready, return URL |
| **Codes promo** | ✅ Livré v0.402 | Validation, OrderSummary |
| **Reviews** | ✅ Livré v0.702 | Create, List, tests unitaires |
| **Factures PDF** | ✅ Livré v0.702 | GenerateInvoice, download |
| **Remboursements** | ✅ Livré v0.702 | RefundOrder, licence revocation |
| **Seller dashboard** | ✅ Livré v0.401 | Stats, evolution chart, top products |
| **Transfer auto** | ✅ Livré v0.603 | Stripe Connect, commission plateforme |
| **Wishlist** | ❌ Absent | wishlist.go existe mais non connecté frontend |
| **Promotions / flash sales** | ❌ Absent | Pas de système de promotions dynamiques |
| **Dispute / réclamation** | ❌ Absent | Pas de flow dispute client |
| **Répondre aux reviews** | ❌ Absent | Pas de réponse vendeur aux reviews |
| **Re-téléchargement illimité** | ❌ Absent | Pas de re-download après achat |
| **Informations fiscales** | ❌ Absent | Pas de calcul taxes automatique |
| **Analytics créateur** | ✅ Livré v0.202 | Stats, charts, export CSV/JSON |
| **Géographie auditeurs** | ❌ Absent | Pas de carte géographique |
| **Démographie** | ❌ Absent | Pas de données démographiques |
| **Device analytics** | ❌ Absent | Pas de breakdown par device |
| **Admin analytics** | ❌ Absent | Pas de DAU/MAU, rétention |

---

## 3. Lots

### Lot MK1 — Marketplace Avancé

| # | Tâche | Fichiers impactés | Effort |
|---|-------|--------------------|--------|
| MK1-01 | Wishlist frontend — connecter wishlist.go existant, `WishlistView`, bouton coeur sur ProductCard, `GET /marketplace/wishlist` | Frontend + routes | M |
| MK1-02 | `POST /marketplace/wishlist/:productId`, `DELETE /marketplace/wishlist/:productId` — ajout/retrait wishlist | Backend routes | S |
| MK1-03 | Promotions — migration `126_promotions.sql` (table promotions: product_id, discount_percent, starts_at, ends_at, is_active), CRUD endpoints | Migrations, handlers | L |
| MK1-04 | Flash sales frontend — badge "PROMO -X%" sur ProductCard, countdown timer, page /marketplace/deals | Frontend | M |
| MK1-05 | Dispute / réclamation — migration `127_disputes.sql` (table disputes: order_id, buyer_id, reason, status, resolution), `POST /marketplace/orders/:id/dispute`, `GET /admin/disputes` | Migrations, handlers | L |
| MK1-06 | Réponse aux reviews — `POST /marketplace/reviews/:id/reply` (seller uniquement), affichage reply dans ProductDetailViewReviews | Backend, frontend | M |
| MK1-07 | Re-download — `GET /marketplace/orders/:id/download` retourne lien S3 temporaire pour les fichiers achetés, illimité dans le temps | Backend | M |
| MK1-08 | Taxes — config `TAX_RATE` par pays (défaut 0), calcul automatique dans checkout, affichage dans OrderSummary | Backend, frontend | M |
| MK1-09 | MSW handlers — wishlist, promotions, disputes, review reply, download | MSW | S |
| MK1-10 | Tests — wishlist CRUD, promotion validity, dispute flow, re-download auth | Tests | M |

### Lot AN1 — Creator Analytics Complet

| # | Tâche | Fichiers impactés | Effort |
|---|-------|--------------------|--------|
| AN1-01 | Géographie auditeurs — collecte IP → country (MaxMind GeoIP2-Lite), `GET /analytics/geography` | Backend | L |
| AN1-02 | Carte géographique frontend — composant carte avec heatmap par pays (bibliothèque légère, ex: react-simple-maps) | Frontend | L |
| AN1-03 | Démographie — user-agent parsing (device, OS, browser), `GET /analytics/demographics` | Backend | M |
| AN1-04 | Device analytics — breakdown desktop/mobile/tablet, chart donut | Frontend | M |
| AN1-05 | Sources de trafic — referrer tracking, `GET /analytics/traffic-sources` | Backend | M |
| AN1-06 | Revenue projections — `GET /analytics/revenue/projection` basé sur tendance 30/60/90 jours (régression linéaire simple) | Backend | M |
| AN1-07 | Comparaison périodes — `GET /analytics/compare?period1=...&period2=...` | Backend | M |
| AN1-08 | Frontend analytics dashboard enrichi — onglets Geography, Demographics, Traffic, Revenue | Frontend | L |
| AN1-09 | Tests — geography parsing, projection calculation, comparison | Tests | M |

### Lot AN2 — Admin Analytics

| # | Tâche | Fichiers impactés | Effort |
|---|-------|--------------------|--------|
| AN2-01 | DAU/MAU — `GET /admin/analytics/users` basé sur last_active_at | Backend | M |
| AN2-02 | Nouveaux inscrits — `GET /admin/analytics/signups?period=30d` | Backend | S |
| AN2-03 | Taux de rétention — calcul D1, D7, D30 retention | Backend | M |
| AN2-04 | Volume de transactions — `GET /admin/analytics/transactions` (revenus, nombre, ticket moyen) | Backend | S |
| AN2-05 | Performances infrastructure — `GET /admin/analytics/performance` (p50, p95 latency, error rate) via Prometheus API | Backend | M |
| AN2-06 | Frontend admin analytics — dashboard avec widgets DAU/MAU, signups chart, retention curve, transactions summary | Frontend | L |
| AN2-07 | Tests — DAU calculation, retention formula, transaction aggregation | Tests | M |

### Lot QA1 — Tests & Release

| # | Tâche | Fichiers impactés | Effort |
|---|-------|--------------------|--------|
| QA1-01 | Smoke test v0.901 | `docs/SMOKE_TEST_V0901.md` | S |
| QA1-02 | Mise à jour docs | `docs/` | S |
| QA1-03 | Rétrospective, archivage, placeholder v0.902, tag | `docs/`, Git | S |

---

## 4. Hors scope v0.901

| Élément | Version cible |
|---------|---------------|
| Chat enrichi (images, GIFs) | v0.902 |
| Transactional emails | v0.902 |
| Social complete (hashtags, QR) | v0.902 |
| Profiles complete (verified badge) | v0.902 |
| Search recommendations ML | v0.903 |
| PayPal support | v2.0 |
| Crypto payments | v2.0 |
| Signature électronique licences | v2.0 |
| Contrat automatique généré | v2.0 |

---

## 5. Critères d'acceptation

- [ ] Wishlist : ajout/retrait produit, page /marketplace/wishlist, coeur sur ProductCard
- [ ] Promotions : CRUD, discount appliqué au checkout, badge PROMO, countdown, page /deals
- [ ] Dispute : création par buyer, liste admin, résolution (refund/dismiss)
- [ ] Review reply : vendeur peut répondre, reply affiché sous la review
- [ ] Re-download : lien S3 temporaire illimité pour les achats
- [ ] Taxes : calcul auto par pays, affiché dans OrderSummary
- [ ] Géographie : carte heatmap des auditeurs par pays
- [ ] Démographie : breakdown device/OS/browser
- [ ] Traffic sources : referrer top 10
- [ ] Revenue projections : prévision 30/60/90j
- [ ] Admin DAU/MAU, signups, retention, transactions
- [ ] Tag v0.901 créé

---

## 6. Risques

| Risque | Mitigation |
|--------|------------|
| GeoIP database size | Utiliser MaxMind GeoIP2-Lite (gratuit, ~60MB), refresh mensuel |
| Projections revenus fausses | Disclaimer "estimation basée sur les 90 derniers jours" |
| Carte géographique lourde (SVG) | react-simple-maps avec lazy load, simplification polygones |
| Dispute flow complexe | Flow simple v1 (open → resolve), workflow avancé en v2 |
| Taxes multi-pays | Taux configurables par pays dans admin, pas de calcul auto TVA complexe |

---

## 7. Références

- [V0_803_RELEASE_SCOPE.md](archive/V0_803_RELEASE_SCOPE.md)
- [SCOPE_CONTROL.md](SCOPE_CONTROL.md)
- `veza-backend-api/internal/core/marketplace/` (service, models, wishlist.go)
- `veza-backend-api/internal/core/analytics/`
- `apps/web/src/features/marketplace/`
- `apps/web/src/features/analytics/`