veza/docs/PLAN_V0_903_IMPLEMENTATION.md

Plan d'implémentation v0.903 — Stabilisation v1.0 & Launch Readiness

État des lieux

Feature	Backend	Frontend	Tests
Recherche phonétique	❌	❌	❌
Spell correction	❌	❌	❌
Saved searches	❌	❌	❌
Recommendations algo	⚠️ basic random	❌	❌
Auto playlists	❌	❌	❌
Smart playlists	❌	❌	❌
Export M3U	❌	❌	❌
Merge/duplicate playlists	❌	❌	❌
Session management	❌	❌	❌
Login unusual detection	❌	❌	❌
Login history	❌	❌	❌
CAPTCHA	❌	❌	❌
Password history	❌	❌	❌
Load tests k6	❌	—	❌
Production guide	❌	—	—

---

Fichiers existants clés

• Search : existing search handlers in internal/core/track/track_search_handler.go
• Recommendations : GET /tracks/recommendations (basic random)
• Playlists : internal/handlers/ (CRUD playlists)
• Auth : internal/core/auth/ (service, handler)
• Player : apps/web/src/features/player/
• Search frontend : apps/web/src/features/search/
• Library : apps/web/src/features/library/
• Settings Security : apps/web/src/components/settings/

---

Step 1 : Recherche phonétique + spell correction (ST1-01, ST1-02)

Backend :

• Activer extensions PostgreSQL : CREATE EXTENSION IF NOT EXISTS fuzzystrmatch;
• Modifier search query pour inclure soundex() et metaphone() comme fallback si trigram similarity < 0.3
• Ajouter "Did you mean" dans la réponse search : si < 3 résultats, chercher la meilleure alternative via similarity() > 0.3

type SearchResponse struct {
    Results    []Track  `json:"results"`
    Total      int64    `json:"total"`
    DidYouMean *string  `json:"did_you_mean,omitempty"`
}

Frontend : Afficher "Did you mean: {suggestion}" cliquable dans SearchPage

Commit : feat(search): phonetic search with soundex/metaphone and spell correction

---

Step 2 : Saved searches (ST1-03)

Migration : migrations/132_saved_searches.sql

