roadwave/docs/REFACTOR-DDD.md

Plan de refactorisation : Organisation DDD de la documentation

🎯 Objectif

Réorganiser 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.

📊 Situation actuelle

Structure actuelle

docs/
├── regles-metier/          # 19 fichiers numérotés 01-19 + ANNEXE
├── diagrammes/             # Organisés par type (flux, états, séquences, entités)
│   ├── flux/
│   ├── etats/
│   ├── sequence/
│   └── entites/
├── adr/                    # Architecture Decision Records
├── legal/                  # Documentation légale
└── interfaces/             # Interfaces UI

Problèmes identifiés

1. Organisation séquentielle : Numérotation 01-19 ne reflète pas les domaines métier
2. Diagrammes dispersés : Séparés des règles métier qu'ils illustrent
3. Navigation complexe : Difficile de trouver toute la doc d'un domaine
4. Pas d'alignement code : Structure docs ≠ structure backend/internal/
5. Onboarding difficile : Nouveau dev doit parcourir 19 fichiers linéairement
6. Maintenance : Règles métier, entités et diagrammes d'un même domaine sont éparpillés

🎨 Architecture cible (DDD)

Nouvelle structure

docs/
├── domains/                              # 🆕 Organisation par domaine
│   ├── README.md                        # Context Map + Index domaines
│   │
│   ├── _shared/                         # Core Domain
│   │   ├── README.md
│   │   ├── rules/
│   │   │   ├── authentification.md
│   │   │   ├── rgpd.md
│   │   │   └── gestion-erreurs.md
│   │   ├── entities/
│   │   │   └── modele-global.md
│   │   └── ubiquitous-language.md
│   │
│   ├── recommendation/                  # Bounded Context
│   │   ├── README.md
│   │   ├── rules/
│   │   │   ├── centres-interet-jauges.md
│   │   │   ├── algorithme-recommandation.md
│   │   │   └── interactions-navigation.md
│   │   ├── entities/
│   │   │   └── modele-recommandation.md
│   │   ├── sequences/
│   │   │   └── scoring-recommandation.md
│   │   └── features/
│   │       └── *.feature
│   │
│   ├── content/                        # Bounded Context
│   │   ├── README.md
│   │   ├── rules/
│   │   │   ├── creation-publication.md
│   │   │   ├── audio-guides.md
│   │   │   ├── radio-live.md
│   │   │   ├── contenus-geolocalises.md
│   │   │   └── detection-contenu-protege.md
│   │   ├── entities/
│   │   │   ├── modele-audio-guides.md
│   │   │   └── modele-radio-live.md
│   │   └── flows/
│   │
│   ├── advertising/                    # Bounded Context
│   │   ├── README.md
│   │   ├── rules/
│   │   │   └── publicites.md
│   │   ├── entities/
│   │   │   └── modele-publicites.md
│   │   ├── sequences/
│   │   ├── states/
│   │   └── flows/
│   │
│   ├── premium/                        # Bounded Context
│   │   ├── README.md
│   │   ├── rules/
│   │   │   ├── premium.md
│   │   │   ├── mode-offline.md
│   │   │   └── abonnements-notifications.md
│   │   ├── entities/
│   │   │   └── modele-premium.md
│   │   └── sequences/
│   │
│   ├── monetization/                   # Bounded Context
│   │   ├── README.md
│   │   ├── rules/
│   │   │   └── monetisation-createurs.md
│   │   ├── entities/
│   │   │   └── modele-monetisation.md
│   │   └── flows/
│   │
│   └── moderation/                     # Bounded Context
│       ├── README.md
│       ├── rules/
│       │   ├── moderation-flows.md
│       │   ├── moderation-communautaire.md
│       │   └── autres-comportements.md
│       ├── entities/
│       │   └── modele-moderation.md
│       ├── sequences/
│       │   └── processus-appel-moderation.md
│       ├── states/
│       │   └── signalement-lifecycle.md
│       ├── flows/
│       │   └── moderation-signalement.md
│       └── features/
│
├── adr/                                # Inchangé
├── legal/                              # Inchangé
├── interfaces/                         # Inchangé
└── technical.md                        # Inchangé

📋 Mapping des domaines

7 Bounded Contexts identifiés

