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/premium/README.md
+++ b/docs/domains/premium/README.md
@@ -24,6 +24,7 @@ Le domaine **Premium** gère les abonnements payants et les fonctionnalités exc
 ## Ubiquitous Language

 **Termes métier du domaine** :
+
 - **Premium Subscription** : Abonnement payant mensuel ou annuel
 - **Offline Download** : Téléchargement pour écoute hors-ligne
 - **Sync Queue** : File d'attente de synchronisation offline
--- a/docs/domains/premium/rules/abonnements-notifications.md
+++ b/docs/domains/premium/rules/abonnements-notifications.md
@@ -5,6 +5,7 @@
 **Décision** : Boost +30% au score + reste dans le mix

 **Boost de score abonnements** :
+
 - **+30% au score final** pour contenus d'un créateur suivi
 - Application : multiplicateur sur le score calculé

@@ -13,6 +14,7 @@ score_final_avec_boost = score_final × 1.3
 ```

 **Reste dans le mix** :
+
 - ❌ **Pas de priorité absolue** (pas de file dédiée abonnements)
 - ✅ Contenu suivi entre en **compétition avec autres contenus**
 - ✅ Si créateur suivi publie contenu faible engagement → peut être battu par contenu viral non-suivi
@@ -22,12 +24,14 @@ score_final_avec_boost = score_final × 1.3
 Utilisateur à Paris, 2 contenus disponibles :

 Contenu A (créateur NON suivi) :
+
 - Score géo : 0.9 (très proche)
 - Score intérêts : 0.8
 - Score engagement : 0.7
 → Score final : 0.80

 Contenu B (créateur suivi) :
+
 - Score géo : 0.5 (moyennement proche)
 - Score intérêts : 0.6
 - Score engagement : 0.5
@@ -45,6 +49,7 @@ Contenu B (suivi) : score 0.60 → avec boost 0.78
 ```

 **Justification** :
+
 - **Équilibre** : valorise abonnements sans enfermer utilisateur
 - **Découverte** : contenus viraux/locaux peuvent toujours émerger
 - **Prévisible** : boost fixe, pas de logique opaque
@@ -104,16 +109,19 @@ Tap pour explorer
 ```

 **Filtrage géographique** :
+
 - Si contenu/live hors zone utilisateur → **pas de notification**
 - Évite frustration : "notification pour contenu que je ne peux pas écouter"
 - Exception : contenu national → notifie tous les abonnés

 **Fréquence maximale** :
+
 - **Maximum 10 notifications push/jour** par utilisateur (tous types confondus)
 - Si dépassement : notifications regroupées
 - Message groupé : "🎧 3 nouveaux contenus de créateurs suivis"

 **Plages horaires** :
+
 - **Mode silencieux** : 22h-8h (pas de push, sauf live)
 - Paramétrable utilisateur (désactivation totale possible)
 - Option "Notifications importantes uniquement" (lives uniquement)
@@ -129,6 +137,7 @@ Tap pour explorer
 | **Limite quotidienne** | 10 | Modifiable 5-20 |

 **Justification** :
+
 - **Sécurité routière** : pas de push en conduite (distraction)
 - **Engagement piéton** : push actifs pour audio-guides (valeur ajoutée tourisme)
 - **Pas de spam** : limite 10/jour + mode silencieux
@@ -207,10 +216,12 @@ Liste des séquences :
 | **Quitter** | Tap "×" | Sauvegarde progression, sortie guide |

 **Guidage vocal automatique** :
+
 - Entre 2 séquences : "Vous avez terminé la séquence 2. Dirigez-vous vers la Vénus de Milo pour la séquence 3."
 - Si utilisateur s'éloigne (>50m de la prochaine pièce) : "Vous vous éloignez de la prochaine étape. Consultez le plan."

 **Sauvegarde progression** :
+
 - Position dans guide sauvegardée automatiquement
 - Retour ultérieur : "Reprendre à la séquence 5 ?" ou "Recommencer depuis le début"
 - Historique : guide marqué "Terminé" si toutes séquences écoutées
@@ -251,6 +262,7 @@ Liste des séquences :
 ```

 **Justification** :
