docs: documenter migration et règles de contribution
Ajout de 2 fichiers de documentation : MIGRATION.md : - Liste complète des changements effectués - Tableau de correspondance ancien → nouveau - Métriques de la migration (21% → 100% features accessibles) - Guide de rollback si nécessaire - FAQ CONTRIBUTING.md : - Principes fondamentaux (source unique, français, generated/ read-only) - Guide ajout feature BDD (étape par étape) - Guide ajout règle métier - Guide ajout entité et diagrammes - Conventions de nommage - Checklist avant commit - Format des messages de commit
This commit is contained in:
jpgiannetti
457
docs/CONTRIBUTING.md
Normal file
457
docs/CONTRIBUTING.md
Normal file
@@ -0,0 +1,457 @@
|
|||||||
|
# Guide de Contribution à la Documentation
|
||||||
|
|
||||||
|
Bienvenue ! Ce guide explique comment contribuer à la documentation RoadWave tout en respectant son architecture et ses conventions.
|
||||||
|
|
||||||
|
## Principes Fondamentaux
|
||||||
|
|
||||||
|
### 1. Source Unique de Vérité (Single Source of Truth)
|
||||||
|
|
||||||
|
Chaque information doit exister à **un seul endroit** :
|
||||||
|
|
||||||
|
- **Règles métier** → `docs/domains/[domain]/rules/*.md`
|
||||||
|
- **Features BDD** → `domains/[domain]/features/**/*.feature` (sources Gherkin)
|
||||||
|
- **Documentation BDD** → `docs/generated/bdd/` (générée automatiquement)
|
||||||
|
- **Entités** → `docs/domains/[domain]/entities/*.md`
|
||||||
|
- **États** → `docs/domains/[domain]/states/*.md`
|
||||||
|
- **Séquences** → `docs/domains/[domain]/sequences/*.md`
|
||||||
|
|
||||||
|
❌ **Ne jamais** dupliquer une information
|
||||||
|
✅ **Toujours** référencer via des liens
|
||||||
|
|
||||||
|
### 2. Langue : 100% Français
|
||||||
|
|
||||||
|
Tous les fichiers de documentation doivent être en français :
|
||||||
|
|
||||||
|
- ✅ Noms de fichiers en français (kebab-case)
|
||||||
|
- ✅ Contenu en français
|
||||||
|
- ✅ Navigation `mkdocs.yml` en français
|
||||||
|
- ⚠️ Exception : code backend en anglais (convention internationale)
|
||||||
|
|
||||||
|
### 3. Dossier `generated/` = Read-Only
|
||||||
|
|
||||||
|
Le dossier `docs/generated/` contient **exclusivement** des fichiers générés automatiquement.
|
||||||
|
|
||||||
|
❌ **Ne JAMAIS** créer de fichiers manuels dans `generated/`
|
||||||
|
❌ **Ne JAMAIS** éditer des fichiers dans `generated/`
|
||||||
|
✅ Modifier les sources (`.feature`) et regénérer
|
||||||
|
|
||||||
|
## Ajouter une Nouvelle Feature BDD
|
||||||
|
|
||||||
|
### Étape 1 : Créer le fichier `.feature`
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Créer dans le bon domaine
|
||||||
|
touch domains/[domain]/features/[category]/ma-feature.feature
|
||||||
|
```
|
||||||
|
|
||||||
|
**Exemple** : Feature de recherche dans le domaine recommendation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
touch domains/recommendation/features/recherche/recherche-avancee.feature
|
||||||
|
```
|
||||||
|
|
||||||
|
### Étape 2 : Écrire la feature en Gherkin
|
||||||
|
|
||||||
|
```gherkin
|
||||||
|
# language: fr
|
||||||
|
Fonctionnalité: Recherche avancée de contenus
|
||||||
|
En tant qu'utilisateur
|
||||||
|
Je veux rechercher des contenus avec des filtres avancés
|
||||||
|
Afin de trouver exactement ce que je cherche
|
||||||
|
|
||||||
|
Contexte:
|
||||||
|
Étant donné que je suis connecté
|
||||||
|
Et que je suis sur la page de recherche
|
||||||
|
|
||||||
|
Scénario: Recherche par catégorie et distance
|
||||||
|
Quand je sélectionne la catégorie "Tourisme"
|
||||||
|
Et je définis un rayon de 10 km
|
||||||
|
Alors je vois uniquement les contenus de type "Tourisme"
|
||||||
|
Et tous les résultats sont à moins de 10 km
|
||||||
|
|
||||||
|
Scénario: Recherche avec filtres multiples
|
||||||
|
# ... autres scénarios
|
||||||
|
```
|
||||||
|
|
||||||
|
**Conventions Gherkin** :
|
||||||
|
- Langue française (`# language: fr`)
|
||||||
|
- Mots-clés : `Fonctionnalité`, `Scénario`, `Étant donné`, `Quand`, `Alors`
|
||||||
|
- Commentaires pour référencer les règles DDD
|
||||||
|
|
||||||
|
### Étape 3 : Regénérer la documentation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
make bdd-docs
|
||||||
|
```
|
||||||
|
|
||||||
|
Cette commande :
|
||||||
|
1. Parse les fichiers `.feature`
|
||||||
|
2. Génère les `.md` dans `generated/bdd/`
|
||||||
|
3. Démarre le serveur MkDocs (http://localhost:8000)
|
||||||
|
|
||||||
|
### Étape 4 : Ajouter dans `mkdocs.yml`
|
||||||
|
|
||||||
|
Si la catégorie n'existe pas encore, l'ajouter :
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
- '🎯 Recommendation':
|
||||||
|
# ...
|
||||||
|
- Tests BDD:
|
||||||
|
- 'Recherche':
|
||||||
|
- Recherche de contenu: generated/bdd/recommendation/features/recherche/recherche.md
|
||||||
|
- Recherche avancée: generated/bdd/recommendation/features/recherche/recherche-avancee.md # ← NOUVEAU
|
||||||
|
```
|
||||||
|
|
||||||
|
### Étape 5 : Commit
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git add domains/recommendation/features/recherche/recherche-avancee.feature
|
||||||
|
git add mkdocs.yml
|
||||||
|
git commit -m "feat(bdd): ajouter feature recherche avancée
|
||||||
|
|
||||||
|
- Ajout recherche par catégorie et distance
|
||||||
|
- Ajout filtres multiples
|
||||||
|
- Couverture domaine recommendation"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Ajouter une Règle Métier
|
||||||
|
|
||||||
|
### Étape 1 : Identifier le domaine
|
||||||
|
|
||||||
|
Déterminer dans quel domaine DDD se situe la règle :
|
||||||
|
|
||||||
|
- **Shared** : Authentification, RGPD, erreurs, profil
|
||||||
|
- **Recommendation** : Algorithme, jauges d'intérêt, recherche
|
||||||
|
- **Content** : Audio-guides, création, streaming
|
||||||
|
- **Moderation** : Signalements, validation, sanctions
|
||||||
|
- **Advertising** : Publicités, ciblage
|
||||||
|
- **Premium** : Abonnements, mode offline
|
||||||
|
- **Monetization** : Paiements, revenus créateurs
|
||||||
|
|
||||||
|
### Étape 2 : Créer ou éditer le fichier de règles
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Éditer fichier existant
|
||||||
|
vim domains/[domain]/rules/[theme].md
|
||||||
|
|
||||||
|
# Ou créer un nouveau fichier
|
||||||
|
touch domains/[domain]/rules/nouveau-theme.md
|
||||||
|
```
|
||||||
|
|
||||||
|
### Étape 3 : Documenter la règle
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Règles - Nouveau Thème
|
||||||
|
|
||||||
|
## Contexte
|
||||||
|
|
||||||
|
Description du contexte métier...
|
||||||
|
|
||||||
|
## Règles
|
||||||
|
|
||||||
|
### Règle 1 : Titre de la règle
|
||||||
|
|
||||||
|
**Contexte** : Quand...
|
||||||
|
**Règle** : L'utilisateur doit/peut/ne peut pas...
|
||||||
|
**Justification** : Parce que...
|
||||||
|
|
||||||
|
**Exemple** :
|
||||||
|
- Cas nominal : ...
|
||||||
|
- Cas d'erreur : ...
|
||||||
|
|
||||||
|
### Règle 2 : Autre règle
|
||||||
|
|
||||||
|
...
|
||||||
|
|
||||||
|
## Liens avec d'autres domaines
|
||||||
|
|
||||||
|
- [Entité X](../entities/entite-x.md)
|
||||||
|
- [Séquence Y](../sequences/sequence-y.md)
|
||||||
|
- [ADR-XXX](../../adr/XXX-decision.md)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Étape 4 : Créer les features BDD correspondantes
|
||||||
|
|
||||||
|
Les règles métier doivent être testables → créer des features BDD.
|
||||||
|
|
||||||
|
### Étape 5 : Ajouter dans `mkdocs.yml`
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
- '🎙️ Content':
|
||||||
|
- Règles:
|
||||||
|
- Création & Publication: domains/content/rules/creation-publication.md
|
||||||
|
- Nouveau Thème: domains/content/rules/nouveau-theme.md # ← NOUVEAU
|
||||||
|
```
|
||||||
|
|
||||||
|
## Ajouter une Entité
|
||||||
|
|
||||||
|
### Créer le fichier
|
||||||
|
|
||||||
|
```bash
|
||||||
|
touch domains/[domain]/entities/nouvelle-entite.md
|
||||||
|
```
|
||||||
|
|
||||||
|
### Documenter l'entité
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Entité : NouvelleThing
|
||||||
|
|
||||||
|
## Description
|
||||||
|
|
||||||
|
Brève description de l'entité...
|
||||||
|
|
||||||
|
## Attributs
|
||||||
|
|
||||||
|
| Attribut | Type | Description | Contraintes |
|
||||||
|
|----------|------|-------------|-------------|
|
||||||
|
| `id` | UUID | Identifiant unique | PK, NOT NULL |
|
||||||
|
| `name` | String | Nom de la chose | NOT NULL, max 255 |
|
||||||
|
| `created_at` | Timestamp | Date de création | NOT NULL |
|
||||||
|
|
||||||
|
## Relations
|
||||||
|
|
||||||
|
- **BelongsTo** : [User](../../../_shared/entities/users.md)
|
||||||
|
- **HasMany** : [Items](./items.md)
|
||||||
|
|
||||||
|
## États du Cycle de Vie
|
||||||
|
|
||||||
|
Voir [Lifecycle](../states/nouvelle-thing-lifecycle.md)
|
||||||
|
|
||||||
|
## Règles Métier
|
||||||
|
|
||||||
|
- [Règle de création](../rules/creation.md#nouvelle-thing)
|
||||||
|
- [Règle de validation](../rules/validation.md#nouvelle-thing)
|
||||||
|
|
||||||
|
## Implémentation Backend
|
||||||
|
|
||||||
|
**Module** : `backend/internal/[domain]/`
|
||||||
|
**Table** : `nouvelle_things`
|
||||||
|
**Repository** : `nouvelle_thing_repository.go`
|
||||||
|
|
||||||
|
Requêtes sqlc : `backend/queries/nouvelle_thing.sql`
|
||||||
|
```
|
||||||
|
|
||||||
|
### Ajouter dans `mkdocs.yml`
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
- Entités:
|
||||||
|
- Vue d'ensemble: domains/[domain]/entities/vue-ensemble.md
|
||||||
|
- Nouvelle Entité: domains/[domain]/entities/nouvelle-entite.md # ← NOUVEAU
|
||||||
|
```
|
||||||
|
|
||||||
|
## Ajouter un Diagramme
|
||||||
|
|
||||||
|
### Diagrammes de Séquence
|
||||||
|
|
||||||
|
```bash
|
||||||
|
touch domains/[domain]/sequences/nouveau-processus.md
|
||||||
|
```
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Séquence - Nouveau Processus
|
||||||
|
|
||||||
|
## Diagramme
|
||||||
|
|
||||||
|
\`\`\`mermaid
|
||||||
|
sequenceDiagram
|
||||||
|
participant U as Utilisateur
|
||||||
|
participant A as API
|
||||||
|
participant DB as Database
|
||||||
|
|
||||||
|
U->>A: POST /nouvelle-action
|
||||||
|
A->>DB: Vérifier permissions
|
||||||
|
DB-->>A: OK
|
||||||
|
A->>DB: INSERT nouvelle_thing
|
||||||
|
A-->>U: 201 Created
|
||||||
|
\`\`\`
|
||||||
|
|
||||||
|
## Légende
|
||||||
|
|
||||||
|
**Acteurs** :
|
||||||
|
- Utilisateur : Client de l'API
|
||||||
|
- API : Backend RoadWave
|
||||||
|
- Database : PostgreSQL
|
||||||
|
|
||||||
|
**Étapes clés** :
|
||||||
|
1. Vérification des permissions
|
||||||
|
2. Insertion en base
|
||||||
|
3. Retour confirmation
|
||||||
|
|
||||||
|
## Cas d'Erreur
|
||||||
|
|
||||||
|
### Permissions insuffisantes
|
||||||
|
...
|
||||||
|
|
||||||
|
### Contrainte violée
|
||||||
|
...
|
||||||
|
```
|
||||||
|
|
||||||
|
### Diagrammes d'États
|
||||||
|
|
||||||
|
```bash
|
||||||
|
touch domains/[domain]/states/nouvelle-thing-lifecycle.md
|
||||||
|
```
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# États - Lifecycle NouvelleThing
|
||||||
|
|
||||||
|
## Diagramme
|
||||||
|
|
||||||
|
\`\`\`mermaid
|
||||||
|
stateDiagram-v2
|
||||||
|
[*] --> Draft
|
||||||
|
Draft --> Pending: Submit
|
||||||
|
Pending --> Approved: Approve
|
||||||
|
Pending --> Rejected: Reject
|
||||||
|
Approved --> Published: Publish
|
||||||
|
Published --> Archived: Archive
|
||||||
|
Archived --> [*]
|
||||||
|
\`\`\`
|
||||||
|
|
||||||
|
## États
|
||||||
|
|
||||||
|
| État | Description | Transitions Possibles |
|
||||||
|
|------|-------------|----------------------|
|
||||||
|
| Draft | Création en cours | → Pending |
|
||||||
|
| Pending | En attente validation | → Approved, Rejected |
|
||||||
|
| Approved | Validé | → Published |
|
||||||
|
| Rejected | Refusé | → Draft (correction) |
|
||||||
|
| Published | Publié | → Archived |
|
||||||
|
| Archived | Archivé | (final) |
|
||||||
|
|
||||||
|
## Règles de Transition
|
||||||
|
|
||||||
|
### Draft → Pending
|
||||||
|
**Conditions** : Tous les champs obligatoires remplis
|
||||||
|
**Actions** : Notification modérateurs
|
||||||
|
```
|
||||||
|
|
||||||
|
## Conventions de Nommage
|
||||||
|
|
||||||
|
### Fichiers Markdown
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Format : kebab-case-francais.md
|
||||||
|
✅ export-donnees.md
|
||||||
|
✅ suppression-compte.md
|
||||||
|
✅ moderation-communautaire.md
|
||||||
|
✅ vue-ensemble.md
|
||||||
|
|
||||||
|
❌ data-export.md (anglais)
|
||||||
|
❌ entities-overview.md (anglais)
|
||||||
|
❌ ExportDonnees.md (PascalCase)
|
||||||
|
❌ export_donnees.md (snake_case)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Fichiers Features
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Format : kebab-case-francais.feature
|
||||||
|
✅ signalement.feature
|
||||||
|
✅ jauge-initiale.feature
|
||||||
|
✅ creation-audio-guide.feature
|
||||||
|
|
||||||
|
❌ reporting.feature (anglais)
|
||||||
|
❌ initial-gauge.feature (anglais)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Répertoires
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Format : kebab-case-anglais (convention internationale)
|
||||||
|
✅ features/
|
||||||
|
✅ interest-gauges/
|
||||||
|
✅ content-creation/
|
||||||
|
✅ rgpd-compliance/
|
||||||
|
```
|
||||||
|
|
||||||
|
## Vérifications Avant Commit
|
||||||
|
|
||||||
|
### Checklist
|
||||||
|
|
||||||
|
- [ ] Tous les fichiers sont en français (sauf code backend)
|
||||||
|
- [ ] Pas de fichiers dans `generated/` (seulement sources modifiées)
|
||||||
|
- [ ] Les liens internes fonctionnent
|
||||||
|
- [ ] `mkdocs.yml` mis à jour si nécessaire
|
||||||
|
- [ ] Features BDD regénérées (`make bdd-docs`)
|
||||||
|
- [ ] Message de commit descriptif
|
||||||
|
|
||||||
|
### Tester Localement
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Vérifier syntaxe YAML
|
||||||
|
python3 -c "import yaml; yaml.safe_load(open('mkdocs.yml'))"
|
||||||
|
|
||||||
|
# Tester la navigation
|
||||||
|
make docs-serve
|
||||||
|
# → http://localhost:8000
|
||||||
|
```
|
||||||
|
|
||||||
|
### Vérifier les Liens
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Chercher liens cassés vers anciens noms
|
||||||
|
grep -r "entities-overview\.md" docs/
|
||||||
|
grep -r "user-account-lifecycle\.md" docs/
|
||||||
|
grep -r "data-export\.md" docs/
|
||||||
|
|
||||||
|
# Ne devrait rien retourner
|
||||||
|
```
|
||||||
|
|
||||||
|
## Messages de Commit
|
||||||
|
|
||||||
|
### Format
|
||||||
|
|
||||||
|
```
|
||||||
|
type(scope): description courte
|
||||||
|
|
||||||
|
Corps optionnel avec détails...
|
||||||
|
|
||||||
|
Refs: #issue-number
|
||||||
|
```
|
||||||
|
|
||||||
|
### Types
|
||||||
|
|
||||||
|
- `feat(bdd)` : Nouvelle feature BDD
|
||||||
|
- `docs(rules)` : Nouvelle règle métier
|
||||||
|
- `docs(entity)` : Nouvelle entité
|
||||||
|
- `fix(link)` : Correction de lien
|
||||||
|
- `refactor(nav)` : Réorganisation navigation
|
||||||
|
|
||||||
|
### Exemples
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Feature BDD
|
||||||
|
git commit -m "feat(bdd): ajouter recherche avancée dans recommendation"
|
||||||
|
|
||||||
|
# Règle métier
|
||||||
|
git commit -m "docs(rules): documenter règles de modération préventive"
|
||||||
|
|
||||||
|
# Entité
|
||||||
|
git commit -m "docs(entity): ajouter entité Campaign pour advertising"
|
||||||
|
|
||||||
|
# Fix
|
||||||
|
git commit -m "fix(link): corriger lien vers vue-ensemble.md"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Ressources
|
||||||
|
|
||||||
|
- **Architecture DDD** : [domains/README.md](domains/README.md)
|
||||||
|
- **Tests BDD** : [ADR-007](adr/007-tests-bdd.md)
|
||||||
|
- **Migration** : [MIGRATION.md](MIGRATION.md)
|
||||||
|
- **ADRs** : [adr/README.md](adr/README.md)
|
||||||
|
|
||||||
|
## Support
|
||||||
|
|
||||||
|
Questions ? Consultez :
|
||||||
|
1. Cette documentation
|
||||||
|
2. Les ADRs existants
|
||||||
|
3. Les exemples dans les domaines existants
|
||||||
|
4. L'équipe RoadWave
|
||||||
|
|
||||||
|
## Auteurs
|
||||||
|
|
||||||
|
- Équipe RoadWave
|
||||||
|
- Claude Sonnet 4.5 (documentation)
|
||||||
|
|
||||||
|
Dernière mise à jour : 2026-02-08
|
||||||
220
docs/MIGRATION.md
Normal file
220
docs/MIGRATION.md
Normal file
@@ -0,0 +1,220 @@
|
|||||||
|
# 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** :
|
||||||
|
```yaml
|
||||||
|
- 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** :
|
||||||
|
```yaml
|
||||||
|
- 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
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Ancien lien (cassé)
|
||||||
|
docs/domains/_shared/entities/entities-overview.md
|
||||||
|
|
||||||
|
# Nouveau lien
|
||||||
|
docs/domains/_shared/entities/vue-ensemble.md
|
||||||
|
```
|
||||||
|
|
||||||
|
### États
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Ancien lien (cassé)
|
||||||
|
docs/domains/_shared/states/user-account-lifecycle.md
|
||||||
|
|
||||||
|
# Nouveau lien
|
||||||
|
docs/domains/_shared/states/compte-utilisateur.md
|
||||||
|
```
|
||||||
|
|
||||||
|
### Séquences
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# 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 :
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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
|
||||||
Reference in New Issue
Block a user