Domaine	Règles métier	Entités	Diagrammes	Responsabilité
_shared	01, 02, 10	USERS, CONTENTS, SUBSCRIPTIONS, LISTENING_HISTORY	-	Authentification, RGPD, Gestion erreurs
recommendation	03, 04, 05	USER_INTERESTS, INTEREST_CATEGORIES	scoring-recommandation.md	Jauges, Algorithme, Navigation
content	06, 07, 11, 12, 13	AUDIO_GUIDES, LIVE_STREAMS, GUIDE_SEQUENCES, LIVE_RECORDINGS	-	Création, Audio-guides, Live, Détection droits
advertising	16	AD_CAMPAIGNS, AD_METRICS, AD_IMPRESSIONS	-	Campagnes, Ciblage, Métriques
premium	08, 09, 17	PREMIUM_SUBSCRIPTIONS, ACTIVE_STREAMS, OFFLINE_DOWNLOADS	-	Abonnements, Offline, Notifications
monetization	18	CREATOR_MONETIZATION, REVENUES, PAYOUTS	-	KYC, Revenus, Versements
moderation	14, 15, 19	REPORTS, SANCTIONS, APPEALS, STRIKES, BADGES	processus-appel-moderation.md, signalement-lifecycle.md, moderation-signalement.md	Signalements, Sanctions, Badges

🗺️ Plan de migration détaillé

Phase 1 : Créer la structure cible

# Créer l'arborescence
mkdir -p docs/domains/{_shared,recommendation,content,advertising,premium,monetization,moderation}/{rules,entities,sequences,states,flows,features}

Phase 2 : Déplacer les règles métier

Fichier actuel	Destination
01-authentification-inscription.md	domains/_shared/rules/authentification.md
02-conformite-rgpd.md	domains/_shared/rules/rgpd.md
03-centres-interet-jauges.md	domains/recommendation/rules/centres-interet-jauges.md
04-algorithme-recommandation.md	domains/recommendation/rules/algorithme-recommandation.md
05-interactions-navigation.md	domains/recommendation/rules/interactions-navigation.md
06-audio-guides-multi-sequences.md	domains/content/rules/audio-guides.md
07-contenus-geolocalises-voiture.md	domains/content/rules/contenus-geolocalises.md
08-mode-offline.md	domains/premium/rules/mode-offline.md
09-abonnements-notifications.md	domains/premium/rules/abonnements-notifications.md
10-gestion-erreurs.md	domains/_shared/rules/gestion-erreurs.md
11-creation-publication-contenu.md	domains/content/rules/creation-publication.md
12-radio-live.md	domains/content/rules/radio-live.md
13-detection-contenu-protege.md	domains/content/rules/detection-contenu-protege.md
14-moderation-flows.md	domains/moderation/rules/moderation-flows.md
15-moderation-communautaire.md	domains/moderation/rules/moderation-communautaire.md
16-publicites.md	domains/advertising/rules/publicites.md
17-premium.md	domains/premium/rules/premium.md
18-monetisation-createurs.md	domains/monetization/rules/monetisation-createurs.md
19-autres-comportements.md	domains/moderation/rules/autres-comportements.md
ANNEXE-POST-MVP.md	domains/_shared/rules/ANNEXE-POST-MVP.md

Phase 3 : Déplacer les diagrammes d'entités

Fichier actuel	Destination
diagrammes/entites/modele-global.md	domains/_shared/entities/modele-global.md
diagrammes/entites/modele-recommandation.md	domains/recommendation/entities/modele-recommandation.md
diagrammes/entites/modele-audio-guides.md	domains/content/entities/modele-audio-guides.md
diagrammes/entites/modele-radio-live.md	domains/content/entities/modele-radio-live.md
diagrammes/entites/modele-publicites.md	domains/advertising/entities/modele-publicites.md
diagrammes/entites/modele-premium.md	domains/premium/entities/modele-premium.md
diagrammes/entites/modele-monetisation.md	domains/monetization/entities/modele-monetisation.md
diagrammes/entites/modele-moderation.md	domains/moderation/entities/modele-moderation.md

Phase 4 : Déplacer les autres diagrammes

Fichier actuel	Destination
diagrammes/flux/moderation-signalement.md	domains/moderation/flows/moderation-signalement.md
diagrammes/etats/signalement-lifecycle.md	domains/moderation/states/signalement-lifecycle.md
diagrammes/sequence/processus-appel-moderation.md	domains/moderation/sequences/processus-appel-moderation.md

Phase 5 : Créer les README.md de domaine

Créer un README.md dans chaque domaine avec le template suivant :

# Domaine : [Nom]

## Vue d'ensemble
[Description du bounded context]

## Responsabilités
- Responsabilité 1
- Responsabilité 2

## Règles métier
- [Règle 1](rules/xxx.md)

## Modèle de données
- [Diagramme entités](entities/modele-xxx.md)

## Diagrammes
- [Flux](flows/xxx.md)
- [États](states/xxx.md)
- [Séquences](sequences/xxx.md)

## Tests BDD
- [Feature 1](features/xxx.feature)

## Dépendances
- ✅ Dépend de : `_shared`
- ⚠️ Interactions avec : `moderation`