+
 - **UX piéton** : navigation tactile adaptée (pas de commandes volant)
 - **Autonomie** : utilisateur maître de son rythme (pas d'enchaînement forcé)
 - **Choix** : plusieurs guides = diversité styles (famille, expert, rapide)
@@ -264,6 +276,7 @@ Liste des séquences :
 **Décision** : 200 abonnements max + désabonnement -5% jauges

 **Nombre maximum d'abonnements** :
+
 - **200 créateurs maximum** par utilisateur
 - Raisons :
  - **Évite spam** : au-delà de 200, notifications ingérables
@@ -271,16 +284,19 @@ Liste des séquences :
  - **Performance** : requêtes SQL optimisées (index sur 200 max)

 **Si limite atteinte** :
+
 - Message : "Vous suivez déjà 200 créateurs. Désabonnez-vous d'un créateur pour en suivre un nouveau."
 - Liste triable : par date abonnement, nb contenus écoutés, dernière activité
 - Suggestion : "Vous n'avez pas écouté [Créateur X] depuis 6 mois, le désabonner ?"

 **Abonnement initial** :
+
 - Impact : **+5% toutes jauges tags du créateur** (voir [Règle 05 - Section 5.3](../../recommendation/rules/interactions-navigation.md#actions-complémentaires-mode-piéton-uniquement))
 - Action : Bouton "S'abonner" dans profil créateur (interface mobile)
 - Immédiat à l'action

 **Désabonnement** :
+
 - Impact : **-5% toutes jauges tags du créateur** (symétrique)
 - Action : Bouton "Se désabonner" dans profil créateur
 - Immédiat à l'action
@@ -300,15 +316,18 @@ Abonnement :
 ```

 **Gestion multi-tags** :
+
 - Si créateur a 3 tags → **+5% sur chacun des 3 tags**
 - Logique : abonnement = signal fort d'affinité à TOUS les sujets du créateur

 **Abonnements réciproques** :
+
 - ❌ **Pas d'abonnement mutuel visible**
 - Créateur ne voit pas qui est abonné (privacy)
 - Créateur voit uniquement : nombre total abonnés (métrique globale)

 **Justification** :
+
 - **Limite 200** : équilibre entre liberté et gestion spam
 - **Symétrie +5%/-5%** : cohérence mathématique, prévisibilité
 - **Privacy** : pas de liste publique abonnés (évite stalking)
--- a/docs/domains/premium/rules/mode-offline.md
+++ b/docs/domains/premium/rules/mode-offline.md
@@ -5,6 +5,7 @@
 **Zone géographique** : Choix manuel utilisateur

 **Options prédéfinies** :
+
 - "Autour de moi" (rayon 50 km position actuelle)
 - "Ma ville" (limite administrative détectée)
 - "Mon département" (sélection liste)
@@ -19,6 +20,7 @@
 | **Premium** | Illimité | "245 contenus (3.2 GB)" |

 **Calcul temps disponible** :
+
 - 50 contenus × 5 min moyenne = 250 min = **4h d'écoute** (suffisant pour gratuits)
 - Premium illimité = limité uniquement par espace disque device

@@ -47,6 +49,7 @@ Exemple : 20 contenus × 5 min × 48 kbps = ~72 MB
 | **Haute** | 64 kbps | ~30 MB/h | **Premium uniquement** |

 **Justification** :
+
 - Standard = bon compromis qualité/taille (Opus 48 kbps = très correct pour voix)
 - Haute réservée Premium = incitation upgrade
 - User peut réduire à "basse" si espace limité
@@ -58,6 +61,7 @@ Exemple : 20 contenus × 5 min × 48 kbps = ~72 MB
 **Durée de validité** : 30 jours après téléchargement

 **Standard industrie** :
+
 - Spotify : 30 jours
 - YouTube Music : 30 jours
 - Deezer : 30 jours
@@ -77,11 +81,13 @@ App détecte WiFi + contenus >25 jours
 ```

 **Notification avant expiration** :
+
 - **J-3** : "X contenus expirent dans 3 jours. Connectez-vous en WiFi pour les renouveler"
 - **J-0** : Suppression automatique
 - **J+0** : Toast "15 contenus expirés ont été supprimés"

 **Justification** :
+
 - **Force reconnexion** : vérifier abonnement actif, contenus légaux
 - **Évite stockage obsolète** : contenus supprimés/modérés ne restent pas
 - **UX transparente** : renouvellement silencieux si WiFi régulier
@@ -91,6 +97,7 @@ App détecte WiFi + contenus >25 jours
 ### 11.3 Synchronisation actions offline

 **Actions stockées localement (SQLite)** :
+
 - Likes/unlikes
 - Abonnements/désabonnements
 - Signalements
@@ -108,11 +115,13 @@ App détecte WiFi + contenus >25 jours
 ```

 **Gestion erreurs sync** :
+
 - Si échec après 3 tentatives → notification : "Impossible de synchroniser. Réessayez plus tard"
 - Actions conservées jusqu'à sync réussie (pas de perte)
 - **Rétention max 7 jours** : après = purge (évite queue infinie)

 **Justification** :
+
 - **Pas de conflit possible** : actions unilatérales user (likes/abonnements)
 - **UX fluide** : pas de blocage offline
 - **Batch = économie** : requêtes HTTP groupées
@@ -187,17 +196,20 @@ User se reconnecte (WiFi détecté)
 ```

 **Bouton "Voir la liste"** :
+
 - Affiche titres + créateurs des contenus supprimés
 - Permet comprendre ce qui a disparu
 - Historique conservé 7 jours (puis purge)

 **Justification KISS** :
+
 - ✅ **Simplicité technique** : pas de grace period complexe, pas de gestion d'états intermédiaires
 - ✅ **Respect créateur** : si créateur supprime = volonté claire immédiate, pas de diffusion prolongée
 - ✅ **Conformité légale** : contenu modéré (illégal, violation CGU) retiré immédiatement, pas de risque juridique
 - ✅ **Cas rare** : peu de créateurs suppriment contenus après publication, impact user limité

 **Post-MVP** : Si feedback négatifs users ("J'étais en train d'écouter et ça s'est coupé brutalement !"), ajouter grace period UNIQUEMENT pour suppression créateur volontaire :
+
 - Motif suppression = "modération RoadWave" → Suppression immédiate (sécurité/légalité)
 - Motif suppression = "créateur volontaire" → Grace period 7 jours + badge "Bientôt retiré"
 - Motif suppression = "passage Premium" → Si user Premium : conserve accès, si gratuit : grace period 7j
--- a/docs/domains/premium/rules/premium.md
+++ b/docs/domains/premium/rules/premium.md
@@ -12,6 +12,7 @@
 **❌ Pas d'essai gratuit**

 **Raisons** :
+
 - **Anti-abus vacances** : évite inscriptions opportunistes (essai 14j avant road trip vacances, puis annulation)
 - **Protection revenus créateurs** : les écoutes Premium rémunèrent créateurs dès jour 1
 - **Simplicité** : pas de gestion période trial + conversion
@@ -20,6 +21,7 @@
 **❌ Pas de partage familial (MVP)**

 **Raisons** :
+
 - Complexité technique (gestion invitations, validation liens, limite devices)
 - Risque abus ("familles" de 6 inconnus)
 - Coût dev/support élevé pour ROI incertain
@@ -27,6 +29,7 @@
 - **Post-MVP** : Si forte demande, offre "Famille" à 9.99€/mois pour 5 comptes

 **Justification tarif** :
+
 - **Aligné marché bas** : Spotify = 10.99€, YouTube Premium = 11.99€, Apple Music = 10.99€
 - **Prix accessible** : cible conducteurs quotidiens (budget raisonnable)
 - **Incitation annuel** : 2 mois offerts = engagement long terme + réduction churn
@@ -100,6 +103,7 @@ Device 1 vraiment offline (mode avion, tunnel)
 ```

 **Boutons** :
+
 - **Reprendre ici** : Coupe l'autre device, reprend lecture sur ce device
 - **Sécuriser mon compte** : Lien vers changement mot de passe + déconnexion tous devices

@@ -119,6 +123,7 @@ Contenus téléchargés valides 30 jours
 #### Détection abus (post-MVP)

 Monitoring patterns suspects (backend analytics) :
+
 - >10 changements devices/jour (suspect)
 - Connexions alternées 2 villes éloignées répétées
 - Signalements users : "je n'ai jamais été à Marseille"
@@ -131,6 +136,7 @@ Action :
 **Pas d'action automatique** (évite faux positifs), juste flag modération manuelle.

 **Justification KISS** :
+
 - ✅ **Simplicité technique** : pas de tracking GPS précis, pas de calcul distances, pas de faux positifs (TGV Paris→Lyon = légitime)
 - ✅ **Assume bonne foi** : majorité users honnêtes, partage compte = minorité, gestion réactive suffit
 - ✅ **Message dissuasif clair** : avertissement CGU dans message coupure, possibilité "Sécuriser compte" si suspicion piratage
@@ -144,12 +150,14 @@ Action :
 **Décision** : Créateur décide (déjà couvert section 9.6)

 **Rappel règles** :
+
 - Toggle "Réservé Premium" par contenu
 - Aucune limite de ratio gratuit/premium
 - Badge 👑 visible
 - Users gratuits : lecture bloquée avec CTA "Passez Premium"

 **Impact algorithme** :
+
 - Contenus premium inclus dans recommandations
 - Si user gratuit → skip automatique (ne consomme pas slot)
 - Si user premium → diffusé normalement selon score
@@ -169,10 +177,12 @@ Action :
 | **Historique écoute** | 100 derniers | Illimité |

 **Qualité audio** :
+
 - Gratuit : 48 kbps Opus (~20 MB/h) = très correct pour voix
 - Premium : 64 kbps Opus (~30 MB/h) = excellente qualité

 **Justification différences** :
+
 - **0 pub** = argument principal (confort écoute)
 - **Qualité audio** = avantage tangible audiophiles
 - **Offline illimité** = use case road trips longs
@@ -191,23 +201,27 @@ Action :
 | **Android App** | Google Play Billing | 5.99€ | 30% (Google) |

 **Majoration mobile (5.99€)** :
+
 - Apple/Google prennent 30% de commission
 - RoadWave majore prix de 20% pour compenser
 - **Incitation web** : Email aux users "Abonnez-vous sur roadwave.com pour 4.99€/mois" (38% moins cher en frais !)

 **Renouvellement automatique** :
+
 - Email rappel **7 jours avant** renouvellement
 - Email confirmation **après** renouvellement réussi
 - Retry automatique si échec paiement (3 tentatives sur 7 jours)
 - Annulation automatique après 3 échecs

 **Annulation** :
+
 - Self-service dans Settings app : "Abonnement > Annuler"
 - Accès Premium maintenu jusqu'à **fin période payée**
 - Pas de remboursement prorata (standard industrie)
 - Email confirmation annulation avec date fin d'accès

 **Réabonnement** :
+
 - Possibilité immédiate
 - ❌ Pas de nouvelle période d'essai (pas d'essai du tout)

@@ -235,6 +249,7 @@ CREATE TABLE subscriptions (
 ```
 Cache Redis : premium:{user_id} → boolean (TTL 1h)
 Refresh via webhooks :
+
 - Mangopay : PAYIN_NORMAL_SUCCEEDED, PAYIN_NORMAL_FAILED
 - Apple : App Store Server Notifications
 - Google : Real-time Developer Notifications