jpgiannetti/roadwave
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(docs): réorganiser la documentation selon principes DDD

Browse Source 
Réorganise la documentation du projet selon les principes du Domain-Driven Design (DDD) pour améliorer la cohésion, la maintenabilité et l'alignement avec l'architecture modulaire du backend.

**Structure cible:**
```
docs/domains/
├── README.md (Context Map)
├── _shared/ (Core Domain)
├── recommendation/ (Supporting Subdomain)
├── content/ (Supporting Subdomain)
├── moderation/ (Supporting Subdomain)
├── advertising/ (Generic Subdomain)
├── premium/ (Generic Subdomain)
└── monetization/ (Generic Subdomain)
```

**Changements effectués:**

Phase 1: Création de l'arborescence des 7 bounded contexts
Phase 2: Déplacement des règles métier (01-19) vers domains/*/rules/
Phase 3: Déplacement des diagrammes d'entités vers domains/*/entities/
Phase 4: Déplacement des diagrammes flux/états/séquences vers domains/*/
Phase 5: Création des README.md pour chaque domaine
Phase 6: Déplacement des features Gherkin vers domains/*/features/
Phase 7: Création du Context Map (domains/README.md)
Phase 8: Mise à jour de mkdocs.yml pour la nouvelle navigation
Phase 9: Correction automatique des liens internes (script fix-markdown-links.sh)
Phase 10: Nettoyage de l'ancienne structure (regles-metier/, diagrammes/, features/)

