roadwave/features/api/recommendation/README.md

# Tests Gherkin - Algorithme de Recommandation

Tests BDD pour la section [04-algorithme-recommandation.md](../../docs/regles-metier/04-algorithme-recommandation.md)

## Fichiers de tests

### [classification-geo.feature](classification-geo.feature)
**Couverture** : Section 2.1 des règles métier

- ✅ Classification 3 types (Géo-ancré 70%, Géo-contextuel 50%, Géo-neutre 20%)
- ✅ Choix par créateur
- ✅ Reclassification par modérateur
- ✅ Modification après publication
- ✅ Impact sur pondération algorithme

**Scénarios** : 11

---

### [scoring-recommandation.feature](scoring-recommandation.feature)
**Couverture** : Sections 2.2, 2.3, 2.4 des règles métier

- ✅ Calcul score géographique linéaire (1 - distance/200km)
- ✅ Calcul score d'intérêts (moyenne jauges tags)
- ✅ Calcul score engagement (complétion 50%, likes 30%, abonnements 20%)
- ✅ Seuil minimum 50 écoutes
- ✅ Score final combiné selon type contenu
- ✅ Bonus aléatoire 10% configurable
- ✅ Contenu viral peut être recommandé loin
- ✅ Pré-calcul 5 contenus suivants
- ✅ Recalcul si >10 km ou >10 min

**Scénarios** : 23

---

### [contenu-politique.feature](contenu-politique.feature)
**Couverture** : Section 2.5 des règles métier (MVP simplifié)

- ✅ Tag simple "Politique" sans classification gauche/droite
- ✅ Filtrage utilisateur "Masquer contenu politique"
- ✅ Par défaut tous contenus visibles
- ✅ Mode Kids filtre automatiquement le politique
- ✅ Pas d'équilibrage imposé en MVP

**Scénarios** : 13

---

### [mode-kids.feature](mode-kids.feature)
**Couverture** : Section 2.6 des règles métier

