roadwave/docs/MIGRATION.md

Migration Documentation - Réorganisation 2026-02-08

Cette documentation liste tous les changements effectués lors de la réorganisation complète de la documentation RoadWave.

Objectifs de la Migration

1. Éliminer les redondances : Supprimer les doublons de fichiers et la navigation duale
2. Normaliser la langue : 100% français pour la cohérence
3. Intégrer BDD dans DDD : Source unique de vérité avec navigation domaine-first
4. Rendre accessible toutes les features : 164 features BDD dans la navigation (vs 34 avant)

Changements Effectués

1. Fusions de Fichiers Doublons

Fichiers supprimés (versions anglaises) :

Fichier Supprimé	Fichier Conservé	Raison
sequences/data-export.md	sequences/export-donnees.md	Version française plus détaillée
sequences/account-deletion.md	sequences/suppression-compte.md	Version française plus détaillée

2. Renommages EN → FR

Entités :

Ancien Nom	Nouveau Nom
entities-overview.md	vue-ensemble.md

États (Lifecycles) :

Ancien Nom	Nouveau Nom
user-account-lifecycle.md	compte-utilisateur.md
content-lifecycle.md	contenu.md
session-lifecycle.md	session.md
report-lifecycle.md	signalement.md
export-lifecycle.md	export-donnees.md
parental-consent-lifecycle.md	consentement-parental.md
account-deletion-lifecycle.md	suppression-compte.md
breach-incident-lifecycle.md	incident-breach.md

Séquences :

Ancien Nom	Nouveau Nom
authentication-flow.md	authentification.md
token-refresh.md	refresh-token.md
content-moderation.md	moderation-contenu.md
content-report.md	signalement.md

3. Réorganisation Navigation

Changement majeur : Suppression de la section "Tests BDD" autonome

Avant :

- Domaines DDD:
    - Shared: (avec Features BDD)
    - Recommendation: (SANS Features BDD)
    - Content: (SANS Features BDD)
    - ...
- Tests BDD:
    - Vue d'ensemble: generated/bdd/index.md

Après :

- Domaines DDD:
    - Shared:
        - Tests BDD: (34 features)
    - Recommendation:
        - Tests BDD: (17 features) ← NOUVEAU
    - Content:
        - Tests BDD: (59 features) ← NOUVEAU
    - Moderation:
        - Tests BDD: (23 features) ← NOUVEAU
    - Advertising:
        - Tests BDD: (7 features) ← NOUVEAU
    - Premium:
        - Tests BDD: (16 features) ← NOUVEAU
    - Monetization:
        - Tests BDD: (8 features) ← NOUVEAU

Résultat : 164/164 features BDD accessibles (100% vs 21% avant)

4. Structure de Navigation par Domaine

Chaque domaine suit désormais cette structure cohérente :

Domaine X:
  - Vue d'ensemble
  - Règles métier
  - Entités
  - [États] (si applicable)
  - [Séquences] (si applicable)
  - [Diagrammes] (si applicable)
  - Tests BDD ← AJOUTÉ pour tous les domaines

Métriques de la Migration

Métrique	Avant	Après	Amélioration
Fichiers doublons	4	0	-100%
Features BDD accessibles	34/164 (21%)	164/164 (100%)	+379%
Domaines avec section BDD	1/7 (14%)	7/7 (100%)	+600%
Chemins vers BDD	2	1	Source unique
Langues mélangées	2 (FR + EN)	1 (FR)	Cohérence

Impact sur les Liens

Tous les liens internes ont été automatiquement mis à jour. Si vous avez des liens externes ou des bookmarks :

Entités

# Ancien lien (cassé)
docs/domains/_shared/entities/entities-overview.md

# Nouveau lien
docs/domains/_shared/entities/vue-ensemble.md

États

# Ancien lien (cassé)
docs/domains/_shared/states/user-account-lifecycle.md

# Nouveau lien
docs/domains/_shared/states/compte-utilisateur.md

Séquences

# Ancien lien (cassé)
docs/domains/_shared/sequences/data-export.md

# Nouveau lien
docs/domains/_shared/sequences/export-donnees.md

Navigation vers les Features BDD

Avant (34 features accessibles)

Pour accéder aux features BDD de Shared :

1. Domaines DDD → Shared → Features BDD
2. OU Tests BDD → Vue d'ensemble

Pour les autres domaines : Impossible (130 features inaccessibles)

Après (164 features accessibles)

Pour accéder aux features BDD de n'importe quel domaine :

1. Domaines DDD → [Domaine] → Tests BDD

Un seul chemin, cohérent pour tous les domaines.

Commits de la Migration

1. docs: fusionner séquences dupliquées (garder versions FR)
2. docs: renommer fichiers EN→FR pour cohérence linguistique
3. docs: mettre à jour liens après renommages
4. docs: intégrer toutes les features BDD dans navigation DDD
5. docs: supprimer index.md manuels du dossier generated/bdd

Rollback (si nécessaire)

Pour revenir à l'état avant migration :

git checkout docs-before-refactor
# OU
git revert a29718a..4b28db3

Tag de sauvegarde : docs-before-refactor

Questions Fréquentes

Où sont passées les pages "Vue d'ensemble" des domaines BDD ?

Elles ont été supprimées car elles étaient dans le dossier generated/ qui doit contenir uniquement les fichiers générés automatiquement par scripts/generate-bdd-docs.py. Les features sont directement accessibles dans la navigation.

Pourquoi supprimer la section "Tests BDD" autonome ?

Pour établir une source unique de vérité : les tests BDD sont une vue testable des règles DDD, ils doivent donc être intégrés dans chaque domaine DDD, pas séparés.

Comment trouver une feature BDD maintenant ?

1. Identifier le domaine concerné (content, recommendation, etc.)
2. Domaines DDD → [Domaine] → Tests BDD
3. Naviguer dans les catégories

Les fichiers .feature sont-ils dans la navigation ?

Non. Seuls les fichiers générés (.md dans generated/bdd/) sont dans la navigation MkDocs. Les .feature sources sont dans domains/[domain]/features/.

Prochaines Étapes

Pour maintenir cette organisation :

1. Toujours utiliser les noms français pour les nouveaux fichiers
2. Ne jamais créer de fichiers manuels dans generated/
3. Ajouter les nouvelles features dans domains/[domain]/features/
4. Regénérer avec make bdd-docs après ajout de features
5. Consulter CONTRIBUTING.md pour les règles de contribution

Auteurs

• Claude Sonnet 4.5 (réorganisation)
• Équipe RoadWave (validation)

Date : 2026-02-08