CREATE TABLE IF NOT EXISTS saved_searches (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    query TEXT NOT NULL,
    filters JSONB DEFAULT '{}',
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE INDEX idx_saved_searches_user ON saved_searches(user_id);

Backend : POST /search/saved, GET /search/saved, DELETE /search/saved/:id (max 50 per user)

Frontend : Section "Saved Searches" dans SearchPage, bouton save, liste dans sidebar

Commit : feat(search): saved searches with CRUD and frontend display

---

Step 3 : Recommendation algorithm + Auto playlists (ST1-04, ST1-05)

Backend :

• Collaborative filtering : SELECT t.* FROM tracks t JOIN track_plays tp ON t.id = tp.track_id WHERE tp.user_id IN (SELECT user_id FROM track_plays WHERE track_id IN (SELECT track_id FROM track_plays WHERE user_id = ?)) AND t.id NOT IN (SELECT track_id FROM track_plays WHERE user_id = ?) ORDER BY count(*) DESC LIMIT 30
• Fallback si pas assez de données : genre + BPM similarity
• "Discover Weekly" : cron lundi 00:00, génère playlist auto pour chaque user actif (played_last_30d)
• "Your Top Tracks" : top 20 plays du mois en cours, régénéré quotidiennement

Frontend : Section dans Library avec playlists auto-générées (badge "Auto", read-only)

Commit : feat(search): collaborative filtering recommendations and auto-generated playlists

---

Step 4 : Smart playlists (ST2-01)

Migration : migrations/133_smart_playlists.sql

ALTER TABLE playlists ADD COLUMN IF NOT EXISTS is_smart BOOLEAN NOT NULL DEFAULT false;
ALTER TABLE playlists ADD COLUMN IF NOT EXISTS smart_rules JSONB;
ALTER TABLE playlists ADD COLUMN IF NOT EXISTS last_updated_at TIMESTAMPTZ;

Backend :

• Smart playlist rules : { "rules": [{"field": "genre", "op": "eq", "value": "hip-hop"}, {"field": "bpm", "op": "gt", "value": 120}], "logic": "AND", "limit": 100 }
• Cron quotidien : re-évalue les règles, met à jour les tracks de la playlist
• POST /playlists/smart — créer smart playlist, PUT /playlists/:id/rules — modifier règles

Frontend : Smart playlist builder — formulaire de règles (field selector, operator, value input), preview résultat

Commit : feat(playlists): smart playlists with rule builder and auto-update

---

Step 5 : Export M3U + Merge + Duplicate (ST2-02 to ST2-04)

Backend :

• GET /playlists/:id/export?format=m3u — génère fichier M3U8 avec URLs des tracks
• POST /playlists/merge — body { "playlist_ids": [...], "name": "Merged" }, déduplique par track_id
• POST /playlists/:id/duplicate — copie playlist + tracks, nom = "Copy of {name}"

Frontend : Menu actions dans PlaylistView avec Export, Merge (multi-select), Duplicate

Commit : feat(playlists): export M3U, merge playlists, duplicate playlist

---

Step 6 : Session management + Login history (ST3-01 to ST3-04)

Migration : migrations/134_sessions_history.sql

CREATE TABLE IF NOT EXISTS user_sessions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    device VARCHAR(255),
    ip_address VARCHAR(45),
    user_agent TEXT,
    is_current BOOLEAN NOT NULL DEFAULT false,
    is_suspicious BOOLEAN NOT NULL DEFAULT false,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    last_active_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE INDEX idx_user_sessions_user ON user_sessions(user_id);

CREATE TABLE IF NOT EXISTS login_history (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    ip_address VARCHAR(45),
    device VARCHAR(255),
    success BOOLEAN NOT NULL,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE INDEX idx_login_history_user ON login_history(user_id);

Backend :

• Créer session à chaque login, mettre à jour last_active_at sur chaque requête auth
• GET /auth/sessions — liste des sessions actives avec device/IP/date
• DELETE /auth/sessions/:id — révoquer une session (invalider le token)
• DELETE /auth/sessions — logout all devices
• GET /auth/login-history — dernières 50 connexions
• Détection login inhabituel : nouvelle IP non vue dans les 30 derniers jours → email notification

Frontend : Page Security dans Settings — tableau des sessions actives avec bouton Revoke, historique connexions

Commit : feat(auth): session management, login history, unusual login detection

---

Step 7 : CAPTCHA + Password history (ST3-05, ST3-06)

Backend :

• Intégration hCaptcha : middleware sur /auth/login (après 3 échecs consécutifs), /auth/register, /auth/reset-password
• Vérification server-side via hCaptcha API
• Password history : stocker hash des 5 derniers mots de passe dans password_history JSONB, vérifier avant update

Frontend : Composant <CaptchaWidget /> intégré dans les formulaires login/register/reset quand requis

Commit : feat(auth): hCaptcha integration and password history enforcement

---

Step 8 : Load testing k6 (ST4-01)

Fichier : tests/load/ (nouveau répertoire)

Scripts k6 :

• auth-flow.js — register + login + refresh + logout (100 VUs, 5min)
• search.js — search queries variées (200 VUs, 5min)
• marketplace.js — browse + add to cart + checkout (50 VUs, 5min)
• streaming.js — GET track + HLS segments (100 VUs, 5min)
• websocket.js — WebSocket connect + send/receive messages (50 VUs, 5min)

Target : p95 < 200ms, error rate < 1%, 0 crashes

Commit : test(load): k6 load testing scripts for auth, search, marketplace, streaming, websocket

---

Step 9 : Performance optimization (ST4-02 to ST4-04)

Redis : Ajouter cache-aside sur :

• Search results (TTL 30s)
• Trending hashtags (TTL 5min)
• Analytics aggregations (TTL 1min)
• User preferences (TTL 10min)

DB : EXPLAIN ANALYZE sur top 10 slow queries, ajouter indexes manquants

CDN : Cache-Control headers sur :

• Static assets : max-age=31536000, immutable
• HLS segments : max-age=3600
• Product images : max-age=86400

Commit : perf: Redis cache optimization, DB query tuning, CDN cache headers

---

Step 10 : Documentation v1.0 (ST5)

Fichier : docs/API_REFERENCE.md — compléter tous les endpoints manquants Fichier : docs/PRODUCTION_GUIDE.md (nouveau) — docker-compose prod, env vars, backup, monitoring, scaling Fichier : README.md — mise à jour v1.0 avec architecture, quick start, features Fichier : docs/MIGRATION_GUIDE.md (nouveau) — liste migrations 1-134+, procédure upgrade Fichier : CHANGELOG.md — historique complet v0.101 à v1.0

Commit : docs: v1.0 documentation — API Reference, Production Guide, README, Migration Guide

---

Step 11 : E2E validation + Security audit (REL)

• Exécuter tous les smoke tests (v0.703 à v0.903)
• Vérifier security headers sur toutes les réponses
• Vérifier rate limiting
• Vérifier GDPR (export + deletion)
• Lighthouse audit : Performance ≥ 85, Accessibility ≥ 90, PWA ≥ 90
• k6 results : p95 < 200ms

Commit : test: v1.0 E2E validation and security audit

---

Step 12 : Release v0.903 + v1.0

Fichier : docs/PROJECT_STATE.md — Version = v1.0, Phase = Released, features count final Fichier : docs/FEATURE_STATUS.md — mise à jour finale Fichier : docs/RETROSPECTIVE_V0903.md (nouveau) Fichier : docs/RETROSPECTIVE_V1.md (nouveau) — rétrospective globale du projet

git add .
git commit -m "chore(release): finalize v0.903 and v1.0 documentation"
git tag v0.903
git tag v1.0

---

Dépendances entre steps

graph TD
    S1[Step1 Search phonetic] --> S2[Step2 Saved searches]
    S2 --> S3[Step3 Recommendations]
    S4[Step4 Smart playlists] --> S5[Step5 Export/Merge/Dup]
    S6[Step6 Sessions] --> S7[Step7 CAPTCHA]
    S8[Step8 k6 load tests] --> S9[Step9 Perf optimization]
    S3 --> S10[Step10 Docs]
    S5 --> S10
    S7 --> S10
    S9 --> S10
    S10 --> S11[Step11 E2E]
    S11 --> S12[Step12 Release]

---

Validation finale

cd veza-backend-api && go build ./... && go vet ./... && go test ./... -v
cd apps/web && npm run build
# k6 load tests
cd tests/load && k6 run auth-flow.js && k6 run search.js
# Lighthouse
# Security headers check
git tag v0.903
git tag v1.0