**Configuration des tests:**
- Makefile: godog run docs/domains/*/features/
- scripts/generate-bdd-docs.py: features_dir → docs/domains

**Avantages:**
✅ Cohésion forte: toute la doc d'un domaine au même endroit
✅ Couplage faible: domaines indépendants, dépendances explicites
✅ Navigabilité améliorée: README par domaine = entrée claire
✅ Alignement code/docs: miroir de backend/internal/
✅ Onboarding facilité: exploration domaine par domaine
✅ Tests BDD intégrés: features au plus près des règles métier

Voir docs/REFACTOR-DDD.md pour le plan complet.
This commit is contained in:
jpgiannetti
2026-02-07 17:15:02 +01:00
parent 78422bb2c0
commit 5e5fcf4714
227 changed files with 1413 additions and 1967 deletions
Download Patch File Download Diff File Expand all files Collapse all files

854
docs/domains/content/rules/audio-guides.md Normal file
View File

@@ -0,0 +1,854 @@
## 16. Audio-guides multi-séquences
### 16.1 Types d'audio-guides et modes de déplacement
**Décision** : 4 modes distincts avec détection automatique
#### 16.1.1 Classification par mode
| Mode | Vitesse détection | Déclenchement | Use case |
|------|-------------------|---------------|----------|
| **🚶 Piéton** | <5 km/h | Manuel (bouton "Suivant") | Musées, visites urbaines, monuments |
| **🚗 Voiture** | >10 km/h | Auto GPS + Manuel possible | Safari-parc, routes touristiques, circuits auto |
| **🚴 Vélo** | 5-25 km/h | Auto GPS + Manuel possible | Pistes cyclables, circuits vélo, parcours nature |
| **🚌 Transport** | Variable | Auto GPS + Manuel possible | Bus touristiques, trains panoramiques |
**Détection automatique** :
- Vitesse moyenne calculée sur 30 secondes
- Suggestion mode au démarrage : "Détection : 🚗 Voiture. Est-ce correct ? [Oui] [Changer]"
- User peut forcer mode manuellement (settings)
**Justification** :
- Flexibilité maximale créateurs et utilisateurs
- Expériences optimisées par type de déplacement
- Gestion cas limites (vélo lent vs piéton rapide)
---
#### 16.1.2 Création d'un audio-guide (côté créateur)
**Formulaire création** :
```
┌────────────────────────────────────────┐
│ Nouvel audio-guide multi-séquences │
├────────────────────────────────────────┤
│ Titre : [Safari du Paugre] │
│ Description : [Découvrez les animaux │
│ du parc en voiture...] │
│ │
│ Mode de déplacement : *obligatoire │
│ ○ 🚶 Piéton (navigation manuelle) │
│ ● 🚗 Voiture (GPS auto + manuel) │
│ ○ 🚴 Vélo (GPS auto + manuel) │
│ ○ 🚌 Transport (GPS auto + manuel) │
│ │
│ Vitesse recommandée : 30-50 km/h │
│ (si voiture/vélo/transport) │
│ │
│ ──────────────────────────────────── │
│ │
│ Séquences (ordre lecture) : │
│ │
│ 1. [📍] Introduction - Point d'accueil │
│ Lat: 43.1234, Lon: 2.5678 │
│ Rayon déclenchement : 30m │
│ Durée : 2:15 │
│ [🎵 Audio uploadé] [✏️] [🗑️] │
│ │
│ 2. [📍] Enclos des lions │
│ Lat: 43.1245, Lon: 2.5690 │
│ Rayon déclenchement : 30m │
│ Durée : 3:42 │
│ [📤 Upload audio] [✏️] [🗑️] │
│ │
│ 3. [📍] Enclos des girafes │
│ [+ Ajouter point GPS] │
│ │
│ [+ Ajouter séquence] │
│ │
│ 📊 Statistiques : │
│ · 2 séquences complètes │
│ · 5:57 durée totale │
│ · 320m distance totale │
│ │
│ [🗺️ Aperçu sur carte] │
│ [✅ Publier audio-guide] │
└────────────────────────────────────────┘
```
**Métadonnées obligatoires** :
| Champ | Requis | Détails |
|-------|--------|---------|
| **Titre audio-guide** | ✅ | 5-100 caractères |
| **Description** | ✅ | 10-500 caractères |
| **Mode déplacement** | ✅ | Piéton / Voiture / Vélo / Transport |
| **Nombre séquences** | ✅ | Minimum 2, maximum 50 |
| **Point GPS par séquence** | ✅ (sauf piéton) | Latitude, longitude (WGS84) |
| **Rayon déclenchement** | ✅ (sauf piéton) | 10-100m selon mode |
| **Vitesse recommandée** | ❌ | Optionnel, affichée utilisateur |
| **Tags** | ✅ | 1-3 parmi liste prédéfinie |
| **Classification âge** | ✅ | Tout public / 13+ / 16+ / 18+ |
| **Zone diffusion** | ✅ | Polygon géographique |
**Wizard de création** :
- Étape 1 : Infos générales (titre, description, mode)
- Étape 2 : Ajout séquences une par une
- Étape 3 : Preview carte (trace + points)
- Étape 4 : Validation modération (3 premiers audio-guides)
**Justification** :
- Contrôle total créateur sur expérience
- Carte preview aide visualiser parcours
- Wizard guidé = réduction friction création
---
### 16.2 Mode Piéton (manuel)
**Décision** : Navigation manuelle avec pub auto-play
#### 16.2.1 Passage entre séquences
**Séquence normale (sans pub)** :
1. Séquence 1 se termine
2. Player se met en **pause automatique**
3. Message affiché : "Séquence 1 terminée. Appuyez sur Suivant quand vous êtes prêt."
4. User appuie sur [▶|] → Séquence 2 démarre immédiatement
**Séquence avec publicité** (1 pub / 5 séquences) :
1. Séquence 2 se termine
2. **Publicité s'enchaîne automatiquement** (pas d'attente bouton)
3. Pub se lit (skippable après 5s)
4. Pub se termine → Player se met en **pause automatique**
5. Message : "Séquence 3 prête. Appuyez sur Suivant."
6. User appuie sur [▶|] → Séquence 3 démarre
**Schéma flux** :
```
Séquence 1 [fin] → PAUSE → User clique → Séquence 2 [fin] → PUB AUTO-PLAY → PAUSE → User clique → Séquence 3
```
**Fréquence pub** :
- Gratuits : 1 pub toutes les 5 séquences (paramétrable admin 1/3 à 1/10)
- Premium : 0 pub
**Justification** :
- Pub s'insère naturellement (pas d'attente utilisateur pour déclencher)
- User garde contrôle rythme visite (pause après pub)
- Monétisation effective créateurs
- Premium reste attractif (0 interruption)
---
#### 16.2.2 Navigation et contrôles
**Décision** : Liberté totale utilisateur
**Contrôles disponibles** :
| Bouton | Fonction | Comportement |
|--------|----------|--------------|
| **[▶\|] Suivant** | Passe séquence suivante | Immédiat, même si séquence actuelle pas terminée |
| **[\|◀] Précédent** | Retour séquence précédente | Saut direct séquence avant (pas de logique "replay si >10s") |
| **[⏸️] Pause** | Pause temporaire | Reprend à position exacte |
| **[▶️] Play** | Reprend lecture | Continue position actuelle |
| **Liste séquences** | Navigation libre | Tap séquence → saut direct (même séquences non écoutées) |
**Interface liste séquences** :
```
┌────────────────────────────────────────┐
│ 🚶 Audio-guide Piéton │
│ Musée du Louvre │
├────────────────────────────────────────┤
│ [Cover image] │
│ │
│ ▶️ 0:00 ──●────────── 3:42 │
│ │
│ Séquence 3/12 : La Joconde │
│ │
│ [|◀] [⏸️] [▶|] │
│ │
│ ──────────────────────────────────── │
│ │
│ 📋 Liste des séquences │
│ │
│ ✅ 1. Introduction (2:15) │
│ Écouté le 15/01/2026 │
│ │
│ ✅ 2. Pyramide du Louvre (1:48) │
│ Écouté le 15/01/2026 │
│ │
│ ▶️ 3. La Joconde (3:42) - EN COURS │
│ ──●──────────── 1:22/3:42 │
│ │
│ ⭕ 4. Vénus de Milo (2:58) │
│ │
│ ⭕ 5. Code d'Hammurabi (4:12) │
│ │
│ ⭕ 6. Victoire de Samothrace (3:25) │
│ │
│ ... +6 séquences │
│ │
│ [Tout afficher ▼] │
└────────────────────────────────────────┘
```
**Navigation libre** :
- User peut sauter séquences déjà connues
- User peut revenir en arrière à tout moment
- User peut aller directement à séquence 8 (même si 4-7 non écoutées)
**Sauvegarde progression** :
- Checkmarks ✅ sur séquences écoutées >80%
- Position exacte sauvegardée dans séquence en cours
**Justification** :
- Utilisateur contrôle 100% son rythme
- Adapté musées : visitor peut voir physiquement une œuvre lointaine et vouloir écouter sa description
- Pas de frustration (liberté totale)
---
### 16.3 Mode Voiture (GPS automatique)
**Décision** : GPS auto avec navigation manuelle conservée
#### 16.3.1 Déclenchement et contrôles
**Distinction audio-guides vs contenus géolocalisés simples** :
⚠️ **Important** : Les audio-guides multi-séquences fonctionnent différemment des contenus géolocalisés simples.
| Type | Séquences | Déclenchement | Notification | Enchaînement | Comptabilité quota |
|------|-----------|---------------|--------------|--------------|-------------------|
| **Contenu géolocalisé simple** | 1 séquence unique | Notification 7s avant (temps ETA) | Sonore + icône | Fin → retour buffer normal | 1 contenu = 1 quota |
| **Audio-guide multi-séquences** | 2 à 50 séquences | Au point GPS exact (distance 30m) | Ding + toast 2s | Séquences s'enchaînent auto | 1 audio-guide = 1 quota (toutes séquences) |
**Fonctionnement GPS automatique** :
1. User démarre audio-guide en voiture (voir section 16.1 pour démarrage)
2. Séquence 1 démarre automatiquement au point GPS défini (rayon 30m)
3. Séquence 1 se termine
4. **Affichage progress bar** : distance temps réel + ETA jusqu'au prochain point
5. User roule vers point GPS suivant
6. Arrivée au point GPS suivant (rayon 30m) → **déclenchement automatique** séquence suivante
7. Notification sonore discrète : "Ding" (0.3s) + toast 2s : "Enclos des girafes"
8. Séquence suivante démarre immédiatement (pas de décompte)
**Pas de système "7 secondes avant" pour les audio-guides** :
- Contrairement aux contenus géolocalisés simples (voir [05-interactions-navigation.md](05-interactions-navigation.md#511-file-dattente-et-commande-suivant))
- Les séquences se déclenchent **au point GPS exact** (rayon 30m)
- Raison : expérience guidée continue, user sait qu'il suit un parcours
**Navigation manuelle CONSERVÉE** :
| Bouton | État | Comportement |
|--------|------|--------------|
| **[▶\|] Suivant** | ✅ Toujours actif | Passe séquence suivante immédiatement (même hors point GPS) |
| **[\|◀] Précédent** | ✅ Toujours actif | Retour séquence précédente (même hors point GPS) |
| **[⏸️] Pause** | ✅ | Pause temporaire |
| **Liste séquences** | ✅ | Saut direct possible |
**Use cases navigation manuelle** :
| Situation | Solution manuelle |
|-----------|-------------------|
| Embouteillage (séquence finie, point GPS loin) | User clique Suivant → avance manuellement |
| Point GPS inaccessible (route fermée) | User clique Suivant → skip point |
| Envie réécouter séquence précédente | User clique Précédent → retour |
| Passager manipule l'app | Passager navigue librement |
**Avertissement sécurité** :
- Si vitesse **>10 km/h** ET user clique bouton (Suivant/Précédent) :
- Toast 3 secondes : "⚠️ Manipulation en conduite détectée. Pour votre sécurité, demandez à un passager."
- **Action quand même exécutée** (pas de blocage)
- Justification : sensibilisation sans bloquer (passager peut légitimement manipuler)
**Schéma flux** :
```
Point GPS 1 (30m) → Séquence 1 AUTO → User roule → Distance affichée → Point GPS 2 (30m) → Séquence 2 AUTO
↓
User clique Suivant (manuel) → Séquence 2 immédiate
```
**Justification** :
- Flexibilité maximale : GPS optimise expérience MAIS user garde contrôle
- Gestion cas limites : routes fermées, détours, embouteillages
- Sécurité : warning sensibilise sans bloquer (passager légitime)
---
#### 16.3.2 Affichage distance et guidage
**Décision** : Distance + direction (PAS de carte miniature)
**Interface en conduite** :
```
┌────────────────────────────────────────┐
│ 🚗 Audio-guide Voiture │
│ Safari du Paugre │
├────────────────────────────────────────┤
│ │
│ ▶️ 0:00 ──●────────── 2:15 │
│ │
│ Séquence 2/8 : Les lions │
│ │
│ ──────────────────────────────────── │
│ │
│ 📍 Prochain point │
│ │
│ Enclos des girafes │
│ │
│ ┌────────────────────────────────┐ │
│ │ │ │
│ │ ↗️ │ │
│ │ (direction) │ │
│ │ │ │
│ │ 320 mètres │ │
│ │ ≈ 40 secondes │ │
│ │ │ │
│ └────────────────────────────────┘ │
│ │
│ Vitesse actuelle : 28 km/h │
│ Vitesse recommandée : 20-30 km/h │
│ │
│ [|◀] [⏸️] [▶|] [📋 Liste] │
└────────────────────────────────────────┘
```
**Affichage entre deux séquences** :
Quand une séquence se termine et qu'il reste un point GPS suivant, l'interface bascule en mode "attente prochain point" :
```
┌────────────────────────────────────────┐
│ 🚗 Audio-guide Voiture │
│ Safari du Paugre │
├────────────────────────────────────────┤
│ │
│ ✅ Séquence 2/8 terminée │
│ Les lions │
│ │
│ ──────────────────────────────────── │
│ │
│ 📍 Prochain point │
│ │
│ Enclos des girafes │
│ │
│ ┌────────────────────────────────┐ │
│ │ [Progress bar] │ │
│ │ ████████░░░░░░░░░ 65% │ │
│ │ │ │
│ │ ↗️ │ │
│ │ (direction) │ │
│ │ │ │
│ │ 320 mètres │ │
│ │ ≈ 40 secondes │ │
│ │ │ │
│ └────────────────────────────────┘ │
│ │
│ Vitesse actuelle : 28 km/h │
│ │
│ [|◀] [▶️ Rejouer séq.] [▶|] │
└────────────────────────────────────────┘
```
**Progress bar dynamique** :
- Se remplit au fur et à mesure qu'on se rapproche du point
- Calcul : `progress = 100 - (distance_actuelle / distance_initiale * 100)`
- Exemple : distance initiale 500m, distance actuelle 175m → progress = 65%
- Couleur : vert (#4CAF50) pour la partie remplie, gris (#E0E0E0) pour le reste
**Bouton "Rejouer séq."** :
- Permet de réécouter la séquence qui vient de se terminer
- User clique → séquence actuelle redémarre depuis 0:00
- Utile si distraction pendant l'écoute
---
**Informations affichées** :
| Info | Mise à jour | Format |
|------|-------------|--------|
| **Distance** | Chaque seconde | "320 m" / "1.2 km" |
| **ETA** | Chaque seconde | "≈ 40 secondes" / "≈ 2 minutes" |
| **Direction** | Chaque 5s | Flèche indique direction (8 directions : ↑ ↗ → ↘ ↓ ↙ ← ↖) |
| **Vitesse actuelle** | Chaque seconde | "28 km/h" |
| **Vitesse recommandée** | Statique | "20-30 km/h" (définie par créateur) |
| **Progress bar** | Chaque seconde | Pourcentage parcouru vers prochain point |
**Calcul direction** :
```javascript
// Calcul angle entre position actuelle et prochain point
const currentGPS = getCurrentLocation();
const nextPoint = audioGuide.sequences[currentIndex + 1].location;
const angle = calculateBearing(currentGPS, nextPoint); // 0-360°
// Conversion en flèche (8 directions)
const arrows = ['↑', '↗', '→', '↘', '↓', '↙', '←', '↖'];
const index = Math.round(angle / 45) % 8;
const direction = arrows[index];
```
**Calcul ETA** :
```javascript
const distance = calculateDistance(currentGPS, nextPoint); // mètres
const currentSpeed = getCurrentSpeed(); // km/h
if (currentSpeed > 5) {
const eta = (distance / 1000) / currentSpeed * 3600; // secondes
return formatETA(eta); // "≈ 40 secondes" ou "≈ 2 minutes"
} else {
return "En attente de déplacement";
}
```
**Justification** :
- Distance + ETA = info essentielle sans surcharge visuelle
- Direction (flèche) = aide se repérer sans carte complexe
- Simplicité = moins distraction conducteur
- Économie batterie (pas de rendu carte)
---
#### 16.3.3 Rayon de déclenchement et tolérance
**Décision** : Rayon configurable créateur avec défauts intelligents
**Rayons par défaut** :
| Mode | Rayon déclenchement | Rayon "point manqué" | Justification |
|------|---------------------|----------------------|---------------|
| **🚗 Voiture** | 30 mètres | 100 mètres | Vitesse élevée = anticipation |
| **🚴 Vélo** | 50 mètres | 75 mètres | Vitesse variable, arrêts fréquents |
| **🚌 Transport** | 100 mètres | 150 mètres | Arrêts bus/train, moins précis |
**Configuration créateur** :
- Curseur rayon : **10m → 200m**
- Défaut pré-sélectionné selon mode choisi
- Preview visuel : cercle sur carte (lors création)
- Suggestion auto : "Recommandé : 30m pour voiture à 30 km/h"
**Gestion point manqué** :
```
User passe à 110m du point GPS
(hors rayon déclenchement 30m MAIS dans rayon tolérance 100m)
↓
Toast : "⚠️ Point manqué : Enclos des girafes"
↓
Popup 5 secondes :
┌────────────────────────────────────┐
│ Point manqué │
│ │
│ "Enclos des girafes" │
│ Vous êtes passé à 110m du point │
│ │
│ [🔊 Écouter quand même] │
│ [⏭️ Passer au suivant] │
│ [🔙 Faire demi-tour] │
└────────────────────────────────────┘
```
**Actions popup** :
| Bouton | Comportement |
|--------|--------------|
| **Écouter quand même** | Lance séquence immédiatement (même hors zone) |
| **Passer au suivant** | Skip séquence, continue vers prochain point |
| **Faire demi-tour** | Lance navigation GPS externe (Google Maps / Waze) vers point manqué |
**Si user au-delà rayon tolérance (>100m)** :
- Aucun popup (point trop loin, probablement hors itinéraire)
- User peut naviguer manuellement (bouton Suivant)
**Justification** :
- Flexibilité créateur (ajuste selon terrain, vitesse prévue)
- Gestion intelligente imprévus (détours, routes fermées)
- User pas bloqué (toujours moyen avancer)
---
#### 16.3.4 Système double clic et sortie audio-guide
**Problème** : Que se passe-t-il si l'utilisateur clique "Suivant" pendant un audio-guide en mode voiture, alors qu'il est bloqué dans un embouteillage et va mettre 30 minutes pour atteindre le prochain point GPS ?
**Solution** : Système intelligent à double clic permettant de désactiver le GPS automatique puis de sortir de l'audio-guide.
##### Comportement bouton [▶|] Suivant
**1. Premier clic (mode GPS auto actif)** :
- Désactive GPS automatique
- Passe à la séquence suivante immédiatement
- Bascule en **mode manuel**
- Toast 3s : "Mode manuel activé. Cliquez à nouveau pour quitter l'audio-guide."
- Timer 10 secondes démarre
**2. Deuxième clic (dans les 10 secondes suivantes)** :
- Sort de l'audio-guide
- Audio-guide mis en **pause** (historique conservé)
- Retour au **flux normal** (algorithme de recommandation)
- Toast 2s : "Audio-guide en pause"
**3. Clics suivants (après 10 secondes)** :
- Passe à la séquence suivante (comportement standard mode manuel)
- Timer 10 secondes redémarre à chaque clic
**Schéma** :
```
Mode GPS auto → [Clic 1] → Mode manuel + séquence suivante + timer 10s
↓
[Clic 2 < 10s] → Sortie audio-guide + pause
↓
[Clic après 10s] → Séquence suivante + reset timer
```
##### Comportement bouton [|◀] Précédent
| Contexte | Action | Résultat |
|----------|--------|----------|
| **Dans audio-guide** (GPS auto ou manuel) | Séquence précédente (ou replay si <10s) | Reste dans audio-guide |
| **Hors audio-guide** (flux normal) | Contenu précédent | Si contenu précédent = audio-guide → reprend audio-guide |
##### Mode manuel
- **Persistant** : Reste actif jusqu'à fin audio-guide
- **Pas de réactivation GPS auto** pendant session en cours
- **Reset au redémarrage** : Si audio-guide relancé plus tard → repart en mode GPS auto par défaut
##### Détection et reprise après détour
**Règle 1 : Détection "hors itinéraire"**
```
Si user à >1 km de tous points GPS pendant >10 min :
→ Toast : "Audio-guide en pause (hors itinéraire)"
→ Icône audio-guide passe en gris (inactif)
```
**Règle 2 : Détection "retour sur itinéraire"**
```
Si user revient à <100m d'un point GPS non écouté :
→ Popup : "Reprendre audio-guide à la séquence X ?"
→ 3 boutons : Reprendre / Voir liste / Ignorer
```
**Règle 3 : Respect des clics manuels**
```
Si user a cliqué "Suivant" manuellement :
→ Séquence considérée "skippée volontairement"
→ Pas de proposition automatique de revenir en arrière
→ User peut revenir manuellement via liste séquences
```
##### Implémentation technique (référence)
```javascript
let lastSuivantClickTime = null;
const DOUBLE_CLICK_DELAY = 10000; // 10 secondes
function onSuivantClick() {
const now = Date.now();
if (audioGuideState.mode === 'gps_auto') {
// 1er clic : Désactive GPS auto
audioGuideState.mode = 'manual';
playNextSequence();
showToast("Mode manuel activé. Cliquez à nouveau pour quitter.", 3000);
lastSuivantClickTime = now;
}
else if (audioGuideState.mode === 'manual') {
if (lastSuivantClickTime && (now - lastSuivantClickTime) < DOUBLE_CLICK_DELAY) {
// 2ème clic rapide : Sort de l'audio-guide
pauseAudioGuide();
returnToNormalFlow();
showToast("Audio-guide en pause", 2000);
} else {
// Clic normal : Séquence suivante
playNextSequence();
lastSuivantClickTime = now;
}
}
}
```
**Justification** :
- Résout le problème des embouteillages (30 min sans contenu)
- Double intention claire : désactiver GPS puis sortir
- User garde toujours le contrôle (peut reprendre audio-guide plus tard)
- Historique conservé (pas de perte de progression)
---
### 16.4 Modes Vélo et Transport
**Décision** : Même logique voiture avec tolérances ajustées
**Différences par rapport à mode voiture** :
| Paramètre | Voiture | Vélo | Transport |
|-----------|---------|------|-----------|
| **Rayon déclenchement** | 30m | 50m | 100m |
| **Rayon tolérance "point manqué"** | 100m | 75m | 150m |
| **Vitesse recommandée affichée** | 20-50 km/h | 10-25 km/h | Variable (selon ligne) |
| **Warning sécurité** | >10 km/h | >5 km/h | Désactivé |
**Mode Vélo spécificités** :
- Rayon plus large : vitesse variable, nombreux arrêts (feux, piétons)
- Warning sécurité dès 5 km/h (vélo en mouvement)
- Tolérance GPS moins stricte (tracé moins prévisible qu'auto)
**Mode Transport spécificités** :
- Rayon très large : arrêts fréquents (bus, train), ligne fixe
- Pas de warning sécurité (user = passager, pas conducteur)
- Vitesse recommandée = "Selon ligne" (pas de valeur fixe)
- Tolérance horaire : si bus en retard, point peut se déclencher avec 2-3 min de délai
**Comportement identique voiture** :
- Navigation manuelle conservée (boutons actifs)
- Affichage distance + ETA + direction
- Gestion point manqué
- Pub entre séquences
**Justification** :
- Vélo : moins de contrôle qu'auto (obstacles, arrêts), nécessite tolérance
- Transport : moins de contrôle utilisateur (suit ligne fixe), rayon large compense
- Même UX globale = cohérence
---
### 16.5 Publicités dans audio-guides
**Décision** : Pub auto-play entre séquences TOUS modes
#### 16.5.1 Règles universelles
**Insertion publicité** :
- Fréquence : **1 pub toutes les 5 séquences** (paramétrable admin 1/3 à 1/10)
- Gratuits uniquement, **Premium 0 pub**
- Pub s'enchaîne **automatiquement** après séquence
- Skippable après **5 secondes** (règle standard RoadWave)
- Volume normalisé -14 LUFS (comme pubs normales)
**Comportement MODE PIÉTON** :
```
Séquence 2 [fin]
→ Pub AUTO-PLAY
→ Pub se termine
→ PAUSE AUTO
→ Message "Séquence 3 prête. Appuyez sur Suivant."
→ User clique [▶|]
→ Séquence 3 démarre
```
**Comportement MODE VOITURE/VÉLO/TRANSPORT** :
```
Séquence 2 [fin]
→ Pub AUTO-PLAY
→ Pub se termine
→ ATTENTE point GPS suivant OU user clique Suivant
→ Séquence 3 démarre
```
**Schéma complet** :
| Mode | Après séquence normale | Après pub |
|------|------------------------|-----------|
| **Piéton** | Pause + attente user | Pause + attente user |
| **Voiture** | Attente GPS OU user clique Suivant | Attente GPS OU user clique Suivant |
| **Vélo** | Attente GPS OU user clique Suivant | Attente GPS OU user clique Suivant |
| **Transport** | Attente GPS OU user clique Suivant | Attente GPS OU user clique Suivant |
**Justification** :
- Monétisation équitable créateurs (tous modes participent)
- Pub s'insère naturellement (auto-play, pas d'attente utilisateur)
- User garde contrôle : piéton clique Suivant, voiture peut skip manuel
- Premium reste attractif (expérience 0 interruption)
- Modèle économique viable
---
#### 16.5.2 Métriques pub audio-guides
**Dashboard créateur** :
| Métrique | Affichage |
|----------|-----------|
| **Impressions pub** | Nombre de pubs insérées dans audio-guides |
| **Écoutes complètes pub** | Nombre de pubs écoutées >80% |
| **Taux skip pub** | % pubs skippées avant 5s vs après |
| **Revenus pub audio-guides** | 3€ / 1000 écoutes complètes (6% CA pub) |
**Distinction contenus normaux vs audio-guides** :
- Dashboard sépare : "Revenus contenus classiques" / "Revenus audio-guides"
- Permet créateur voir performance par type
**Justification** :
- Transparence créateur (comprend revenus)
- Incite création audio-guides (nouvelle source revenus)
---
### 16.6 Reprise et sauvegarde progression
**Décision** : Sauvegarde complète automatique avec popup intelligente
#### 16.6.1 Sauvegarde automatique
**Données sauvegardées** :
| Info | Détail | Utilité |
|------|--------|---------|
| **Audio-guide ID** | Identifiant unique | Retrouver audio-guide |
| **Séquence actuelle** | Index (ex: 3/12) | Reprise position |
| **Position dans séquence** | Timestamp exact (ex: 1:42/3:20) | Reprise exacte |
| **Séquences écoutées** | Liste avec checkmarks ✅ | Historique progression |
| **Date dernière écoute** | Timestamp | Proposer reprise si <30j |
| **GPS dernière position** | Coordonnées optionnelles | Info contextuelle (non utilisée pour reprise) |
**Stockage** :
| Environnement | Technologie | Utilité |
|---------------|-------------|---------|
| **Local** | SQLite mobile | Fonctionnement offline |
| **Cloud** | PostgreSQL (sync auto) | Multi-device (reprendre sur autre appareil) |
**Synchronisation** :
- Sauvegarde locale : chaque fin de séquence + chaque 30s
- Sync cloud : à la reconnexion réseau (batch)
**Justification** :
- Expérience fluide (pas de perte progression)
- Multi-device (démarrer sur iPhone, continuer sur iPad)
- Offline-first (fonctionne sans réseau)
---
#### 16.6.2 Interface de reprise
**Conditions popup** :
- Dernière écoute **<30 jours**
- Progression **>0%** et **<100%** (pas terminé)
**Popup reprise** :
```
┌────────────────────────────────────────┐
│ Reprendre l'audio-guide ? │
├────────────────────────────────────────┤
│ 🚗 Safari du Paugre │
│ @safari_createur │
│ │
│ Progression : 3/8 séquences écoutées │
│ Dernière écoute : il y a 2 jours │
│ │
│ Vous étiez à : │
│ "Les lions" (1:42/3:20) │
│ │
│ [▶️ Reprendre] [🔄 Recommencer] │
│ [📋 Voir toutes les séquences] │
└────────────────────────────────────────┘
```
**Actions** :
| Bouton | Comportement |
|--------|--------------|
| **Reprendre** | Continue séquence 3 à position 1:42 exacte |
| **Recommencer** | Reset progression, démarre séquence 1 depuis 0:00 |
| **Voir séquences** | Affiche liste complète, user choisit séquence départ |
**Expiration progression** :
- Progression conservée **30 jours**
- Après 30j : popup "Audio-guide expiré. Recommencez depuis le début ?"
- Suppression données progression (mais historique "écouté" préservé)
**Justification** :
- Contexte clair : user sait exactement où il en est
- Flexibilité : reprendre OU recommencer (choix utilisateur)
- 30 jours = raisonnable pour tourisme multi-jours ou retour ultérieur
---
#### 16.6.3 Multi-device
**Scénario** :
1. User démarre audio-guide sur iPhone (séquences 1-3)
2. Progression sync cloud
3. Lendemain : user ouvre app sur iPad
4. Popup : "Reprendre Safari du Paugre sur cet appareil ?"
5. User clique Reprendre → continue séquence 4
**Conflit de version** :
- Si modifications simultanées 2 appareils (rare) : **dernière modification gagne**
- Toast : "Progression mise à jour depuis votre autre appareil"
**Justification** :
- Confort utilisateur (change d'appareil librement)
- Use case réel : planning trajet sur tablette, écoute sur smartphone en voiture
---
## Récapitulatif Section 16
| Point | Décision | Coût | Complexité |
|-------|----------|------|------------|
| **16.1** Types audio-guides | 4 modes (piéton/voiture/vélo/transport) avec détection auto | 0€ | Moyenne |
| **16.1.2** Création | Formulaire séquences + GPS + rayon + wizard guidé | 0€ | Moyenne |
| **16.2.1** Piéton - Passages | Manuel AVEC pub auto-play entre séquences, pause après | 0€ | Faible |
| **16.2.2** Piéton - Navigation | Liberté totale (skip, retour, saut direct liste) | 0€ | Faible |
| **16.3.1** Voiture - Déclenchement | GPS auto + boutons manuels actifs (warning sécurité si >10 km/h) | 0€ | Moyenne |
| **16.3.2** Voiture - Affichage | Distance + ETA + direction (flèche) + vitesse (PAS de carte) | 0€ | Faible |
| **16.3.3** Voiture - Rayon | Configurable créateur (défauts 30m/50m/100m selon mode) | 0€ | Faible |
| **16.4** Vélo & Transport | Mêmes règles avec tolérances ajustées + warning adapté | 0€ | Faible |
| **16.5** Publicités | 1/5 séquences, auto-play TOUS modes, skippable 5s | 0€ | Faible |
| **16.6.1** Sauvegarde | Complète (séquence + position + historique) local + cloud | 0€ | Faible |
| **16.6.2** Reprise | Popup intelligente avec choix (reprendre/recommencer), expiration 30j | 0€ | Faible |
| **16.6.3** Multi-device | Sync cloud PostgreSQL (reprendre sur autre appareil) | 0€ | Faible |
**Coût total MVP : 0€** (GPS natif, calcul distance PostGIS)
---
## Points d'attention pour Gherkin
- Tester 4 modes audio-guides (détection vitesse auto)
- Tester création séquences avec points GPS + rayon configurable
- Tester mode piéton : pause après séquence + pub auto-play + pause après pub + clic Suivant
- Tester navigation libre piéton (skip, retour, saut direct liste)
- Tester mode voiture : déclenchement GPS auto rayon 30m
- Tester navigation manuelle voiture : boutons actifs + warning si vitesse >10 km/h
- **Tester 1er clic Suivant (mode GPS auto) : passage mode manuel + séquence suivante immédiate + toast + timer 10s**
- **Tester 2ème clic Suivant <10s : sortie audio-guide + pause + retour flux normal**
- **Tester clics Suivant >10s : navigation séquences normale + reset timer**
- **Tester Précédent : retour séquence précédente ou replay si <10s écoulé**
- **Tester détection hors itinéraire >1km + >10min : toast + icône gris**
- **Tester détection retour sur itinéraire <100m point GPS non écouté : popup 3 boutons**
- **Tester respect clics manuels : séquences skippées volontairement non reproposées auto**
- Tester affichage distance + ETA + direction (flèche 8 directions)
- Tester rayon tolérance "point manqué" (popup 3 actions)
- Tester mode vélo (rayon 50m) et transport (rayon 100m)
- Tester insertion pub 1/5 séquences tous modes avec auto-play
- Tester sauvegarde progression locale + sync cloud
- Tester popup reprise (3 boutons : reprendre/recommencer/voir liste)
- Tester expiration progression 30 jours
- Tester multi-device : démarrer iPhone, continuer iPad
- Tester gestion conflit progression simultanée 2 appareils