ea77aa8ac7
Couverture complète des règles métier 05-interactions-navigation.md : API (Backend) : - File d'attente : pré-calcul 5 contenus, recalcul auto (>10km, 10min, <3 contenus), invalidation, Redis cache - Notifications géolocalisées : calcul ETA, déclenchement 7s avant, quota 6/h, cooldown 10min, tracking GPS - Jauges d'intérêt : architecture services séparés (Calculation + Update), pattern addition points absolus, persistance Redis/PostgreSQL UI (Frontend) : - Mode piéton : notifications push arrière-plan, rayon 200m, permissions stratégie progressive, geofencing iOS/Android - Basculement automatique voiture↔piéton : détection vitesse GPS, hysteresis 10s, transition transparente Fichiers créés : - features/api/navigation/file-attente.feature - features/api/navigation/notifications-geolocalisees.feature - features/ui/navigation/mode-pieton-notifications-push.feature Fichiers enrichis : - features/api/interest-gauges/evolution-jauges.feature (ajout scénarios architecture backend)
568 lines
19 KiB
Gherkin
568 lines
19 KiB
Gherkin
# language: fr
|
|
Fonctionnalité: API - Évolution des jauges d'intérêt
|
|
En tant qu'API backend
|
|
Je veux calculer et persister les évolutions de jauges d'intérêt
|
|
Afin d'alimenter l'algorithme de recommandation
|
|
|
|
Contexte:
|
|
Étant donné que l'API RoadWave est disponible
|
|
Et que la base de données PostgreSQL est accessible
|
|
Et qu'un utilisateur "user123" existe avec token JWT valide
|
|
|
|
Scénario: API calcule like automatique renforcé (≥80% écoute)
|
|
Étant donné que l'utilisateur "user123" a une jauge "Automobile" à 45% en base
|
|
Et qu'un contenu "content456" de 5 minutes est tagué "Automobile"
|
|
Quand je POST /api/v1/listening-events
|
|
"""json
|
|
{
|
|
"user_id": "user123",
|
|
"content_id": "content456",
|
|
"listened_duration_seconds": 270,
|
|
"total_duration_seconds": 300,
|
|
"completion_percentage": 90
|
|
}
|
|
"""
|
|
Alors le statut de réponse est 201
|
|
Et la réponse contient:
|
|
"""json
|
|
{
|
|
"like_type": "automatic_reinforced",
|
|
"gauge_updates": [
|
|
{
|
|
"category": "Automobile",
|
|
"previous_value": 45,
|
|
"delta": 2,
|
|
"new_value": 47
|
|
}
|
|
]
|
|
}
|
|
"""
|
|
Et en base de données, la jauge "Automobile" de "user123" est à 47%
|
|
|
|
Scénario: API calcule like automatique standard (30-79% écoute)
|
|
Étant donné que l'utilisateur "user123" a une jauge "Voyage" à 60% en base
|
|
Et qu'un contenu "content789" de 10 minutes est tagué "Voyage"
|
|
Quand je POST /api/v1/listening-events
|
|
"""json
|
|
{
|
|
"user_id": "user123",
|
|
"content_id": "content789",
|
|
"listened_duration_seconds": 300,
|
|
"total_duration_seconds": 600,
|
|
"completion_percentage": 50
|
|
}
|
|
"""
|
|
Alors le statut de réponse est 201
|
|
Et la réponse contient:
|
|
"""json
|
|
{
|
|
"like_type": "automatic_standard",
|
|
"gauge_updates": [
|
|
{
|
|
"category": "Voyage",
|
|
"previous_value": 60,
|
|
"delta": 1,
|
|
"new_value": 61
|
|
}
|
|
]
|
|
}
|
|
"""
|
|
Et en base de données, la jauge "Voyage" de "user123" est à 61%
|
|
|
|
Scénario: API applique like manuel explicite (+2%)
|
|
Étant donné que l'utilisateur "user123" a une jauge "Musique" à 55% en base
|
|
Et qu'un contenu "content999" est tagué "Musique"
|
|
Quand je POST /api/v1/likes
|
|
"""json
|
|
{
|
|
"user_id": "user123",
|
|
"content_id": "content999",
|
|
"like_type": "manual"
|
|
}
|
|
"""
|
|
Alors le statut de réponse est 201
|
|
Et la réponse contient:
|
|
"""json
|
|
{
|
|
"like_id": "<uuid>",
|
|
"gauge_updates": [
|
|
{
|
|
"category": "Musique",
|
|
"previous_value": 55,
|
|
"delta": 2,
|
|
"new_value": 57
|
|
}
|
|
]
|
|
}
|
|
"""
|
|
Et en base de données, la jauge "Musique" de "user123" est à 57%
|
|
|
|
Scénario: API applique unlike (retire like manuel)
|
|
Étant donné que l'utilisateur "user123" a une jauge "Sport" à 57% en base
|
|
Et qu'il a liké manuellement le contenu "content888" tagué "Sport"
|
|
Et que le like a l'ID "like_abc123"
|
|
Quand je DELETE /api/v1/likes/like_abc123
|
|
Alors le statut de réponse est 204
|
|
Et en base de données, la jauge "Sport" de "user123" est à 55%
|
|
Et le like "like_abc123" est supprimé de la table likes
|
|
|
|
Scénario: API refuse unlike d'un like automatique
|
|
Étant donné que l'utilisateur "user123" a écouté un contenu à 90%
|
|
Et qu'il a reçu un like automatique "like_auto456"
|
|
Quand je DELETE /api/v1/likes/like_auto456
|
|
Alors le statut de réponse est 403
|
|
Et la réponse contient:
|
|
"""json
|
|
{
|
|
"error": "CANNOT_UNLIKE_AUTOMATIC",
|
|
"message": "Les likes automatiques ne peuvent pas être retirés"
|
|
}
|
|
"""
|
|
Et en base de données, le like "like_auto456" existe toujours
|
|
|
|
Scénario: API cumule like automatique + like manuel
|
|
Étant donné que l'utilisateur "user123" a une jauge "Technologie" à 50% en base
|
|
Et qu'un contenu "content777" de 10 minutes est tagué "Technologie"
|
|
Quand je POST /api/v1/listening-events
|
|
"""json
|
|
{
|
|
"user_id": "user123",
|
|
"content_id": "content777",
|
|
"completion_percentage": 50
|
|
}
|
|
"""
|
|
Alors la jauge "Technologie" passe à 51% (+1% auto)
|
|
Quand je POST ensuite /api/v1/likes
|
|
"""json
|
|
{
|
|
"user_id": "user123",
|
|
"content_id": "content777",
|
|
"like_type": "manual"
|
|
}
|
|
"""
|
|
Alors la jauge "Technologie" passe à 53% (+2% manuel)
|
|
Et le delta total est de 3%
|
|
|
|
Scénario: API applique bonus abonnement créateur (+5% tous tags)
|
|
Étant donné que l'utilisateur "user123" a les jauges suivantes:
|
|
| catégorie | niveau |
|
|
| Automobile | 50% |
|
|
| Technologie | 45% |
|
|
Et qu'un créateur "creator456" publie des contenus tagués "Automobile" et "Technologie"
|
|
Quand je POST /api/v1/subscriptions
|
|
"""json
|
|
{
|
|
"user_id": "user123",
|
|
"creator_id": "creator456"
|
|
}
|
|
"""
|
|
Alors le statut de réponse est 201
|
|
Et en base de données:
|
|
| catégorie | niveau |
|
|
| Automobile | 55% |
|
|
| Technologie | 50% |
|
|
Et l'abonnement est créé avec bonus appliqué
|
|
|
|
Scénario: API retire bonus désabonnement créateur (-5% tous tags)
|
|
Étant donné que l'utilisateur "user123" a les jauges suivantes:
|
|
| catégorie | niveau |
|
|
| Voyage | 65% |
|
|
| Culture | 58% |
|
|
Et qu'il est abonné au créateur "creator789" qui publie "Voyage" et "Culture"
|
|
Quand je DELETE /api/v1/subscriptions/creator789
|
|
Alors le statut de réponse est 204
|
|
Et en base de données:
|
|
| catégorie | niveau |
|
|
| Voyage | 60% |
|
|
| Culture | 53% |
|
|
|
|
Scénario: API applique pénalité skip rapide (<10s)
|
|
Étant donné que l'utilisateur "user123" a une jauge "Politique" à 50% en base
|
|
Et qu'un contenu "content555" de 300 secondes est tagué "Politique"
|
|
Quand je POST /api/v1/skip-events
|
|
"""json
|
|
{
|
|
"user_id": "user123",
|
|
"content_id": "content555",
|
|
"listened_duration_seconds": 5,
|
|
"total_duration_seconds": 300
|
|
}
|
|
"""
|
|
Alors le statut de réponse est 201
|
|
Et la réponse contient:
|
|
"""json
|
|
{
|
|
"skip_type": "early",
|
|
"gauge_updates": [
|
|
{
|
|
"category": "Politique",
|
|
"previous_value": 50,
|
|
"delta": -0.5,
|
|
"new_value": 49.5
|
|
}
|
|
]
|
|
}
|
|
"""
|
|
Et en base de données, la jauge "Politique" de "user123" est à 49.5%
|
|
|
|
Scénario: API n'applique pas de pénalité pour skip ≥10s et <30%
|
|
Étant donné que l'utilisateur "user123" a une jauge "Économie" à 60% en base
|
|
Et qu'un contenu "content333" de 600 secondes est tagué "Économie"
|
|
Quand je POST /api/v1/skip-events
|
|
"""json
|
|
{
|
|
"user_id": "user123",
|
|
"content_id": "content333",
|
|
"listened_duration_seconds": 120,
|
|
"total_duration_seconds": 600,
|
|
"completion_percentage": 20
|
|
}
|
|
"""
|
|
Alors le statut de réponse est 201
|
|
Et la réponse contient:
|
|
"""json
|
|
{
|
|
"skip_type": "neutral",
|
|
"gauge_updates": []
|
|
}
|
|
"""
|
|
Et en base de données, la jauge "Économie" de "user123" reste à 60%
|
|
|
|
Scénario: API n'applique pas de pénalité pour skip ≥30%
|
|
Étant donné que l'utilisateur "user123" a une jauge "Sport" à 55% en base
|
|
Et qu'un contenu "content222" de 600 secondes est tagué "Sport"
|
|
Quand je POST /api/v1/skip-events
|
|
"""json
|
|
{
|
|
"user_id": "user123",
|
|
"content_id": "content222",
|
|
"listened_duration_seconds": 300,
|
|
"total_duration_seconds": 600,
|
|
"completion_percentage": 50
|
|
}
|
|
"""
|
|
Alors le statut de réponse est 201
|
|
Et la réponse contient:
|
|
"""json
|
|
{
|
|
"skip_type": "late",
|
|
"gauge_updates": []
|
|
}
|
|
"""
|
|
Et en base de données, la jauge "Sport" de "user123" reste à 55%
|
|
|
|
Scénario: API applique évolution sur plusieurs tags simultanément
|
|
Étant donné que l'utilisateur "user123" a les jauges suivantes:
|
|
| catégorie | niveau |
|
|
| Automobile | 45% |
|
|
| Voyage | 60% |
|
|
Et qu'un contenu "content111" est tagué "Automobile" et "Voyage"
|
|
Quand je POST /api/v1/listening-events
|
|
"""json
|
|
{
|
|
"user_id": "user123",
|
|
"content_id": "content111",
|
|
"completion_percentage": 90
|
|
}
|
|
"""
|
|
Alors le statut de réponse est 201
|
|
Et la réponse contient:
|
|
"""json
|
|
{
|
|
"like_type": "automatic_reinforced",
|
|
"gauge_updates": [
|
|
{
|
|
"category": "Automobile",
|
|
"previous_value": 45,
|
|
"delta": 2,
|
|
"new_value": 47
|
|
},
|
|
{
|
|
"category": "Voyage",
|
|
"previous_value": 60,
|
|
"delta": 2,
|
|
"new_value": 62
|
|
}
|
|
]
|
|
}
|
|
"""
|
|
Et en base de données:
|
|
| catégorie | niveau |
|
|
| Automobile | 47% |
|
|
| Voyage | 62% |
|
|
|
|
Scénario: API respecte la borne maximum 100%
|
|
Étant donné que l'utilisateur "user123" a une jauge "Cryptomonnaie" à 99% en base
|
|
Et qu'un contenu "content_crypto" est tagué "Cryptomonnaie"
|
|
Quand je POST /api/v1/listening-events
|
|
"""json
|
|
{
|
|
"user_id": "user123",
|
|
"content_id": "content_crypto",
|
|
"completion_percentage": 95
|
|
}
|
|
"""
|
|
Alors le statut de réponse est 201
|
|
Et la réponse contient:
|
|
"""json
|
|
{
|
|
"like_type": "automatic_reinforced",
|
|
"gauge_updates": [
|
|
{
|
|
"category": "Cryptomonnaie",
|
|
"previous_value": 99,
|
|
"delta": 2,
|
|
"new_value": 100,
|
|
"capped": true
|
|
}
|
|
]
|
|
}
|
|
"""
|
|
Et en base de données, la jauge "Cryptomonnaie" de "user123" est à 100%
|
|
Et la jauge n'a pas dépassé 100%
|
|
|
|
Scénario: API respecte la borne minimum 0%
|
|
Étant donné que l'utilisateur "user123" a une jauge "Politique" à 0.3% en base
|
|
Et qu'un contenu "content_pol" est tagué "Politique"
|
|
Quand je POST /api/v1/skip-events
|
|
"""json
|
|
{
|
|
"user_id": "user123",
|
|
"content_id": "content_pol",
|
|
"listened_duration_seconds": 3,
|
|
"total_duration_seconds": 300
|
|
}
|
|
"""
|
|
Alors le statut de réponse est 201
|
|
Et la réponse contient:
|
|
"""json
|
|
{
|
|
"skip_type": "early",
|
|
"gauge_updates": [
|
|
{
|
|
"category": "Politique",
|
|
"previous_value": 0.3,
|
|
"delta": -0.5,
|
|
"new_value": 0,
|
|
"capped": true
|
|
}
|
|
]
|
|
}
|
|
"""
|
|
Et en base de données, la jauge "Politique" de "user123" est à 0%
|
|
Et la jauge n'est pas devenue négative
|
|
|
|
Scénario: API respecte borne minimum lors désabonnement
|
|
Étant donné que l'utilisateur "user123" a une jauge "Économie" à 3% en base
|
|
Et qu'il est abonné au créateur "creator_eco" qui publie "Économie"
|
|
Quand je DELETE /api/v1/subscriptions/creator_eco
|
|
Alors le statut de réponse est 204
|
|
Et en base de données, la jauge "Économie" de "user123" est à 0% (et non -2%)
|
|
|
|
Scénario: API GET retourne toutes les jauges utilisateur
|
|
Étant donné que l'utilisateur "user123" a les jauges suivantes en base:
|
|
| catégorie | niveau |
|
|
| Automobile | 67% |
|
|
| Voyage | 82% |
|
|
| Économie | 34% |
|
|
| Sport | 50% |
|
|
| Musique | 45% |
|
|
| Technologie | 71% |
|
|
Quand je GET /api/v1/users/user123/interest-gauges
|
|
Alors le statut de réponse est 200
|
|
Et la réponse contient les 12 catégories avec leurs niveaux:
|
|
"""json
|
|
{
|
|
"user_id": "user123",
|
|
"gauges": [
|
|
{"category": "Automobile", "level": 67},
|
|
{"category": "Voyage", "level": 82},
|
|
{"category": "Économie", "level": 34},
|
|
{"category": "Sport", "level": 50},
|
|
{"category": "Musique", "level": 45},
|
|
{"category": "Technologie", "level": 71}
|
|
]
|
|
}
|
|
"""
|
|
|
|
Scénario: API calcule évolution immédiate (pas de batch différé)
|
|
Étant donné que l'utilisateur "user123" a une jauge "Voyage" à 50% en base
|
|
Quand je POST /api/v1/listening-events à 12:00:00
|
|
"""json
|
|
{
|
|
"user_id": "user123",
|
|
"content_id": "content_travel",
|
|
"completion_percentage": 85
|
|
}
|
|
"""
|
|
Alors le statut de réponse est 201
|
|
Quand je GET /api/v1/users/user123/interest-gauges à 12:00:01 (1 seconde après)
|
|
Alors la jauge "Voyage" est à 52%
|
|
Et la mise à jour est visible immédiatement
|
|
|
|
Scénario: API rejette token JWT invalide
|
|
Quand je POST /api/v1/listening-events sans token JWT
|
|
Alors le statut de réponse est 401
|
|
Et la réponse contient:
|
|
"""json
|
|
{
|
|
"error": "UNAUTHORIZED",
|
|
"message": "Token JWT manquant ou invalide"
|
|
}
|
|
"""
|
|
|
|
Scénario: API valide format des données d'entrée
|
|
Quand je POST /api/v1/listening-events
|
|
"""json
|
|
{
|
|
"user_id": "user123",
|
|
"content_id": "content456",
|
|
"completion_percentage": 150
|
|
}
|
|
"""
|
|
Alors le statut de réponse est 400
|
|
Et la réponse contient:
|
|
"""json
|
|
{
|
|
"error": "VALIDATION_ERROR",
|
|
"message": "completion_percentage doit être entre 0 et 100"
|
|
}
|
|
"""
|
|
|
|
Scénario: API gère contenu avec tags inexistants en base
|
|
Étant donné qu'un contenu "content_new" est tagué "NouvelleCategorie" (non encore en base)
|
|
Quand je POST /api/v1/listening-events
|
|
"""json
|
|
{
|
|
"user_id": "user123",
|
|
"content_id": "content_new",
|
|
"completion_percentage": 90
|
|
}
|
|
"""
|
|
Alors le statut de réponse est 201
|
|
Et une nouvelle ligne est créée dans la table interest_gauges:
|
|
| user_id | category | level |
|
|
| user123 | NouvelleCategorie | 52 |
|
|
Et l'initialisation démarre à 50% + 2% de like auto = 52%
|
|
|
|
Scénario: API persiste historique des modifications de jauges
|
|
Étant donné que l'utilisateur "user123" a une jauge "Sport" à 50%
|
|
Quand je POST /api/v1/listening-events qui applique +2%
|
|
Alors une ligne est insérée dans interest_gauge_history:
|
|
| user_id | category | previous_value | delta | new_value | event_type | event_id | timestamp |
|
|
| user123 | Sport | 50 | 2 | 52 | listening_event| <event_uuid> | 2026-02-02T12:00:00 |
|
|
Et cet historique permet d'auditer les évolutions
|
|
|
|
Scénario: API retourne métriques d'évolution utilisateur
|
|
Étant donné que l'utilisateur "user123" a un historique d'évolution en base
|
|
Quand je GET /api/v1/users/user123/interest-gauges/evolution?since=7d
|
|
Alors le statut de réponse est 200
|
|
Et la réponse contient:
|
|
"""json
|
|
{
|
|
"period": "7d",
|
|
"evolution": [
|
|
{
|
|
"category": "Automobile",
|
|
"start_value": 60,
|
|
"end_value": 67,
|
|
"delta": 7,
|
|
"events_count": 15
|
|
},
|
|
{
|
|
"category": "Voyage",
|
|
"start_value": 80,
|
|
"end_value": 82,
|
|
"delta": 2,
|
|
"events_count": 3
|
|
}
|
|
]
|
|
}
|
|
"""
|
|
|
|
# Architecture backend - Services séparés
|
|
|
|
Scénario: Gauge Calculation Service calcule l'ajustement (stateless)
|
|
Étant donné un événement d'écoute avec 85% de complétion
|
|
Quand le Gauge Calculation Service calcule l'ajustement
|
|
Alors le service retourne:
|
|
"""json
|
|
{
|
|
"adjustment_type": "automatic_reinforced",
|
|
"adjustment_value": 2.0,
|
|
"reason": "completion_percentage >= 80%"
|
|
}
|
|
"""
|
|
Et le service est stateless (aucune lecture DB)
|
|
Et le service est testable unitairement
|
|
|
|
Scénario: Gauge Update Service applique l'ajustement (stateful)
|
|
Étant donné qu'un ajustement de +2% a été calculé
|
|
Et que la jauge "Automobile" de "user123" est à 45%
|
|
Quand le Gauge Update Service applique l'ajustement
|
|
Alors la nouvelle valeur est 47% (45 + 2)
|
|
Et la borne [0, 100] est respectée via fonction clamp
|
|
Et la mise à jour est persistée en Redis (immédiat)
|
|
Et la mise à jour est persistée en PostgreSQL (batch async)
|
|
|
|
Scénario: Pattern de calcul - Addition de points absolus
|
|
Étant donné qu'une jauge est à 60%
|
|
Et qu'un ajustement de +2% est calculé
|
|
Quand le calcul est effectué
|
|
Alors la formule est: newValue = currentValue + adjustment
|
|
Et la formule est: newValue = clamp(newValue, 0.0, 100.0)
|
|
Et la nouvelle valeur est 62%
|
|
|
|
Scénario: Pattern de calcul - Éviter multiplication relative
|
|
Étant donné qu'une jauge est à 50%
|
|
Et qu'un ajustement de +2% est calculé
|
|
Quand le calcul est effectué
|
|
Alors la formule utilisée est: 50 + 2 = 52
|
|
Et la formule utilisée n'est PAS: 50 * (1 + 2/100) = 51
|
|
Car l'ajustement est en points absolus, pas relatifs
|
|
|
|
Scénario: Multi-tags - Mise à jour de N jauges simultanément
|
|
Étant donné qu'un contenu a 3 tags: ["Automobile", "Voyage", "Technologie"]
|
|
Et qu'un ajustement de +2% est calculé (écoute 85%)
|
|
Quand le Gauge Update Service applique
|
|
Alors 3 jauges sont mises à jour:
|
|
| catégorie | ajustement |
|
|
| Automobile | +2% |
|
|
| Voyage | +2% |
|
|
| Technologie | +2% |
|
|
Et toutes les mises à jour sont effectuées en une seule transaction
|
|
|
|
Scénario: Persistance Redis immédiate (latence <10ms)
|
|
Étant donné qu'un ajustement doit être persisté
|
|
Quand le Gauge Update Service écrit en Redis
|
|
Alors la latence est < 10ms
|
|
Et la jauge est immédiatement disponible pour recommandations
|
|
Et Redis sert de cache haute performance
|
|
|
|
Scénario: Persistance PostgreSQL asynchrone (batch 5 min)
|
|
Étant donné que 100 ajustements ont été appliqués en Redis
|
|
Quand le batch async s'exécute toutes les 5 minutes
|
|
Alors les 100 ajustements sont écrits en PostgreSQL en batch
|
|
Et la cohérence finale est garantie
|
|
Et l'application reste performante (pas de write sync)
|
|
|
|
Scénario: Séparation responsabilités - Calculation vs Update
|
|
Étant donné un événement d'écoute
|
|
Quand il est traité
|
|
Alors le Gauge Calculation Service calcule l'ajustement (logique métier pure)
|
|
Et le Gauge Update Service applique l'ajustement (persistance)
|
|
Et les deux services sont indépendants
|
|
Et chaque service a une responsabilité unique (SRP)
|
|
|
|
Scénario: Réutilisabilité Calculation Service
|
|
Étant donné le Gauge Calculation Service
|
|
Quand il est utilisé pour:
|
|
| contexte |
|
|
| Like automatique |
|
|
| Skip rapide |
|
|
| Like manuel |
|
|
| Abonnement créateur |
|
|
Alors le même service calcule tous les ajustements
|
|
Et la logique métier est centralisée
|
|
Et il n'y a pas de duplication de code
|