roadwave/docs/regles-metier/05-interactions-navigation.md

## 5. Interactions et navigation

### 5.1 File d'attente et commande "Suivant"

**Décision** : Pré-calcul 5 contenus avec insertion prioritaire pour points géographiques

**File d'attente** :
- **5 contenus pré-calculés** en cache (Redis)
- Recalcul automatique si :
  - Déplacement >10km
  - Toutes les 10 minutes (rafraîchissement contenu)
  - File d'attente <3 contenus restants

**Insertion prioritaire géo-ancrée (mode voiture uniquement)** :

**Détection** :
- Calcul ETA (Estimated Time of Arrival) via API GPS native iOS/Android
- Notification déclenchée **7 secondes avant** d'arriver au point GPS
- Si vitesse < 5 km/h ET distance < 50m → notification immédiate
- ⚠️ **App doit être ouverte** (pas de détection en arrière-plan en mode voiture)

**Notification** :
- **Sonore uniquement** : bip court ou son personnalisé RoadWave
- **Visuelle minimale** : icône selon type de contenu (🏛️ culture, 👨‍👩‍👧 famille, 🎵 musique, etc.)
- **Compteur visible** : 7...6...5...4...3...2...1 (décompte des secondes)
- **Pas de texte affiché** (éviter distraction conducteur)
- **Pas de bouton "Annuler"** : seul le bouton "Suivant" permet validation

**Actions utilisateur** :
1. User entend notification sonore + voit icône et compteur
2. User appuie "Suivant" dans les 7 secondes → décompte 5s démarre
3. Pendant décompte : contenu actuel continue, compteur visible (5...4...3...2...1)
4. Si contenu actuel se termine pendant décompte → contenu suivant du buffer démarre
5. À la fin du décompte → contenu géolocalisé démarre (fade out/in 0.3s)

