docs: améliorer rendu markdown et navigation mkdocs

- Ajouter ADR-018 (librairies Go) dans TECHNICAL.md - Transformer Shared en menu dépliable dans mkdocs (cohérence avec autres domaines) - Corriger listes markdown (ajout lignes vides avant listes) - Corriger line breaks dans génération BDD (étapes "Et" sur nouvelles lignes) - Ajouter script fix-markdown-lists.sh pour corrections futures Impacte 86 fichiers de documentation et 164 fichiers BDD générés.
2026-02-09 20:49:52 +01:00
parent 95c65b8be1
commit 35aaa105d0
87 changed files with 1044 additions and 91 deletions
--- a/docs/domains/recommendation/rules/interactions-navigation.md
+++ b/docs/domains/recommendation/rules/interactions-navigation.md
@@ -5,6 +5,7 @@
 **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
@@ -14,12 +15,14 @@
 **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)
@@ -34,19 +37,23 @@
 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** :
@@ -76,6 +83,7 @@ Cooldown après ignorance (Redis) :
 ```

 **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
@@ -88,12 +96,14 @@ Cooldown après ignorance (Redis) :
 **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
@@ -119,12 +129,14 @@ Musée du Louvre : La Joconde - @paris_museum
 ⚠️ **Important** : RoadWave utilise une **stratégie de permissions progressive** pour maximiser l'acceptation utilisateur et la validation stores.

 **Étape 1 - Permission de base (tous utilisateurs)** :
+
 - iOS : "Allow While Using App" (`locationWhenInUse`)
 - Android : `ACCESS_FINE_LOCATION`
 - **Demandée** : Au premier lancement (onboarding)
 - **Permet** : Mode voiture complet ✅

 **Étape 2 - Permission arrière-plan (optionnelle, mode piéton uniquement)** :
+
 - iOS : "Allow Always" (`locationAlways`)
 - Android : `ACCESS_BACKGROUND_LOCATION`
 - **Demandée** : Uniquement si user active "Notifications audio-guides piéton" dans settings
@@ -132,6 +144,7 @@ Musée du Louvre : La Joconde - @paris_museum
 - **Permet** : Mode piéton avec notifications push en arrière-plan ✅

 **Si permission arrière-plan refusée** :
+
 - Mode piéton **désactivé** (toggle grisé dans settings)
 - Mode voiture reste **pleinement fonctionnel**
 - Audio-guides accessibles en mode **manuel** (user ouvre app, lance contenu)
@@ -188,6 +201,7 @@ Android (`AndroidManifest.xml`) :
 ```

 **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)
@@ -201,6 +215,7 @@ Android (`AndroidManifest.xml`) :
 **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

@@ -212,15 +227,18 @@ Changements de mode :
 | 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
@@ -241,6 +259,7 @@ Changements de mode :
 | **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
@@ -257,11 +276,13 @@ Utilisateur écoute :
 ```

 **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)
@@ -273,6 +294,7 @@ Utilisateur écoute :
 **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)
@@ -309,12 +331,14 @@ Utilisateur écoute :
 **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)
 ```
@@ -334,11 +358,13 @@ Contenu de 15 minutes (900s) :
 | **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)

@@ -347,17 +373,20 @@ Contenu de 15 minutes (900s) :
 #### 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)

@@ -431,6 +460,7 @@ class AudioPlayerManager {
 #### 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
@@ -439,6 +469,7 @@ class AudioPlayerManager {
 - ✅ **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
@@ -502,6 +533,7 @@ Utilisez les boutons au volant :
   - Persiste : Redis (immédiat) + PostgreSQL (batch async)

 **Séparation des responsabilités** :
+
 - ✅ **Calculation** : Logique métier pure (réutilisable pour auto-like, skip, actions manuelles)
 - ✅ **Update** : Persistance et contraintes techniques

@@ -516,6 +548,7 @@ newValue := currentValue * (1 + adjustment/100)  // NE PAS FAIRE
 ```

 **Persistance** :
+
 - **Redis** : Mise à jour immédiate (latence <10ms)
 - **PostgreSQL** : Batch async toutes les 5 minutes (cohérence finale)
 - Raison : Jauges consultées fréquemment (recommandations temps réel)
@@ -541,12 +574,14 @@ newValue := currentValue * (1 + adjustment/100)  // NE PAS FAIRE
 | **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
@@ -559,11 +594,13 @@ newValue := currentValue * (1 + adjustment/100)  // NE PAS FAIRE
 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é