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"*