- ✅ Activation manuelle (pas automatique car âge min 13 ans)
- ✅ Filtrage contenus "Tous publics" uniquement
- ✅ Exclusion automatique contenu politique
- ✅ Pas de publicité (ou validée manuellement)
- ✅ Interface standard (pas d'UI enfant)
- ✅ Désactivation possible à tout moment

**Scénarios** : 15

---

### [declenchement-geo.feature](declenchement-geo.feature)
**Couverture** : Section 2.7 des règles métier

- ✅ Notification sonore + visuelle au passage <500m
- ✅ Délai réaction 5 secondes
- ✅ Pas d'interruption contenu en cours
- ✅ Logos différenciés (📍🏛️🍴🎭)
- ✅ Publicité uniquement entre contenus
- ✅ Gestion demi-tour (pas de répétition avant 24h)
- ✅ Rayon configurable par admin

**Scénarios** : 17

---

### [historique-reproposition.feature](historique-reproposition.feature)
**Couverture** : Section 2.8 des règles métier

- ✅ Contenu >80% jamais reproposé (sauf replayable=true)
- ✅ Contenu <10s ne pas reproposer (signal négatif)
- ✅ Contenu 10-80% reproposer avec reprise position
- ✅ Stockage illimité PostgreSQL
- ✅ Algorithme considère 100 derniers pour performance
- ✅ Export complet RGPD

**Scénarios** : 17

---

### [parametrabilite-admin.feature](parametrabilite-admin.feature)
**Couverture** : Section 2.9 des règles métier

- ✅ Dashboard admin avec tous paramètres configurables à chaud
- ✅ Validation plages de valeurs
- ✅ Aucun recalcul batch (économie CPU)
- ✅ Versioning configurations (git-like)
- ✅ Rollback 1 clic
- ✅ A/B testing avec split 50/50
- ✅ Métriques comparatives temps réel
- ✅ Graphiques évolution engagement
- ✅ Export CSV analyse externe

**Scénarios** : 17

---

### [parametrabilite-utilisateur.feature](parametrabilite-utilisateur.feature)
**Couverture** : Section 2.10 des règles métier

- ✅ 3 curseurs (Géolocalisation, Découverte, Politique)
- ✅ Profils sauvegardables (Trajet quotidien, Road trip, Enfants)
- ✅ Synchronisation multi-devices
- ✅ Auto-switch selon contexte GPS
- ✅ Blocage modification si vitesse >10 km/h
- ✅ Warning avant de prendre la route
- ✅ Limite 10 profils par utilisateur

**Scénarios** : 22

---

### [medias-traditionnels.feature](medias-traditionnels.feature)
**Couverture** : Section 2.11 des règles métier

- ✅ Compte média vérifié (badge ✓)
- ✅ Pas de validation 3 premiers contenus
- ✅ Modération a posteriori uniquement
- ✅ Formats: flash info, chroniques, éditos, reportages
- ✅ Classification âge obligatoire
- ✅ Monétisation standard (3€/1000 écoutes)
- ✅ Sponsoring direct autorisé
- ✅ Statistiques détaillées

**Scénarios** : 19

---

## Statistiques

| Métrique | Valeur |
|----------|--------|
| **Fichiers** | 9 |
| **Scénarios** | 154 |
| **Règles métier** | 100% couverture section 2 |

## Formules mathématiques testées

### Score géographique
```
score_geo = 1 - (distance_km / distance_max_km)
```

### Score intérêts
```
score_interets = moyenne(jauges_tags_correspondants)
```

### Score engagement
```
score_engagement = (taux_completion × 0.5) + (ratio_likes × 0.3) + (ratio_abonnements × 0.2)
```

### Score final
```
score_final = (score_geo × poids_geo_type)
            + (score_interets × poids_interets_type)
            + (score_engagement × 0.2)
            + bonus_aleatoire
```

## Paramètres par défaut

| Paramètre | Défaut | Plage |
|-----------|--------|-------|
| poids_geo_ancre | 0.7 | 0.5 - 1.0 |
| poids_geo_contextuel | 0.5 | 0.3 - 0.7 |
| poids_geo_neutre | 0.2 | 0.0 - 0.4 |
| poids_engagement | 0.2 | 0.0 - 0.5 |
| part_aleatoire_global | 0.1 | 0.0 - 0.3 |
| distance_max_km | 200 | 50 - 500 |
| rayon_gps_point_m | 500 | 100 - 2000 |
| seuil_min_ecoutes_engagement | 50 | 10 - 200 |

## Exécution des tests

### Tous les tests de recommandation
```bash
godog run features/recommendation/
```

### Un fichier spécifique
```bash
godog run features/recommendation/scoring-recommandation.feature
```

### Tests calculs mathématiques uniquement
```bash
godog run features/recommendation/scoring-recommandation.feature --tags=@calcul
```

## CI/CD

Ces tests sont exécutés :
- ✅ Avant chaque release
- ✅ Sur les PRs modifiant l'algorithme de recommandation
- ✅ Nightly builds (tous les tests)

## Implémentation des steps

Les steps definitions seront implémentées dans :
```
features/steps/recommendation_steps.go
```

Exemple avec calculs :
```go
func (s *RecommendationSteps) lalgorithmeCalculeLeScoreGeo(expectedScore float64) error {
    actualScore := 1.0 - (s.distance / s.distanceMax)
    if math.Abs(actualScore - expectedScore) > 0.01 {
        return fmt.Errorf("score_geo: attendu %.2f, obtenu %.2f", expectedScore, actualScore)
    }
    return nil
}
```

## Prochaines étapes

1. ⏳ Implémenter les steps definitions en Go
2. ⏳ Tester les formules mathématiques avec valeurs edge cases
3. ⏳ Configurer Testcontainers pour PostgreSQL + PostGIS
4. ⏳ Tests de performance (calcul score pour 1000 contenus <100ms)
5. ⏳ Créer les Gherkin pour les 14 autres sections

---

**Statut** : ✅ Spécifications complètes
**Dernière mise à jour** : 2026-01-21