veza/docs/PLAN_V0_901_IMPLEMENTATION.md

Plan d'implémentation v0.901 — Marketplace Complet & Analytics Avancés

État des lieux

Feature	Backend	Frontend	Tests
Wishlist	✅ wishlist.go	❌	❌
Promotions	❌	❌	❌
Disputes	❌	❌	❌
Review reply	❌	❌	❌
Re-download	❌	❌	❌
Taxes	❌	❌	❌
Geography analytics	❌	❌	❌
Demographics	❌	❌	❌
Traffic sources	❌	❌	❌
Revenue projections	❌	❌	❌
Admin analytics	❌	❌	❌

---

Fichiers existants clés

• Marketplace service : service.go
• Marketplace models : models.go
• Wishlist : wishlist.go
• Analytics handler : handler.go
• Frontend marketplace : apps/web/src/features/marketplace/
• Frontend analytics : apps/web/src/features/analytics/

---

Step 1 : Wishlist frontend (MK1-01, MK1-02)

Backend : Vérifier que wishlist.go expose POST /marketplace/wishlist/:productId et DELETE /marketplace/wishlist/:productId et GET /marketplace/wishlist. Ajouter les routes dans routes_marketplace.go si manquantes.

Frontend :

• WishlistView — page /marketplace/wishlist, grille de ProductCard
• Bouton coeur (Heart icon) sur chaque ProductCard, toggle wishlist via service
• Service : addToWishlist(productId), removeFromWishlist(productId), getWishlist()

Commit : feat(marketplace): connect wishlist frontend with WishlistView and heart toggle

---

Step 2 : Promotions / Flash Sales (MK1-03, MK1-04)

Migration : migrations/126_promotions.sql

CREATE TABLE IF NOT EXISTS promotions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    product_id UUID NOT NULL REFERENCES products(id) ON DELETE CASCADE,
    seller_id UUID NOT NULL REFERENCES users(id),
    discount_percent INTEGER NOT NULL CHECK (discount_percent BETWEEN 1 AND 90),
    starts_at TIMESTAMPTZ NOT NULL,
    ends_at TIMESTAMPTZ NOT NULL,
    is_active BOOLEAN NOT NULL DEFAULT true,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE INDEX idx_promotions_product ON promotions(product_id);
CREATE INDEX idx_promotions_active ON promotions(is_active, starts_at, ends_at);

Backend : CRUD promotions — seller crée promo sur ses produits, discount appliqué dans CreateOrder Frontend : Badge "PROMO -X%" sur ProductCard, countdown timer, page /marketplace/deals

Commit : feat(marketplace): promotions with flash sales, discount badge, deals page

---

Step 3 : Disputes (MK1-05)

Migration : migrations/127_disputes.sql

CREATE TABLE IF NOT EXISTS disputes (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    order_id UUID NOT NULL REFERENCES orders(id),
    buyer_id UUID NOT NULL REFERENCES users(id),
    reason TEXT NOT NULL,
    details TEXT,
    status VARCHAR(20) NOT NULL DEFAULT 'open',
    resolution VARCHAR(20),
    resolved_by UUID REFERENCES users(id),
    resolved_at TIMESTAMPTZ,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

Backend : POST /marketplace/orders/:id/dispute (buyer), GET /admin/disputes, POST /admin/disputes/:id/resolve Frontend : Bouton "Report Issue" dans PurchasesView, admin DisputesView

Commit : feat(marketplace): dispute flow with buyer creation and admin resolution

---

Step 4 : Review replies + Re-download + Taxes (MK1-06 to MK1-08)

Review reply : POST /marketplace/reviews/:id/reply (seller only, max 1 reply per review), migration ajout reply TEXT et replied_at sur product_reviews

Re-download : GET /marketplace/orders/:id/download — génère signed S3 URL (5min expiry) pour chaque fichier de la commande, vérifie ownership

Taxes : Config TAX_RATES JSONB dans config/DB ({"FR": 20, "US": 0, "UK": 20}), calcul auto dans CreateOrder, affichage dans OrderSummary

Commit : feat(marketplace): review replies, unlimited re-download, auto tax calculation

---

Step 5 : Geography analytics (AN1-01, AN1-02)

Backend :

• Middleware track listener IP → country (MaxMind GeoIP2-Lite database)
• Store country on track_plays table (migration 128_track_plays_country.sql)
• GET /analytics/geography — aggregate plays par country, top 20

Frontend : Carte heatmap avec react-simple-maps, tooltip country name + play count

Commit : feat(analytics): listener geography with GeoIP and map visualization

---

Step 6 : Demographics + Traffic + Revenue (AN1-03 to AN1-07)

Demographics : Parse user-agent sur track plays, store device_type/os/browser. GET /analytics/demographics

Traffic sources : Store referrer on track plays. GET /analytics/traffic-sources — top 10 referrers

Revenue projections : GET /analytics/revenue/projection — régression linéaire simple sur les revenus des 90 derniers jours, projections 30/60/90j

Period comparison : GET /analytics/compare?period1_start=...&period1_end=...&period2_start=...&period2_end=... — compare plays, revenue, followers entre 2 périodes

Frontend : Onglets dans analytics dashboard — Demographics (donut chart), Traffic (bar chart), Revenue (line chart + projection), Comparison (side-by-side)

Commit : feat(analytics): demographics, traffic sources, revenue projections, period comparison

---

Step 7 : Admin Analytics (AN2-01 to AN2-06)

Backend :

• GET /admin/analytics/users — DAU/MAU basé sur last_active_at
• GET /admin/analytics/signups — count inscrits par jour/semaine/mois
• GET /admin/analytics/retention — D1/D7/D30 retention cohorts
• GET /admin/analytics/transactions — revenus, nombre, ticket moyen
• GET /admin/analytics/performance — query Prometheus API pour p50/p95 latency, error rate

Frontend : Admin analytics dashboard — widgets DAU/MAU, line chart signups, retention curve, transactions KPIs, performance metrics

Commit : feat(admin): analytics dashboard with DAU/MAU, retention, transactions, performance

---

Step 8 : MSW + Tests

MSW : handlers wishlist, promotions, disputes, review reply, download, analytics endpoints Tests : wishlist CRUD, promotion validity window, dispute flow, tax calculation, geography aggregation, retention cohort formula, revenue projection

Commit : test(marketplace,analytics): unit tests for wishlist, promotions, disputes, analytics

---

Step 9 : Documentation + release

Commit : docs: update documentation for v0.901

---

Step 10 : Rétrospective + archivage + tag

git tag v0.901

---

Validation finale

cd veza-backend-api && go build ./... && go test ./... -v
cd apps/web && npm run build
git tag v0.901