## Ubiquitous Language
**Termes métier spécifiques au domaine**

Phase 6 : Déplacer les features Gherkin

# Les features actuellement dans /features/ root
mv features/api/recommendation/* domains/recommendation/features/
mv features/moderation/* domains/moderation/features/
# etc.

Phase 7 : Créer le Context Map

Créer docs/domains/README.md avec la cartographie des domaines :

# Context Map RoadWave

## Vue d'ensemble des domaines

[Diagramme Mermaid des relations entre bounded contexts]

## Bounded Contexts

### Core Domain
- **_shared** : Authentification, RGPD, Gestion erreurs

### Supporting Subdomains
- **recommendation** : Jauges, Algorithme, Scoring
- **content** : Création, Audio-guides, Live
- **moderation** : Signalements, Sanctions, Badges

### Generic Subdomains
- **advertising** : Campagnes publicitaires
- **premium** : Abonnements, Offline
- **monetization** : Revenus créateurs

Phase 8 : Mettre à jour mkdocs.yml

Réorganiser la navigation MkDocs pour refléter la nouvelle structure par domaine.

Phase 9 : Mettre à jour les liens internes

Corriger tous les liens relatifs dans les fichiers markdown pour pointer vers les nouvelles locations.

Phase 10 : Nettoyer l'ancienne structure

# Une fois tout migré et testé
rm -rf docs/regles-metier/
rm -rf docs/diagrammes/

✅ Avantages attendus

1. Cohésion forte : Toute la doc d'un domaine au même endroit
2. Couplage faible : Domaines indépendants, dépendances explicites
3. Navigabilité améliorée : README par domaine = entrée claire
4. Alignement code/docs : Miroir de backend/internal/
5. Onboarding facilité : Nouveau dev explore domaine par domaine
6. Maintenance simplifiée : Modifier un domaine sans toucher aux autres
7. Scalabilité : Facile d'ajouter un nouveau domaine
8. Tests BDD intégrés : Features au plus près des règles métier

⚠️ Risques et précautions

Risques identifiés

1. Liens cassés : Nombreux liens internes à corriger
2. Confusion temporaire : Équipe doit s'adapter à la nouvelle structure
3. MkDocs rebuild : Navigation complète à refaire
4. Features Gherkin : Potentiellement beaucoup de fichiers à déplacer

Précautions

1. ✅ Créer ce plan d'abord : Validation avant exécution
2. ✅ Branch dédiée : refactor/ddd-documentation
3. ✅ Commits atomiques : Un commit par phase
4. ✅ Tests continus : Vérifier MkDocs build après chaque phase
5. ✅ Backup : Garder ancienne structure jusqu'à validation complète
6. ✅ Script automatisé : Créer script pour les déplacements et corrections de liens

📝 Checklist d'exécution

• Valider ce plan avec l'équipe
• Créer branch refactor/ddd-documentation
• Phase 1 : Créer arborescence
• Phase 2 : Déplacer règles métier
• Phase 3 : Déplacer diagrammes entités
• Phase 4 : Déplacer autres diagrammes
• Phase 5 : Créer README.md domaines
• Phase 6 : Déplacer features Gherkin
• Phase 7 : Créer Context Map
• Phase 8 : Mettre à jour mkdocs.yml
• Phase 9 : Corriger liens internes
• Phase 10 : Nettoyer ancienne structure
• Tester build MkDocs
• Valider avec équipe
• Merger dans main

🚀 Script d'automatisation suggéré

#!/bin/bash
# scripts/refactor-ddd.sh

# Phase 1 : Créer structure
echo "Phase 1: Création structure..."
mkdir -p docs/domains/{_shared,recommendation,content,advertising,premium,monetization,moderation}/{rules,entities,sequences,states,flows,features}

# Phase 2 : Déplacer règles métier
echo "Phase 2: Migration règles métier..."
git mv docs/regles-metier/01-authentification-inscription.md docs/domains/_shared/rules/authentification.md
# ... etc pour tous les fichiers

# Phase 3-4 : Déplacer diagrammes
echo "Phase 3-4: Migration diagrammes..."
git mv docs/diagrammes/entites/modele-global.md docs/domains/_shared/entities/modele-global.md
# ... etc

# Phase 9 : Corriger liens (sed ou script Python)
echo "Phase 9: Correction liens..."
find docs/domains -name "*.md" -exec sed -i 's|../../regles-metier/|../rules/|g' {} \;
# ... etc

echo "Migration terminée!"

📚 Références DDD

• Domain-Driven Design - Eric Evans
• Bounded Context - Martin Fowler
• Context Mapping

---

Date de création : 2026-02-07 Statut : 🟡 En attente de validation Auteur : Documentation refactoring initiative