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.
2026-02-07 17:15:02 +01:00
parent 78422bb2c0
commit 5e5fcf4714
227 changed files with 1413 additions and 1967 deletions
--- a/docs/domains/monetization/rules/monetisation-createurs.md
+++ b/docs/domains/monetization/rules/monetisation-createurs.md
@@ -0,0 +1,418 @@
+## 9. Monétisation créateurs
+
+### 9.1 Pourboires
+
+**Décision** : ❌ Fonctionnalité abandonnée pour le MVP
+
+**Raisons** :
+- Complexité juridique (collecte pour compte de tiers, TVA variable)
+- Frais de transaction élevés sur petits montants (Mangopay ~1.8% + 0.18€)
+- UX additionnelle à développer (wallet, transactions, confirmations)
+- Charge comptable importante pour la plateforme
+
+**Post-MVP** : Possible réintégration avec crypto (Bitcoin/Lightning Network) si législation UE l'autorise clairement (régulation MiCA en cours).
+
+---
+
+### 9.2 Conditions d'activation de la monétisation
+
+**Décision** : 5 critères cumulatifs obligatoires
+
+| Critère | Seuil | Justification |
+|---------|-------|---------------|
+| **Ancienneté** | Compte créé depuis ≥ 3 mois | Anti-fraude : temps de détecter comportements suspects |
+| **Popularité** | ≥ 500 abonnés | Garantit audience réelle et engagée |
+| **Engagement** | ≥ 10 000 écoutes complètes cumulées | Créateurs produisant du contenu de qualité |
+| **Fiabilité** | Aucun strike actif, 0 contenu modéré dans les 6 derniers mois | Historique propre requis |
+| **Régularité** | ≥ 5 contenus publiés dans les 90 derniers jours | Activité constante |
+
+**Vérification** : Automatique via requêtes SQL lors de la demande d'activation
+
+**Affichage** :
+- Bouton "Demander la monétisation" dans profil créateur
+- Si critères non remplis → affichage progression vers objectifs
+- Si critères remplis → redirection vers KYC Mangopay
+
+**Justification** :
+- **Anti-fraude** : Le délai de 3 mois permet de détecter les comptes suspects
+- **Qualité** : Seuls les créateurs sérieux avec audience réelle sont monétisés
+- **Coût administratif** : Réduit le nombre de comptes à gérer (KYC, comptabilité, virements)
+- **Légitimité** : Audience organique prouvée
+
+---
+
+### 9.3 KYC (Know Your Customer) et inscription
+
+**Décision** : Statut juridique professionnel obligatoire
+
+**Statuts acceptés** :
+- Auto-entrepreneur (micro-BNC pour artistes/créateurs de contenu)
+- SARL/SAS/SASU (sociétés)
+
+**Documents requis** :
+
+| Document | Obligatoire | Format | Validité |
+|----------|-------------|--------|----------|
+| **SIRET** | ✅ | 14 chiffres | Permanent |
+| **RIB professionnel** | ✅ | IBAN FR | Permanent |
+| **Pièce d'identité** | ✅ | CNI/Passeport | En cours de validité |
+| **Numéro TVA intracommunautaire** | ⚠️ Si applicable | FR + 11 chiffres | Permanent |
+| **Kbis <3 mois** | ⚠️ Si société | PDF | <3 mois |
+
+**Vérification** : Via Mangopay (KYC intégré + vérification bancaire)
+
+**Délai** : 24-72h si documents conformes
+
+**Rejet possible si** :
+- Documents invalides/illisibles
+- Identité ne correspond pas au compte RoadWave
+- Liste noire anti-blanchiment (vérification automatique Mangopay)
+- RIB non professionnel (particulier)
+
+**Base légale** :
+- **Conformité fiscale** : L'État français impose déclaration revenus >1200€/an (DAS2)
+- **Anti-blanchiment** : Directive EU 2018/843 (5ème directive LCB-FT)
+- **RGPD** : Données hébergées EU via Mangopay (conforme)
+
+**Justification** :
+- **Responsabilité légale** : RoadWave doit pouvoir prouver identité réelle créateurs monétisés
+- **Automatisation** : Mangopay gère tout (KYC, vérifications, conformité, e-wallets)
+- **KYC gratuit** : inclus dans l'offre Mangopay (vs 1.20€ chez Stripe)
+- **Souveraineté EU** : Mangopay est européen (France/Luxembourg), régulé ACPR
+
+---
+
+### 9.4 Sources de revenus créateurs
+
+#### A) Publicités (utilisateurs gratuits)
+
+**Formule** : **3€ / 1000 écoutes complètes** (CPM créateur)
+
+**Répartition économique** :
+
+```
+Publicité facturée par RoadWave : 0.05€/écoute complète = 50€ CPM
+├─ Créateur touche : 3€ (6% du CA pub)
+└─ Plateforme garde : 47€ (94%)
+    ├─ CDN + infrastructure : ~10-15€
+    ├─ Modération + support : ~5-10€
+    ├─ Développement + R&D : ~10-15€
+    └─ Marge opérationnelle : ~10-15€
+```
+
+**Exemple concret** :
+- 10 000 écoutes/mois → créateur touche **30€**
+- 50 000 écoutes/mois → créateur touche **150€**
+- 100 000 écoutes/mois → créateur touche **300€**
+
+**Comparaison industrie** :
+- YouTube : 3-5€/1000 vues
+- Spotify : 3-4€/1000 écoutes
+- RoadWave : 3€/1000 écoutes (aligné)
+
+**Règles comptabilisation** :
+- ✅ Écoute complète = ≥80% du contenu écouté
+- ✅ Utilisateur gratuit uniquement
+- ❌ Écoutes Premium ne comptent pas ici (autre système)
+- ❌ Bots détectés exclus (rate limiting + analyse patterns)
+
+---
+
+#### B) Abonnés Premium
+
+**Formule** : **70% au créateur, 30% à la plateforme**
+
+**Répartition proportionnelle au temps d'écoute effectif** :
+
+```
+Utilisateur Premium = 4.99€/mois
+├─ 3.49€ reversés aux créateurs (70%)
+└─ 1.50€ gardés par plateforme (30%)
+
+Si l'utilisateur écoute 3 créateurs ce mois :
+- Créateur A : 10h d'écoute (50%) → 1.75€
+- Créateur B : 6h d'écoute (30%) → 1.05€
+- Créateur C : 4h d'écoute (20%) → 0.70€
+```
+
+**Calcul technique** :
+
+```sql
+-- Pour chaque utilisateur Premium
+SELECT
+    creator_id,
+    SUM(listen_duration_seconds) AS total_seconds,
+    (SUM(listen_duration_seconds) / total_user_seconds) AS ratio,
+    (4.99 * 0.70 * ratio) AS revenue_euros
+FROM premium_listens
+WHERE user_id = :user_id
+  AND month = :current_month
+GROUP BY creator_id;
+```
+
+**Comparaison industrie** :
+- YouTube Premium : 70/30
+- Spotify : 70/30
+- Apple Music : 52/48 (moins avantageux)
+- RoadWave : 70/30 (standard)
+
+**Justification** :
+- **Standard industrie** : ratio équitable éprouvé
+- **Incitation qualité** : créateurs les plus écoutés gagnent plus
+- **Équité** : pas de "winner takes all", chaque créateur écouté reçoit sa part
+- **Marge plateforme** : 30% couvre absence revenus pub sur Premium
+
+---
+
+### 9.5 Paiement des créateurs
+
+#### 9.5.1 Seuil de paiement et conservation du solde
+
+**Seuil standard** : 50€
+
+- En dessous → solde reporté mois suivant
+- Évite frais bancaires sur micro-sommes (Mangopay SEPA : 1.8% + 0.18€)
+- Standard industrie (YouTube/Twitch/Spotify = 50-100€)
+
+**Conservation du solde** :
+
+- Solde conservé **indéfiniment** SI créateur actif
+  - Critère activité : >0 écoute/mois OU connexion dashboard/mois
+- Solde visible en temps réel dans dashboard créateur
+
+**Créateur inactif** (0 écoute/mois + 0 connexion dashboard) :
+
+| Durée inactivité | Action RoadWave | Email créateur |
+|------------------|-----------------|----------------|
+| **0-12 mois** | Conservation solde | Aucun |
+| **12 mois** | Conservation solde | "⚠️ Vous avez X€ en attente. Versement automatique dans 6 mois si inactivité continue." |
+| **18 mois** | Préavis versement | "📢 Versement automatique dans 30 jours (frais bancaires déduits : ~0.36€)" |
+| **18 mois + 30j** | **Versement forcé** | Confirmation versement + montant net |
+| **18 mois + 37j** | Purge données comptables | (Conservation logs 10 ans RGPD) |
+
+**Exception soldes <10€** :
+- Si solde <10€ après 18 mois → Frais bancaires (0.36€) > 3.6% du montant
+- Proposition email : "Don association ou conservation jusqu'à 50€"
+- Si don refusé + inactivité continue → versement forcé quand même (équité)
+
+**Frais bancaires assumés par créateur** :
+- Mangopay SEPA : 1.8% + 0.18€
+- Exemple : 45€ → versement **44.64€** net
+- Transparence totale dans email préavis
+
+**Modèle email (12 mois d'inactivité)** :
+
+```
+Objet : ⚠️ Votre solde RoadWave (X€) - Action requise
+
+Bonjour [Créateur],
+
+Vous n'avez pas publié de contenu depuis 12 mois.
+Votre solde actuel : XX.XX€
+
+🔔 Si vous restez inactif 6 mois supplémentaires :
+→ Versement automatique (frais bancaires déduits)
+→ Montant net estimé : XX.XX€
+
+💡 Pour éviter le versement anticipé :
+- Publiez un nouveau contenu, OU
+- Connectez-vous à votre dashboard créateur
+
+Consultez votre solde : [Lien dashboard]
+
+L'équipe RoadWave
+```
+
+**Comparaison Twitch** :
+
+| Critère | Twitch | RoadWave | Avantage |
+|---------|--------|----------|----------|
+| **Seuil paiement** | 50-100$ | 50€ | Aligné |
+| **Délai inactivité** | 24 mois | 18 mois | RoadWave plus court |
+| **Action fin délai** | **Forfeiture** (perte argent) | **Versement forcé** (récupère argent) | ✅ RoadWave plus équitable |
+| **Emails préventifs** | ❓ Non documenté | 12 mois + 18 mois + 30j avant | ✅ RoadWave transparent |
+| **Frais bancaires** | ❓ Non documenté | Déduits + annoncés | ✅ RoadWave transparent |
+
+**Justification** :
+- **Plus équitable que Twitch** : versement forcé au lieu de forfeiture (créateur récupère son argent)
+- **Emails préventifs** : 3 relances (12 mois, 18 mois, 18 mois + 30j) avant action
+- **Transparence** : frais bancaires annoncés clairement dans emails
+- **Assume bonne foi** : 18 mois d'inactivité = probablement abandon compte, mais argent restitué
+
+---
+
+#### 9.5.2 Fréquence et calendrier de paiement
+
+**Fréquence** : Mensuelle
+
+| Date | Action |
+|------|--------|
+| **Dernier jour du mois** (ex: 31 janvier) | Calcul revenus du mois via SQL |
+| **1-14 du mois suivant** | Traitement contestations/fraudes éventuelles |
+| **15 du mois suivant** (ex: 15 février) | Virement SEPA via Mangopay (Payout) |
+| **16-18 du mois suivant** | Réception virement (1-3 jours ouvrés SEPA) |
+
+**Virement via Mangopay** :
+- SEPA pour comptes EU (gratuit, 1-3 jours)
+- Virement international hors EU (frais variables selon pays, rare en pratique)
+- **E-wallets automatiques** : chaque créateur possède un wallet Mangopay où ses revenus sont transférés automatiquement
+
+**Tableau de bord créateur** (temps réel) :
+
+| Métrique | Description | Mise à jour |
+|----------|-------------|-------------|
+| **Revenus pub** | Écoutes × CPM | Temps réel |
+| **Revenus premium** | Abonnés actifs × ratio écoute | Temps réel |
+| **Solde disponible** | Total revenus mois en cours | Temps réel |
+| **Solde en attente** | Revenus mois précédent (paiement le 15) | Figé fin de mois |
+| **Historique virements** | Liste des paiements reçus | Permanent |
+| **Export comptable CSV** | Données pour expert-comptable | Téléchargement |
+
+**Gestion échecs virement** :
+1. Tentative 1 (15 du mois) → échec
+2. Retry automatique J+3
+3. Retry automatique J+7
+4. Si 3 échecs → suspension monétisation + email créateur (RIB invalide)
+
+---
+
+### 9.6 Contenus Premium exclusifs
+
+**Décision** : Créateur décide individuellement pour chaque contenu
+
+**Fonctionnement** :
+- Toggle "Réservé Premium" lors création/édition contenu
+- **Aucune limite imposée** : créateur peut mettre 0%, 50% ou 100% en premium
+- Badge 👑 visible sur interface utilisateur
+
+**Comportement utilisateurs gratuits** :
+- Contenu premium visible dans liste/algo
+- Tentative lecture → overlay bloquant
+- Message : "Ce contenu est réservé aux abonnés Premium"
+- CTA : "Passez Premium pour 4.99€/mois"
+
+**Comportement algorithme** :
+- Contenus premium inclus dans recommandations
+- Si user gratuit → contenu skippé automatiquement (ne consomme pas de slot)
+- Si user premium → diffusé normalement
+
+**Métadonnées** :
+- Champ `is_premium` (boolean) en base
+- Index sur ce champ pour requêtes rapides
+- Cache Redis : `content:{id}:premium` (TTL 1h)
+
+**Justification** :
+- **Liberté créateur** : chaque créateur choisit sa stratégie (freemium, tout gratuit, tout premium)
+- **Incitation Premium** : contenu exclusif = argument fort pour s'abonner
+- **Équité** : un petit créateur peut tout mettre en premium, un gros peut tout offrir gratuitement
+
+---
+
+### 9.7 Obligations fiscales
+
+**RoadWave génère automatiquement** :
+
+| Document | Fréquence | Destinataire | Base légale |
+|----------|-----------|--------------|-------------|
+| **Relevé mensuel PDF** | Chaque mois | Créateur | Transparence |
+| **Export CSV comptable** | À la demande | Créateur + expert-comptable | Facilitation déclarations |
+| **DAS2 annuel** | **Tous montants (même <1200€)** | Impôts (DGFIP) | Obligation légale France + conformité maximale |
+
+**Décision DAS2 systématique** :
+
+- RoadWave envoie **DAS2 à la DGFIP** pour tous créateurs monétisés
+- Déclaration annuelle en janvier N+1 (revenus année N)
+- **Aucun seuil minimum** (même 50€ déclaré)
+- Créateur reçoit copie par email + disponible dashboard
+
+**Justification juridique** :
+
+> Bien que le seuil légal DAS2 soit 1200€/an, rien n'interdit de déclarer les montants inférieurs. Au contraire, cela renforce la transparence et protège RoadWave en cas de contrôle fiscal.
+
+**Avantages** :
+- ✅ **Conformité maximale** : aucune zone grise
+- ✅ **Protection juridique RoadWave** : traçabilité totale
+- ✅ **Simplicité technique** : même processus pour tous
+- ✅ **Créateur a justificatif** : même petits montants
+- ✅ **Coût 0€** : DAS2 = déclaration obligatoire gratuite
+
+**Modèle email créateur (janvier N+1)** :
+
+```
+Objet : Votre déclaration fiscale 2026 RoadWave
+
+Bonjour [Créateur],
+
+Vos revenus RoadWave 2026 ont été déclarés aux impôts (DAS2) :
+- Revenus publicité : XXX.XX€
+- Revenus Premium : XXX.XX€
+- Total déclaré : XXX.XX€
+
+Cette déclaration a été transmise à la DGFIP.
+Vous devez inclure ce montant dans votre déclaration personnelle.
+
+Télécharger le justificatif : [Lien PDF]
+
+Cordialement,
+L'équipe RoadWave
+```
+
+**Créateur responsable de** :
+- Déclarer ses revenus à l'URSSAF (cotisations sociales auto-entrepreneur ou IS/IR)
+- Déclarer ses revenus aux impôts (IR ou IS selon statut)
+- Gérer sa TVA si applicable (franchise en base jusqu'à ~37K€/an en micro-BNC)
+- Conserver justificatifs **10 ans** (obligation légale comptable)
+
+**Mangopay transmet automatiquement** :
+- Données aux autorités fiscales EU via **DAC7** (directive 2021/514)
+- Justificatif de chaque virement (preuve bancaire pour comptabilité créateur)
+
+**Exemple DAS2** :
+```
+Si créateur a touché 2500€ en 2026 :
+→ RoadWave envoie DAS2 aux impôts en janvier 2027
+→ Créateur reçoit copie par email
+→ Créateur doit déclarer ces 2500€ dans sa déclaration annuelle
+```
+
+**Justification** :
+- **Conformité légale** : RoadWave doit déclarer revenus versés (DAS2, DAC7)
+- **Responsabilité fiscale** : Le créateur reste responsable de sa déclaration (impossible de gérer pour lui)
+- **Automatisation** : Minimise charge administrative côtés créateur et plateforme
+
+---
+
+### 9.8 Désactivation et suspension monétisation
+
+**Créateur peut** :
+- Désactiver temporairement (vacances, pause création)
+- Réactiver sans refaire KYC si données à jour (<2 ans)
+- Solde conservé pendant désactivation
+
+**Plateforme suspend automatiquement si** :
+
+| Motif | Action | Réversible |
+|-------|--------|------------|
+| **Strike 3+ actif** | Suspension immédiate | Oui, après résolution strikes |
+| **Compte bancaire invalide** | Suspension après 3 échecs virement | Oui, après mise à jour RIB |
+| **Documents KYC expirés** | Suspension avec préavis 30j | Oui, après renouvellement docs |
+| **Fraude détectée** | Suspension immédiate + enquête | Cas par cas |
+
+**Suppression définitive si** :
+- Demande du créateur (solde versé sous 30 jours)
+- Inactivité 24 mois + solde <50€ (purge RGPD)
+- Ban définitif compte (Strike 4)
+
+**Notification** :
+- Email + in-app pour toute suspension
+- Raison explicite fournie
+- Procédure de réactivation indiquée
+
+**Justification** :
+- **Flexibilité** : créateur peut faire pause sans perdre statut
+- **Sécurité** : plateforme doit pouvoir suspendre en cas problème légal/technique
+- **RGPD** : suppression auto données inactives après délai raisonnable
+
+---
+
+## Récapitulatif Section 9