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.
This commit is contained in:
jpgiannetti
249
docs/domains/README.md
Normal file
249
docs/domains/README.md
Normal file
@@ -0,0 +1,249 @@
|
||||
# Context Map RoadWave
|
||||
|
||||
## Vue d'ensemble
|
||||
|
||||
RoadWave est organisé selon les principes du **Domain-Driven Design (DDD)** avec **7 bounded contexts** clairs. Cette architecture modulaire permet une meilleure séparation des préoccupations, facilite la maintenance et l'évolution du système.
|
||||
|
||||
## Architecture des domaines
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Core Domain"
|
||||
SHARED[_shared<br/>Authentification, RGPD, Erreurs]
|
||||
end
|
||||
|
||||
subgraph "Supporting Subdomains"
|
||||
RECO[recommendation<br/>Jauges & Algorithme]
|
||||
CONTENT[content<br/>Audio-guides & Live]
|
||||
MODERATION[moderation<br/>Signalements & Sanctions]
|
||||
end
|
||||
|
||||
subgraph "Generic Subdomains"
|
||||
ADS[advertising<br/>Publicités]
|
||||
PREMIUM[premium<br/>Abonnements]
|
||||
MONETIZATION[monetization<br/>Monétisation créateurs]
|
||||
end
|
||||
|
||||
%% Dépendances principales
|
||||
RECO --> SHARED
|
||||
RECO --> CONTENT
|
||||
CONTENT --> SHARED
|
||||
ADS --> SHARED
|
||||
ADS --> RECO
|
||||
PREMIUM --> SHARED
|
||||
PREMIUM --> CONTENT
|
||||
MONETIZATION --> SHARED
|
||||
MONETIZATION --> CONTENT
|
||||
MONETIZATION --> ADS
|
||||
MONETIZATION --> PREMIUM
|
||||
MODERATION --> SHARED
|
||||
MODERATION --> CONTENT
|
||||
|
||||
%% Relations anti-corruption
|
||||
ADS -.-|bloqué par| PREMIUM
|
||||
MODERATION -.->|peut démonétiser| MONETIZATION
|
||||
```
|
||||
|
||||
## Bounded Contexts
|
||||
|
||||
### Core Domain
|
||||
|
||||
#### 🔐 [_shared](/_shared/)
|
||||
**Responsabilité** : Fonctionnalités transversales essentielles
|
||||
|
||||
- Authentification et inscription via Zitadel
|
||||
- Conformité RGPD (consentements, suppression données)
|
||||
- Gestion cohérente des erreurs
|
||||
- Entités centrales : `USERS`, `CONTENTS`, `SUBSCRIPTIONS`, `LISTENING_HISTORY`
|
||||
|
||||
**Utilisé par** : Tous les autres domaines
|
||||
|
||||
---
|
||||
|
||||
### Supporting Subdomains
|
||||
|
||||
#### 🎯 [recommendation](/recommendation/)
|
||||
**Responsabilité** : Recommandation géolocalisée de contenus
|
||||
|
||||
- Jauges de centres d'intérêt (scores dynamiques 0-100)
|
||||
- Algorithme de scoring (distance + affinité)
|
||||
- Adaptation selon interactions utilisateur
|
||||
- Entités : `USER_INTERESTS`, `INTEREST_CATEGORIES`
|
||||
|
||||
**Dépend de** : `_shared`, `content`
|
||||
|
||||
**Ubiquitous Language** : Interest Gauge, Recommendation Score, Geographic Priority, Interest Decay
|
||||
|
||||
---
|
||||
|
||||
#### 🎙️ [content](/content/)
|
||||
**Responsabilité** : Création et diffusion de contenus audio
|
||||
|
||||
- Audio-guides multi-séquences géolocalisés
|
||||
- Radio live et enregistrements
|
||||
- Contenus géolocalisés pour voiture/piéton
|
||||
- Détection de contenu protégé (droits d'auteur)
|
||||
- Entités : `AUDIO_GUIDES`, `LIVE_STREAMS`, `GUIDE_SEQUENCES`, `LIVE_RECORDINGS`
|
||||
|
||||
**Dépend de** : `_shared`
|
||||
|
||||
**Interagit avec** : `moderation` (modération), `monetization` (revenus)
|
||||
|
||||
**Ubiquitous Language** : Audio Guide, Guide Sequence, Live Stream, Geofence, Content Fingerprint
|
||||
|
||||
---
|
||||
|
||||
#### 🛡️ [moderation](/moderation/)
|
||||
**Responsabilité** : Modération et sécurité de la plateforme
|
||||
|
||||
- Workflow de traitement des signalements
|
||||
- Système de strikes et sanctions
|
||||
- Processus d'appel
|
||||
- Badges de confiance créateurs
|
||||
- Modération communautaire
|
||||
- Entités : `REPORTS`, `SANCTIONS`, `APPEALS`, `STRIKES`, `BADGES`
|
||||
|
||||
**Dépend de** : `_shared`, `content`
|
||||
|
||||
**Peut affecter** : `monetization` (démonétisation)
|
||||
|
||||
**Ubiquitous Language** : Report, Strike, Sanction, Appeal, Trust Badge, Community Moderation
|
||||
|
||||
---
|
||||
|
||||
### Generic Subdomains
|
||||
|
||||
#### 📢 [advertising](/advertising/)
|
||||
**Responsabilité** : Publicités audio géociblées
|
||||
|
||||
- Campagnes publicitaires
|
||||
- Ciblage géographique et par intérêts
|
||||
- Métriques (impressions, CPM)
|
||||
- Insertion dynamique dans flux audio
|
||||
- Entités : `AD_CAMPAIGNS`, `AD_METRICS`, `AD_IMPRESSIONS`
|
||||
|
||||
**Dépend de** : `_shared`, `recommendation` (ciblage)
|
||||
|
||||
**Bloqué par** : `premium` (pas de pub pour abonnés)
|
||||
|
||||
**Ubiquitous Language** : Ad Campaign, Ad Impression, CPM, Ad Targeting, Skip Rate
|
||||
|
||||
---
|
||||
|
||||
#### 💎 [premium](/premium/)
|
||||
**Responsabilité** : Abonnements et fonctionnalités premium
|
||||
|
||||
- Abonnements payants (mensuel/annuel)
|
||||
- Mode offline (téléchargement, synchro)
|
||||
- Notifications personnalisées
|
||||
- Avantages : sans pub, qualité audio supérieure
|
||||
- Entités : `PREMIUM_SUBSCRIPTIONS`, `ACTIVE_STREAMS`, `OFFLINE_DOWNLOADS`
|
||||
|
||||
**Dépend de** : `_shared`, `content`
|
||||
|
||||
**Bloque** : `advertising` (désactivation pubs)
|
||||
|
||||
**Ubiquitous Language** : Premium Subscription, Offline Download, Sync Queue, Premium Tier, Auto-Renewal
|
||||
|
||||
---
|
||||
|
||||
#### 💰 [monetization](/monetization/)
|
||||
**Responsabilité** : Monétisation des créateurs
|
||||
|
||||
- KYC (vérification identité)
|
||||
- Calcul des revenus (pub + abonnements)
|
||||
- Versements mensuels via Mangopay
|
||||
- Tableaux de bord revenus
|
||||
- Entités : `CREATOR_MONETIZATION`, `REVENUES`, `PAYOUTS`
|
||||
|
||||
**Dépend de** : `_shared`, `content`, `advertising`, `premium`
|
||||
|
||||
**Affecté par** : `moderation` (démonétisation en cas de sanction)
|
||||
|
||||
**Ubiquitous Language** : Revenue Share, KYC Verification, Payout, Minimum Threshold
|
||||
|
||||
---
|
||||
|
||||
## Relations entre domaines
|
||||
|
||||
### Upstream/Downstream
|
||||
|
||||
| Upstream (Fournisseur) | Downstream (Consommateur) | Type de relation |
|
||||
|------------------------|---------------------------|------------------|
|
||||
| `_shared` | Tous | **Kernel partagé** |
|
||||
| `content` | `recommendation` | **Customer/Supplier** |
|
||||
| `recommendation` | `advertising` | **Customer/Supplier** |
|
||||
| `premium` | `advertising` | **Anti-Corruption Layer** |
|
||||
|
||||
### Événements de domaine
|
||||
|
||||
Les domaines communiquent via des événements métier :
|
||||
|
||||
- **UserRegistered** (`_shared` → tous) : Nouvel utilisateur
|
||||
- **ContentPublished** (`content` → `recommendation`, `moderation`) : Nouveau contenu
|
||||
- **InterestGaugeUpdated** (`recommendation` → `advertising`) : Mise à jour jauges
|
||||
- **UserBanned** (`moderation` → `monetization`) : Bannissement utilisateur
|
||||
- **SubscriptionActivated** (`premium` → `advertising`) : Activation premium
|
||||
|
||||
## Structure de la documentation
|
||||
|
||||
Chaque domaine suit cette organisation :
|
||||
|
||||
```
|
||||
domains/<domain>/
|
||||
├── README.md # Vue d'ensemble du domaine
|
||||
├── rules/ # Règles métier (*.md)
|
||||
├── entities/ # Diagrammes entités (*.md)
|
||||
├── sequences/ # Diagrammes séquences (*.md)
|
||||
├── states/ # Diagrammes états (*.md)
|
||||
├── flows/ # Diagrammes flux (*.md)
|
||||
└── features/ # Tests BDD Gherkin (*.feature)
|
||||
```
|
||||
|
||||
## Navigation
|
||||
|
||||
- [📖 Règles métier par numéro](../regles-metier/) *(structure legacy, déprécié)*
|
||||
- [🏛️ ADR (Architecture Decision Records)](../adr/)
|
||||
- [⚖️ Documentation légale](../legal/)
|
||||
- [🖥️ Interfaces UI](../interfaces/)
|
||||
- [🔧 Documentation technique](../technical.md)
|
||||
|
||||
## Ubiquitous Language Global
|
||||
|
||||
**Termes transversaux utilisés dans tous les domaines** :
|
||||
|
||||
- **User** : Utilisateur (auditeur, créateur, ou les deux)
|
||||
- **Content** : Contenu audio diffusé sur la plateforme
|
||||
- **Creator** : Utilisateur créant du contenu
|
||||
- **Geolocation** : Position GPS de l'utilisateur
|
||||
- **Stream** : Flux de lecture audio
|
||||
- **Subscription** : Abonnement (à un créateur ou à premium)
|
||||
- **Interest** : Centre d'intérêt (automobile, voyage, musique, etc.)
|
||||
|
||||
## Principes d'architecture
|
||||
|
||||
1. **Bounded Contexts clairs** : Chaque domaine a des limites bien définies
|
||||
2. **Autonomie des domaines** : Chaque domaine peut évoluer indépendamment
|
||||
3. **Communication asynchrone** : Préférence pour les événements vs appels directs
|
||||
4. **Anti-Corruption Layer** : Protection contre les changements externes
|
||||
5. **Alignment code/docs** : Structure docs ↔ structure `backend/internal/`
|
||||
|
||||
## Alignement avec le code backend
|
||||
|
||||
```
|
||||
backend/internal/ docs/domains/
|
||||
├── auth/ ←→ _shared/
|
||||
├── user/ ←→ _shared/
|
||||
├── content/ ←→ content/
|
||||
├── geo/ ←→ recommendation/
|
||||
├── streaming/ ←→ content/
|
||||
├── moderation/ ←→ moderation/
|
||||
├── payment/ ←→ monetization/
|
||||
└── analytics/ ←→ recommendation/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Dernière mise à jour** : 2026-02-07
|
||||
**Statut** : ✅ Active
|
||||
**Auteur** : Documentation DDD initiative
|
||||
Reference in New Issue
Block a user