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

```bash
# 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 :

```markdown
# 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

```bash
# 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 :

```markdown
# 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

```bash
# 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é

```bash
#!/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](https://www.domainlanguage.com/ddd/)
- [Bounded Context - Martin Fowler](https://martinfowler.com/bliki/BoundedContext.html)
- [Context Mapping](https://github.com/ddd-crew/context-mapping)

---

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