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

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

View File

@@ -0,0 +1,254 @@
## 7. Radio live
### 7.1 Démarrage d'un live
**Décision** : Buffer 15s + notification abonnés + limite 8h
**Processus de démarrage** :
1. Créateur appuie "Démarrer live" dans l'app
2. **Vérification pré-live** :
- Connexion ≥1 Mbps upload (warning si insuffisant)
- Micro autorisé
- Zone diffusion déjà définie (ville, département, région, national)
3. **Buffer initial 15 secondes** avant diffusion publique
- Créateur parle pendant 15s → accumulation buffer serveur
- Message créateur : "Live démarre dans 15s... Testez votre micro"
- Permet vérifier qualité audio avant diffusion
4. Après 15s → **Live public**, auditeurs peuvent rejoindre
**Notification abonnés** :
-**Push notification immédiate** à tous les abonnés dans la zone géographique
- Message : "🔴 [Nom créateur] est en direct : [Titre live]"
- Tap notification → ouverture app + lecture live immédiate
- **Filtrage géographique** : si abonné hors zone, pas de notif (évite frustration)
**Limite de durée** :
- **Maximum 8 heures** par session live
- Warning créateur à 7h30 : "Votre live se terminera dans 30 min"
- Si besoin continuer → arrêt + redémarrage nouveau live (évite abus ressources serveur)
**Métadonnées obligatoires** :
| Champ | Format | Validation |
|-------|--------|------------|
| **Titre** | 5-100 caractères | Ex: "Discussion politique en direct" |
| **Tags** | 1-3 centres d'intérêt | Sélection liste prédéfinie |
| **Classification âge** | Enum | Tout public / 13+ / 16+ / 18+ |
| **Zone diffusion** | Geo | Ville / Département / Région / National |
**Contenus interdits en live** :
| Type | Description | Sanction |
|------|-------------|----------|
| **Concert/spectacle** | Diffusion concert en direct depuis la salle | Strike 2 immédiat + suspension 7 jours |
| **Événement sportif payant** | Match, compétition avec droits TV | Strike 2 immédiat + suspension 7 jours |
| **Œuvre protégée** | Film, série, musique en fond sans droits | Strike 1 + suspension 3 jours + suppression live |
| **Contenu violent** | Agression, violence physique | Strike 3 immédiat + suspension 30 jours |
| **Contenu illégal** | Apologie terrorisme, pédopornographie | Strike 4 (ban définitif) + signalement autorités |
**Exemple usecase interdit** :
```
❌ Utilisateur dans salle de concert diffuse live performance
→ Violation droits d'auteur + droits de diffusion
→ Détection : modération réactive (signalements) + IA audio fingerprint
→ Sanction : Strike 2 (suspension 7 jours) + suppression live + suppression replay
```
**Détection violations** :
- **Signalement utilisateurs** : bouton "Signaler" accessible pendant live
- **IA audio fingerprint** : détection musique protégée en arrière-plan (post-MVP, voir [Section 18](18-detection-contenu-protege.md))
- **Modération réactive** : modérateurs peuvent écouter lives signalés en temps réel
- **Coupure immédiate** : modérateur peut arrêter live si contenu illégal évident
**Justification** :
- **Buffer 15s** : équilibre entre test qualité et friction minimale
- **Notification abonnés** : engagement maximal, valeur ajoutée live
- **8h max** : couvre 99% cas usage (podcasts longs, émissions radio) sans abus
- **Interdictions strictes** : protection juridique plateforme (DSA EU, droits d'auteur)
- **Coût** : WebRTC ingestion + HLS distribution (réutilise infra existante)
---
### 7.2 Arrêt du live
**Décision** : Compte à rebours 5s + tolérance déconnexion 60s + enregistrement auto
**Fin manuelle créateur** :
1. Créateur appuie "Arrêter live"
2. **Compte à rebours 5 secondes** affiché
- Message audio : "Ce live se termine dans 5... 4... 3... 2... 1"
- Permet au créateur de faire un outro propre
- Annulable pendant décompte (bouton "Annuler")
3. Timer atteint 0 → arrêt diffusion
4. **Traitement post-live automatique** démarre (voir ci-dessous)
**Fin automatique si déconnexion** :
| Durée coupure | Comportement |
|---------------|--------------|
| **<60 secondes** | Message auditeurs : "Connexion créateur perdue, reconnexion en cours..." |
| **≥60 secondes** | Arrêt automatique live + message : "Le live est terminé suite à une coupure de connexion" |
**Enregistrement automatique** :
**Obligatoire et automatique** (valeur ajoutée énorme)
**Processus** :
1. Pendant live : enregistrement continu serveur (format Opus raw)
2. Fin live → **job asynchrone** (worker Go + FFmpeg) :
- Conversion MP3 256 kbps (qualité optimale)
- Génération segments HLS (comme contenu classique)
- Normalisation volume -14 LUFS
- Détection silences prolongés (nettoyage)
3. **Publication automatique** du replay :
- Titre : "[REPLAY] [Titre live original]"
- Même zone diffusion, tags, classification
- Disponible sous **5-10 minutes** après fin live
- Type géo : automatiquement "Géo-neutre" (replay = contenu pérenne)
**Options créateur** :
| Option | Défaut | Description |
|--------|--------|-------------|
| **Publier replay automatiquement** | ✅ OUI | Désactivable avant démarrage live |
| **Supprimer replay après coup** | ✅ Possible | Suppression standard contenu |
| **Modifier replay** | ❌ Non | Intégrité enregistrement |
**Conservation fichier source** :
- Opus raw conservé **7 jours** après fin live (backup)
- Suppression automatique après 7j (économie stockage)
- Si replay supprimé par créateur → fichier raw supprimé immédiatement
**Justification** :
- **Compte à rebours 5s** : outro propre, pas de coupure brutale
- **Tolérance 60s** : évite arrêts intempestifs (tunnel, changement cellule)
- **Enregistrement auto** : valorisation contenu éphémère, génération contenu pérenne
- **MP3 256 kbps** : qualité optimale pour replay (vs 48 kbps live)
- **Coût** : stockage minimal (Opus → MP3 1× par live, puis suppression raw après 7j)
---
### 7.3 Comportement auditeur
**Décision** : Buffer 15s + continuation hors zone + reconnexion au live actuel + écoute passive uniquement
**Buffer de synchronisation** :
- **15 secondes** entre créateur et auditeurs
- Raisons :
- Stabilité réseau mobile (3G/4G fluctuant)
- Synchronisation approximative acceptable (pas besoin temps réel strict)
- Permet buffering anticiper coupures courtes (tunnels)
**Comparaison buffers** :
| Buffer | Avantages | Inconvénients | Décision |
|--------|-----------|---------------|----------|
| 5s | Quasi temps réel | Instable 3G, coupures fréquentes | ❌ |
| 10s | Bon compromis | Légèrement juste pour 3G | ❌ |
| **15s** | **Stabilité optimale 3G/4G** | Léger décalage acceptable | ✅ |
| 20s+ | Très stable | Décalage trop perceptible | ❌ |
**Zone géographique pendant live** :
-**Continuation si sortie de zone**
- Scénario : auditeur écoute live régional → sort du département → **live continue**
- Raisons :
- Pas de coupure brutale (mauvaise UX)
- Écoute engagée = terminer naturellement
- Après fin live → algo normal (pas de contenus hors zone)
**Reconnexion après coupure réseau** :
| Durée coupure | Comportement |
|---------------|--------------|
| **<90 secondes** | Reprend au live actuel (pas au buffer ancien) + saut temporel transparent |
| **≥90 secondes** | Message : "Live en cours perdu, passage au contenu suivant" + algo propose contenu normal |
**Interactions disponibles** :
**Décision ferme** : ❌ **Aucun chat en direct, ni maintenant ni dans le futur**
**Raisons** :
- **Sécurité routière** : pas de distraction en voiture (focus UX)
- **Harcèlement** : évite contenu haineux, insultes, trolling
- **Modération** : pas de coût modération temps réel (impossible à scale)
- **Simplicité** : écoute passive = expérience uniforme
**Actions autorisées pendant live** :
| Action | Disponible | Effet |
|--------|------------|-------|
| **Like** | ✅ | Bouton cœur interface mobile (véhicule arrêté) |
| **Abonnement créateur** | ✅ | Bouton profil créateur (interface mobile) |
| **Skip** | ✅ | Passe au contenu suivant, sort du live |
| **Précédent** | ❌ | Pas de sens sur live (flux temps réel) |
| **Chat** | ❌ | Jamais implémenté (décision définitive) |
| **Réactions emoji** | ❌ | Jamais implémenté (décision définitive) |
**Messages utilisateur** :
- "💬 Les discussions ne sont pas disponibles sur RoadWave pour garantir votre sécurité en voiture et éviter le harcèlement."
**Justification décision définitive** :
- **UX cohérente** : RoadWave = écoute en conduisant, pas réseau social interactif
- **Bien-être** : évite toxicité, harcèlement, haine (fléau réseaux sociaux)
- **Juridique** : pas de risque contentieux modération chat (DSA EU)
- **Coût** : 0€ infra chat, 0€ modération temps réel
- **Différenciation** : positionnement "audio safe" vs plateformes toxiques
---
### 7.4 Architecture technique
**Stack** :
```
Créateur (App mobile)
↓ WebRTC (OPUS 48 kbps)
Serveur Ingestion (Go + Pion WebRTC)
↓ Conversion temps réel
Serveur HLS (segments .ts)
↓ NGINX Cache (OVH VPS)
Auditeurs (App mobile, HLS natif)
```
**Flux détaillé** :
1. **Créateur** → WebRTC OPUS 48 kbps vers serveur Go
2. **Serveur Go** → Conversion temps réel OPUS → segments HLS (.m3u8 + .ts)
3. **NGINX Cache (OVH VPS)** → Distribution HLS avec cache
4. **Auditeurs** → Lecture HLS native iOS/Android (buffer 15s)
5. **Enregistrement parallèle** → Opus raw stocké temporairement
6. **Post-live** → Job async : Opus → MP3 256 kbps → Publication replay
**Dépendances** :
-**Pion WebRTC** (Go library, open source, MIT license)
-**FFmpeg** (conversion audio, LGPL/GPL)
-**NGINX** (cache et distribution HLS, open source)
-**OVH Object Storage** (stockage origin, compatible S3)
-**PostgreSQL + Redis** (métadonnées live + cache)
**Avantages** :
- ✅ Pas de dépendance Google/Facebook/Cloudflare (souveraineté)
- ✅ WebRTC standard ouvert (Pion = lib Go pure)
- ✅ Réutilise infra HLS existante (pas de doublon)
- ✅ NGINX Cache (OVH VPS) optimise la distribution (coût réduit)
- ✅ Scalable horizontalement (workers Go)
**Coût estimé infrastructure** :
| Phase | Utilisateurs | Infra live | Coût/mois |
|-------|--------------|------------|-----------|
| **MVP** | 0-100K | 1 instance Go (ingestion 100 lives simultanés) | +50€ (serveur) + bande passante |
| **Growth** | 100K-1M | 3-5 instances Go (500 lives simultanés) | +200€ + bande passante |
| **Scale** | 1M-10M | Kubernetes auto-scale (2000+ lives) | +1K€ + bande passante |
**Bande passante** :
- Live : 48 kbps × nb_auditeurs (via NGINX Cache, segments)
- Exemple : 100 auditeurs = 4.8 Mbps = ~2 Go/heure via cache
- Coût estimé : ~0.02€/heure pour 100 auditeurs
---
## Récapitulatif Section 7