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,160 @@
## 3. Centres d'intérêt et jauges
### 3.1 Évolution des jauges
**Décision** : Système simple avec valeurs fixes (points de pourcentage absolus)
| Action | Impact jauge | Justification |
|--------|--------------|---------------|
| **Like automatique renforcé (≥80% écoute)** | **+2%** | Signal fort d'intérêt (écoute quasi-complète) |
| **Like automatique standard (30-79% écoute)** | **+1%** | Signal modéré d'intérêt |
| **Like explicite (manuel)** | **+2%** | Signal fort, cumulable avec auto |
| **Abonnement créateur** | **+5%** sur tous ses tags | Signal très fort d'affinité |
| **Skip rapide (<10s), NON abonné** | **-0.5%** | Désintérêt marqué (signal négatif légitime) |
| **Skip rapide (<10s), ABONNÉ au créateur** | **0%** (neutre) | Abonnement = affinité forte, skip contextuel (pas ce contenu spécifique) |
| **Skip tardif (≥30%)** | **0%** | Neutre (contenu essayé suffisamment) |
**Note importante** : Les pourcentages indiqués sont des **points de pourcentage absolus**, **PAS des pourcentages relatifs**.
**Calcul** :
- Si jauge "Automobile" = 45%
- Like renforcé (+2%) → 45 + 2 = **47%**
- **NOT** 45 × 1.02 = 45.9% ❌
Cette approche garantit une **progression linéaire** et **équitable** pour tous les utilisateurs, indépendamment de leur niveau actuel dans une jauge.
**Paramètres techniques** :
- Les jauges sont bornées strictement entre **0% et 100%**
- Calcul immédiat à chaque action (pas de batch différé)
- Les tags du contenu sont définis par le créateur à la publication
- Si un contenu a plusieurs tags, chaque jauge correspondante est impactée
**Exemple de calcul** :
```
Contenu de 5 minutes tagué "Automobile" + "Voyage"
Scénario 1 : Écoute 4min30 (90%)
→ Like automatique renforcé (+2%)
→ Jauge Automobile : 45% → 47%
→ Jauge Voyage : 60% → 62%
Scénario 2 : Écoute 2min30 (50%)
→ Like automatique standard (+1%)
→ Jauge Automobile : 45% → 46%
→ Jauge Voyage : 60% → 61%
Scénario 3 : Écoute 2min30 (50%) + Like manuel
→ Like auto +1% puis like manuel +2% = +3% total
→ Jauge Automobile : 45% → 48%
→ Jauge Voyage : 60% → 63%
Scénario 4 : Skip après 5s (NON abonné au créateur)
→ Signal négatif (-0.5%)
→ Jauge Automobile : 45% → 44.5%
→ Jauge Voyage : 60% → 59.5%
Scénario 5 : Skip après 5s (ABONNÉ au créateur)
→ Neutre (0%, pas de pénalité)
→ Jauge Automobile : 45% → 45%
→ Jauge Voyage : 60% → 60%
→ Raison : Abonnement signale affinité globale, skip ponctuel = pas intéressé par CE contenu spécifique
```
**Justification** :
- **Like automatique** : Reflète l'engagement réel (voir [Règle 05 - Section 5.3](05-interactions-navigation.md#53-interactions-au-volant--like-automatique-et-engagement))
- **Sécurité routière** : Pas d'action complexe en conduite
- **Prévisibilité** : Règles claires et déterministes
- **Progression linéaire** : Évite l'effet "rich get richer" (progression équitable)
- **Coût minimal** : Calculs simples en backend (addition/soustraction uniquement)
- **Fiabilité** : Pas d'edge cases complexes (pas de risque d'overflow avec multiplication)
- **Ajustable** : Valeurs modifiables via dashboard admin si besoin
> 📋 **Référence technique** : Voir [Règle 05 - Implémentation Technique](05-interactions-navigation.md#implémentation-technique-backend) pour l'architecture backend détaillée.
---
### 3.2 Jauge initiale
**Décision** : Démarrage neutre à 50%, pas de questionnaire
**À l'inscription** :
- Toutes les jauges d'intérêt sont initialisées à **50%**
- Pas de questionnaire onboarding (friction zéro)
- L'algorithme apprend naturellement via les premières écoutes
**Catégories disponibles** :
- Automobile
- Voyage
- Famille
- Amour
- Musique
- Économie
- Cryptomonnaie
- Politique
- Culture générale
- Sport
- Technologie
- Santé
- *... (extensible)*
**Cold start (premiers jours)** :
1. Nouvel utilisateur s'inscrit → toutes jauges à 50%
2. Écoute premier podcast "Automobile" → jauge Auto monte à 51%
3. Skip un contenu "Économie" → jauge Éco descend à 48%
4. Après 10-15 écoutes, profil commence à se dessiner clairement
**Alternative optionnelle (post-MVP)** :
- Questionnaire **optionnel** proposé après 3 écoutes (in-app)
- Message : "Améliorez vos recommandations en sélectionnant vos centres d'intérêt"
- Si rempli : jauges sélectionnées passent à 70%, non sélectionnées à 30%
- Si skip : conserve 50% partout
**Justification** :
- **Inscription ultra-rapide** : pas de questionnaire = moins de churn
- **Découverte naturelle** : l'algorithme apprend en quelques écoutes
- **Équitable** : pas de biais initial vers certains créateurs
- **Comportement déterministe** : facile à tester et débugger
- **Cold start acceptable** : à 50%, tous les contenus ont une chance égale initialement
---
### 3.3 Dégradation temporelle
**Décision** : Pas de dégradation automatique
Les jauges **ne diminuent jamais** avec le temps de manière automatique.
**Règle** :
- Une jauge ne change **que par les actions utilisateur** (like, écoute, skip)
- Pas de cron job de dégradation périodique
- Pas de "rafraîchissement" artificiel
**Scénario illustratif** :
```
Utilisateur aimait "Économie" (jauge 80%) il y a 1 an
→ Depuis, skip tous les contenus Éco
→ Jauge descend naturellement à 40% via les skips
→ Pas besoin de dégradation temporelle
```
**Si utilisateur inactif longtemps** :
- Utilisateur part en vacances 6 mois → jauges conservées
- Au retour : ses jauges reflètent toujours ses goûts d'avant
- Comportement cohérent et prévisible
**Alternative utilisateur (contrôle explicite)** :
- Bouton "Réinitialiser mes centres d'intérêt" dans paramètres
- Action manuelle : remet toutes les jauges à 50%
- Permet nouveau départ si souhaité (changement de vie, etc.)
**Justification** :
- **Principe KISS** (Keep It Simple, Stupid)
- **Coût 0** : pas de batch nocturne, pas de calculs temporels
- **Fiabilité maximale** : pas de bugs de fuseaux horaires, dates, etc.
- **UX prévisible** : jauge = reflet des actions, pas d'automatisme caché
- **Respect historique** : si utilisateur aimait X depuis 2 ans, pourquoi "oublier" ?
- **Évolution naturelle** : les actions récentes suffisent à faire évoluer les jauges
---
## Récapitulatif Section 3