veza/docs/DISCOVERY_ALGORITHM.md

Algorithme de Découverte Veza — Documentation Auditable

Version : 1.0.0-rc1 Date : 2026-03-13 Référence : ORIGIN_FEATURES_REGISTRY.md §30, ORIGIN_BUSINESS_LOGIC.md

---

Principes fondamentaux

1. Chronologique, pas algorithmique — Le feed affiche les contenus par date de création, du plus récent au plus ancien
2. Tags et genres déclaratifs — Les créateurs choisissent leurs genres (max 3) et tags (max 10)
3. Pas de classement par popularité — play_count et like_count ne sont JAMAIS utilisés dans le tri
4. Artistes émergents = artistes établis — Un artiste avec 0 écoute a la même visibilité qu'un artiste avec 1M d'écoutes
5. Auditable et testable — Des tests automatisés vérifient l'absence de biais

---

Mécanismes de découverte

1. Feed chronologique (GET /api/v1/feed)

• Tri : ORDER BY tracks.created_at DESC, tracks.id DESC
• Source : Pistes des artistes suivis par l'utilisateur
• Pagination : Curseur keyset (created_at, id)
• Fichier : veza-backend-api/internal/core/feed/service.go:77

2. Découverte par genre (GET /api/v1/discover/genre/:genre)

• Tri : ORDER BY tracks.created_at DESC, tracks.id DESC
• Source : Pistes associées au genre déclaré
• Fichier : veza-backend-api/internal/core/discover/service.go:193

3. Découverte par tag (GET /api/v1/discover/tag/:tag)

• Tri : ORDER BY tracks.created_at DESC, tracks.id DESC
• Source : Pistes associées au tag déclaré
• Fichier : veza-backend-api/internal/core/discover/service.go:251

4. Playlists éditoriales (GET /api/v1/discover/playlists/editorial)

• Tri : ORDER BY playlists.created_at DESC
• Source : Playlists curatorées manuellement (humain, pas algorithme)
• Fichier : veza-backend-api/internal/core/discover/service.go:381

5. Recherche (GET /api/v1/search)

• Moteur : Elasticsearch fulltext
• Critères : Correspondance textuelle (titre, artiste, tags)
• Pas de boost par popularité

6. Trending hashtags (GET /api/v1/social/trending)

• Tendances de hashtags de conversation (sujets de discussion)
• PAS de tendances de pistes musicales
• Fichier : veza-backend-api/internal/core/social/trending_service.go

---

Ce que l'algorithme ne fait PAS

Interdit	Raison
Tri par play_count	Biais de popularité
Tri par like_count	Biais de popularité
Collaborative filtering	Profilage comportemental
Content-based filtering ML	IA/ML interdit
"Trending" basé sur les écoutes	Biais de popularité
"Featured" basé sur l'engagement	Dark pattern
Optimisation pour la rétention	Manipulation
A/B testing sur le tri	Optimisation engagement

---

Métriques de popularité

• play_count et like_count existent en base pour les analytics créateur privés
• Ces champs portent le tag json:"-" → jamais sérialisés dans les réponses API publiques
• Le frontend n'affiche ces métriques qu'au créateur de la piste (dans son tableau de bord)

---

Tests automatisés

Fichier : veza-backend-api/internal/core/discover/ethical_bias_test.go

Test	Vérifie
TestDiscovery_NoPlayCountBias_GenreBrowse	Track 0 plays (récent) apparaît avant track 1M plays (ancien)
TestDiscovery_NoPlayCountBias_TagBrowse	Même vérification pour la découverte par tag
TestDiscovery_EmergingArtistVisibility	Artiste émergent pas démotivé par la popularité
TestDiscovery_MetricsNotExposedInJSON	play_count et like_count absents du JSON sérialisé

---

Audit

Ce document, combiné aux tests automatisés et au code source, permet un audit indépendant complet de l'algorithme de découverte. Toutes les clauses ORDER BY du backend sont vérifiables dans les fichiers source référencés.

---

Conforme à ORIGIN_FEATURES_REGISTRY.md §30 : "L'algorithme est documenté, explicable, et auditable"