**Si user n'appuie pas sur "Suivant"** :
- Notification disparaît après 7 secondes
- Contenu géolocalisé est perdu (pas d'insertion dans file)
- Pas de nouveau contenu géolocalisé pendant **10 minutes** (éviter spam)

**Limitation anti-spam** :
- Maximum **6 contenus géolocalisés par heure**
- Timer reset toutes les heures (rolling window)
- Exception : séquences d'un même audio-guide multi-séquences (comptent comme 1)
- Si quota atteint : notifications suivantes ignorées jusqu'à libération du quota

**Invalidation immédiate** :
- Utilisateur change ses préférences (curseurs géo/découverte/politique)
  - ⚠️ **Modification bloquée si vitesse GPS >10 km/h** (sécurité routière)
- Live démarre d'un créateur suivi dans la zone

**Implémentation** :
```
Redis cache :
  - Clé : user:{user_id}:queue
  - Structure : [content_1, content_2, ..., content_5]
  - Métadonnées : {last_lat, last_lon, computed_at, mode: "voiture"|"pieton"}
  - TTL : 15 minutes

Tracking GPS temps réel (mobile) :
  - Vérification toutes les 1 seconde
  - Calcul ETA vers points géolocalisés proches (rayon 500m)
  - Si ETA ≤ 7s → trigger notification
  - Historique GPS : 30 derniers points pour calcul vitesse moyenne

Quota anti-spam (Redis) :
  - Clé : user:{user_id}:geo_quota
  - Structure : sorted set avec timestamps des 6 derniers contenus
  - TTL : 1 heure
  - Vérification avant notification : ZCOUNT pour compter contenus dernière heure

Cooldown après ignorance (Redis) :
  - Clé : user:{user_id}:geo_cooldown
  - TTL : 10 minutes
  - Set après notification ignorée
```

**Justification** :
- **Expérience fluide** : pas de latence au clic "Suivant"
- **Réactivité géo** : contenu local inséré immédiatement
- **Coût optimisé** : recalcul uniquement si nécessaire
- **Sécurité** : pas de modification en conduite

---

### 5.1.2 Mode piéton (audio-guides)

**Décision** : Notifications push en arrière-plan avec rayon large

**Contexte** :
- Mode piéton détecté automatiquement si vitesse moyenne < 5 km/h
- Cas d'usage : visites à pied, musées, monuments, quartiers historiques
- User n'a pas besoin d'avoir l'app ouverte
- ⚠️ **Fonctionnalité optionnelle** : requiert permission "localisation en arrière-plan" (activée par user)

**Détection** :
- App peut être en arrière-plan (si permission accordée)
- Rayon de détection : **200 mètres** autour du point GPS
- Geofencing iOS/Android pour minimiser consommation batterie
- Permission demandée uniquement si user active "Notifications audio-guides piéton" dans settings

**Notification push système** :

Format :
```
Titre : "Audio-guide à proximité"
Body : "[Nom du contenu] - [Nom créateur]"
Action : Tap → ouvre app sur le contenu
```

Exemple :
```
Audio-guide à proximité
Musée du Louvre : La Joconde - @paris_museum
```

**Permissions requises** :

⚠️ **Important** : Permission "Always Location" est **optionnelle** et demandée uniquement si user active le mode piéton dans settings.

iOS (`Info.plist`) :
```xml
<key>NSLocationWhenInUseUsageDescription</key>
<string>RoadWave utilise votre position pour vous proposer des contenus audio géolocalisés adaptés à votre trajet en temps réel.</string>

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Si vous activez les notifications audio-guides piéton, RoadWave peut vous alerter lorsque vous passez près d'un monument ou musée, même quand l'app est en arrière-plan. Cette fonctionnalité est optionnelle et peut être désactivée à tout moment dans les réglages.</string>
```

Android (`AndroidManifest.xml`) :
```xml
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
```

**Disclosure avant demande permission** (Android requis, iOS recommandé) :

Écran affiché avant demande permission "Always Location" :

```
┌────────────────────────────────────────┐
│ 📍 Notifications audio-guides piéton   │
├────────────────────────────────────────┤
│ Pour vous alerter d'audio-guides à     │
│ proximité même quand vous marchez avec │
│ l'app fermée, RoadWave a besoin de     │
│ votre position en arrière-plan.        │
│                                        │
│ Votre position sera utilisée pour :   │
│ ✅ Détecter monuments à 200m           │
│ ✅ Vous envoyer une notification       │
│                                        │
│ Votre position ne sera jamais :        │
│ ❌ Vendue à des tiers                  │
│ ❌ Utilisée pour de la publicité       │
│                                        │
│ Cette fonctionnalité est optionnelle.  │
│ Vous pouvez utiliser RoadWave sans     │
│ cette permission.                      │
│                                        │
│ [Continuer] [Non merci]                │
│                                        │
│ Plus d'infos : Politique confidentialité│
└────────────────────────────────────────┘
```

**Si user refuse** :
- Mode piéton désactivé (uniquement mode voiture disponible)
- App fonctionne normalement avec permission "When In Use"
- Audio-guides accessibles en mode manuel (user ouvre app, sélectionne contenu)

**Comportement après tap sur notification** :
1. User tap notification push
2. App s'ouvre sur la page du contenu
3. User peut démarrer la lecture manuellement
4. Navigation libre (voir section 16.2 pour audio-guides piéton)

**Basculement automatique voiture ↔ piéton** :

Détection par vitesse GPS moyenne sur 30 secondes :
- Vitesse < 5 km/h (stable 10s) → mode piéton
- Vitesse ≥ 5 km/h (stable 10s) → mode voiture

Changements de mode :

| Mode actuel | Vitesse détectée | Nouveau mode | Effet |
|-------------|------------------|--------------|-------|
| Piéton | ≥ 5 km/h | Voiture | Notifications push → sonores + icône (app ouverte requise) |
| Voiture | < 5 km/h | Piéton | Notifications sonores → push arrière-plan |

**Pas de popup confirmation** :
- Basculement transparent et automatique
- User n'a rien à faire
- Hysteresis (10s) pour éviter basculements intempestifs

**Quota anti-spam mode piéton** :
- Même limitation que mode voiture : **6 contenus/heure**
- Cooldown 10 min si notification ignorée (app pas ouverte après tap)

**Justification** :
- ✅ Expérience adaptée aux visites à pied (rayon large, pas de timing précis)
- ✅ Économie batterie (geofencing natif iOS/Android)
- ✅ User peut garder téléphone en poche
- ✅ Basculement automatique = pas de friction

---

### 5.2 Commande "Précédent"

**Décision** : Comportement smart selon progression écoute

**Règles** :

| Situation | Temps écouté | Action "Précédent" |
|-----------|--------------|-------------------|
| **Début de contenu** | <10 secondes | Retour au contenu précédent (position exacte) |
| **Milieu/fin** | ≥10 secondes | Replay contenu actuel depuis le début |
| **Premier de session** | N/A | Replay depuis début (rien avant) |

**Historique de navigation** :
- **10 contenus maximum** en mémoire (Redis List)
- Structure : `[{content_id, position_seconds, listened_at}, ...]`
- FIFO : au-delà de 10, suppression du plus ancien

**Exemple scénario** :
```
Utilisateur écoute :
1. Contenu A → écoute 5s → "Suivant"
2. Contenu B → écoute 2min30 → "Suivant"
3. Contenu C → écoute 5s → "Précédent"
   → Retour Contenu B à 2min30 (car >10s)
4. Sur Contenu B → "Précédent"
   → Retour Contenu A à 5s (position exacte)
```

**Interface (responsabilité front)** :
- ❌ Pas de message UI
- ✅ Progress bar revient au début ou à position exacte
- ✅ Animation fluide (transition 0.3s)

**Justification** :
- **UX intuitive** : comportement standard Spotify/YouTube
- **Pas de frustration** : si début, vraiment revenir en arrière
- **Simplicité** : règle unique (seuil 10s)

---

### 5.3 Interactions au volant : Like automatique et engagement

> ⚠️ **Architecture Decision Record** : Voir [ADR-010](../adr/010-commandes-volant.md) pour les détails techniques complets

**Décision** : Like automatique basé sur le temps d'écoute

**Problème technique identifié** :
- iOS et Android ne supportent **pas nativement** les appuis longs ou doubles-appuis sur les commandes média
- Les commandes physiques au volant varient selon les véhicules (pas de bouton "Pause" dédié sur beaucoup de modèles)
- Système de double-appui/appui long = **non-intuitif** et **risques sécurité** (regarder écran pour feedback)

---

#### Commandes au volant simplifiées

**Actions disponibles** (100% compatibles tous véhicules) :

| Commande physique | Action RoadWave |
|-------------------|-----------------|
| **Suivant** | Passer au contenu suivant |
| **Précédent** | Revenir au contenu précédent (règle 10s, voir section 5.2) |
| **Play/Pause** | Pause/reprise lecture (fade out 0.3s) |

**Aucune action complexe au volant** → Sécurité routière maximale.

---

#### Like automatique implicite

**Principe** : Le système détecte automatiquement l'intérêt utilisateur selon le temps d'écoute.

**Règles d'attribution** :

| Durée écoutée | Action automatique | Points jauge | Justification |
|---------------|-------------------|--------------|---------------|
| **≥ 80% du contenu** | Like renforcé | +2.0 | Écoute quasi-complète = fort intérêt |
| **30-79% du contenu** | Like standard | +1.0 | Écoute significative = intérêt |
| **< 30% du contenu** | Pas de like | 0 | Écoute trop courte |
| **Skip après <10s** | Signal négatif | -0.5 | Désintérêt marqué |

**Exemples concrets** :
```
Contenu de 3 minutes (180s) :
- Écoute 2min30 (83%) → Like renforcé (+2 points)
- Écoute 1min15 (42%) → Like standard (+1 point)
- Écoute 30s (17%) puis skip → Pas de like
- Skip après 5s → Signal négatif (-0.5 point)

Contenu de 15 minutes (900s) :
- Écoute 13min (87%) → Like renforcé (+2 points)
- Écoute 6min (40%) → Like standard (+1 point)
```

---

#### Actions complémentaires (mode piéton uniquement)

**Interface mobile** (vitesse < 5 km/h) :

| Action | Moyen | Effet |
|--------|-------|-------|
| **Like explicite** | Bouton cœur | +2 points jauge (même si déjà liké auto) |
| **Unlike** | Re-clic cœur (toggle) | -2 points jauge |
| **Abonnement** | Bouton "S'abonner" profil créateur | +5 points toutes jauges tags créateur |
| **Désabonnement** | Bouton "Se désabonner" | -5 points |
| **Signalement** | Menu contextuel "⋮" | Ouverture flux modération |

**Feedback visuel** :
- **Like automatique** : Badge discret "♥ Ajouté à vos favoris" (2s, bas de l'écran)
- **Like explicite** : Animation cœur rouge + vibration courte
- **Abonnement** : Animation étoile dorée + badge "Abonné ✓"

**Disponibilité** :
- ✅ Mode piéton (vitesse < 5 km/h) : toutes les actions disponibles
- ❌ Mode voiture (vitesse ≥ 5 km/h) : aucune de ces actions (sauf like automatique)

---

#### Gestion impacts jauges (algorithme)

**Like automatique** :
- Like renforcé (≥80%) → **+2% jauges** de tous les tags du contenu
- Like standard (30-79%) → **+1% jauges** des tags du contenu
- Signal négatif (skip <10s) → **-0.5% jauges** des tags du contenu

**Actions explicites** :
- Like manuel → **+2% jauges** (cumulable avec like auto)
- Unlike → **-2% jauges**
- Abonnement → **+5% toutes jauges** tags créateur
- Désabonnement → **-5% toutes jauges**

**Persistance** :
- Événements stockés en base (table `listen_events`)
- Mise à jour jauges : **immédiate** (Redis) + **async batch** (PostgreSQL)

---

#### Implémentation technique

**Backend** (Go) :

```go
type ListenEvent struct {
    UserID       string
    ContentID    string
    StartedAt    time.Time
    StoppedAt    time.Time
    Duration     int     // secondes écoutées
    ContentTotal int     // durée totale contenu
    Percentage   float64 // duration / contentTotal * 100
    Action       string  // "completed", "skipped", "paused"
}

func ProcessListenEvent(event ListenEvent) {
    percentage := event.Percentage

    // Signal négatif fort
    if event.Action == "skipped" && event.Duration < 10 {
        UpdateJauges(event.UserID, event.ContentID, -0.5)
        return
    }

    // Like automatique
    if percentage >= 80 {
        AutoLike(event.UserID, event.ContentID, 2.0) // Renforcé
    } else if percentage >= 30 {
        AutoLike(event.UserID, event.ContentID, 1.0) // Standard
    }
    // < 30% : pas de like
}
```

**Mobile** (iOS/Android) :

```swift
// iOS - Tracking écoute
class AudioPlayerManager {
    var startTime: Date?
    let contentDuration: TimeInterval

    func onPlay() {
        startTime = Date()
    }

    func onStop(action: String) { // "completed" | "skipped" | "paused"
        guard let start = startTime else { return }
        let duration = Date().timeIntervalSince(start)
        let percentage = (duration / contentDuration) * 100

        // API call
        API.track(ListenEvent(
            contentId: currentContentId,
            duration: Int(duration),
            percentage: percentage,
            action: action
        ))
    }
}
```

---

#### Justification

**Avantages** :
- ✅ **Sécurité routière maximale** : aucune action complexe au volant
- ✅ **UX intuitive** : comportement standard industrie (Spotify, YouTube Music, Deezer)
- ✅ **Compatibilité 100%** : fonctionne sur tous véhicules, tous OS
- ✅ **Engagement amélioré** : tous les contenus écoutés génèrent des signaux
- ✅ **Algorithme plus précis** : données granulaires (30%, 50%, 80%, 100%)
- ✅ **Simplicité développement** : pas de workarounds complexes iOS/Android

**Inconvénients mitigés** :
- ⚠️ Pas de like explicite en conduite → **Mitigation** : like automatique + vocal (CarPlay/Android Auto)
- ⚠️ Pas d'abonnement en conduite → **Mitigation** : liste "Créateurs à découvrir" dans app
- ⚠️ Like automatique peut surprendre → **Mitigation** : onboarding clair + unlike possible

---

#### Communication utilisateurs (onboarding)

**Écran onboarding 1** :
```
🚗 Conduite sécurisée

RoadWave détecte automatiquement vos goûts
selon vos écoutes.

Plus vous écoutez longtemps, plus
l'algorithme s'améliore !

[Suivant]
```

**Écran onboarding 2** :
```
❤️ Likes automatiques

Pas besoin de liker manuellement :
si vous écoutez >50% d'un contenu,
on comprend que vous aimez !

[Suivant]
```

**Écran onboarding 3** :
```
⏸️ Commandes simples

Utilisez les boutons au volant :
• Suivant → Prochain contenu
• Précédent → Contenu d'avant
• Pause → Mettre en pause

[Commencer]
```

---

### 5.4 Lecture en boucle et enchaînement

**Décision** : Passage automatique après 2s + insertion pub paramétrable

**Fin de contenu** :
1. Audio termine → **Timer 2 secondes** démarre
2. UI overlay : "Contenu suivant dans 2s..." + barre décompte
3. Possibilité annuler : bouton "Rester sur ce contenu" (optionnel)
4. Timer atteint 0 → passage automatique au contenu suivant

**Délai selon contexte** :

| Mode | Délai | Justification |
|------|-------|---------------|
| **Standard** | 2 secondes | Temps réaction confortable |
| **Mode Kids** | 1 seconde | Attention courte enfants |
| **Live** | 0 seconde | Enchaînement immédiat |

**Insertion publicité** :
- Pub s'insère **pendant le délai de 2s** (transition naturelle)
- Fréquence : **paramétrable admin** (défaut : 1 pub / 5 contenus)
- Message : "Publicité (15s)" puis lecture pub
- ⚠️ **Jamais d'interruption** d'un contenu en cours

**Publicité skippable** :
- Durée minimale visionnage : **paramétrable** (défaut : 5 secondes)
- Bouton "Passer" apparaît après délai
- Métriques engagement : taux skip, durée écoute moyenne
- **Like et abonnement autorisés sur pub** (engagement créateur pub)

**Si aucun contenu disponible** :
1. Message : "Aucun contenu disponible dans cette zone"
2. Proposition : "Élargir la zone de recherche ?" (bouton)
3. Si accepté → relance algo avec rayon +50km
4. Sinon → lecture en pause, attente action utilisateur

**Gestion erreurs** :
- Échec chargement contenu suivant → **retry 3× avec backoff exponentiel**
- Si 3 échecs → message "Connexion instable, basculement mode offline"
- Mode offline → lecture contenus téléchargés uniquement

**Justification** :
- **Fluidité** : enchaînement naturel sans action utilisateur
- **Contrôle** : possibilité annuler pendant délai
- **Paramétrabilité pub** : évite frustration excès publicité
- **Engagement pub** : like/abonnement autorisé = monétisation créateurs pub

---

## Récapitulatif Section 5