diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 3d74042..876fa5d 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -438,7 +438,6 @@ git commit -m "fix(link): corriger lien vers vue-ensemble.md" - **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 diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md deleted file mode 100644 index b8f0592..0000000 --- a/docs/MIGRATION.md +++ /dev/null @@ -1,220 +0,0 @@ -# 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 diff --git a/docs/architecture/sequences/cache-geospatial.md b/docs/architecture/sequences/cache-geospatial.md deleted file mode 100644 index bd0ae2a..0000000 --- a/docs/architecture/sequences/cache-geospatial.md +++ /dev/null @@ -1,320 +0,0 @@ -# Diagramme de Séquence : Cache Géospatial Redis - -> Architecture du cache Redis Geospatial pour l'optimisation des requêtes de découverte de contenu géolocalisé. - -## Vue d'ensemble - -Le cache Redis Geospatial permet d'accélérer la recherche de contenus audio à proximité d'une position GPS en évitant des calculs PostGIS coûteux sur PostgreSQL à chaque requête. - -**Performance** : -- Sans cache : ~200-500ms (calcul PostGIS sur 100K points) -- Avec cache : ~5-10ms (filtrage Redis en mémoire) - ---- - -## Flux complet : Cold Start → Warm Cache - -```mermaid -sequenceDiagram - participant User as 📱 Utilisateur
(Paris) - participant Backend as 🔧 Backend Go - participant Redis as 🔴 Redis Geospatial
(Cache) - participant PostgreSQL as 🗄️ PostgreSQL
+ PostGIS - participant CDN as 🌐 NGINX Cache (OVH VPS) - - Note over User,CDN: 🥶 Cold Start - Cache vide - - User->>Backend: GET /contents?lat=48.8566&lon=2.3522&radius=50km - Backend->>Redis: EXISTS geo:catalog - Redis-->>Backend: false (cache vide) - - Backend->>PostgreSQL: SELECT id, lat, lon, title, geo_level
FROM contents WHERE active=true - Note over PostgreSQL: Tous les contenus actifs
de la plateforme (métadonnées) - PostgreSQL-->>Backend: 100K contenus (métadonnées) - - Backend->>Redis: GEOADD geo:catalog
lon1 lat1 "content:1"
lon2 lat2 "content:2"
... (100K entrées) - Note over Redis: Stockage index spatial
en mémoire (~20 MB) - Redis-->>Backend: OK (100000) - - Backend->>Redis: EXPIRE geo:catalog 300 - Note over Redis: TTL 5 minutes - - Backend->>Redis: GEORADIUS geo:catalog
2.3522 48.8566 50 km - Note over Redis: Filtrage spatial instantané
(index geohash) - Redis-->>Backend: [content:123, content:456, ...]
(~500 IDs dans rayon) - - Backend->>PostgreSQL: SELECT * FROM contents
WHERE id IN (123, 456, ...)
AND geo_level = 'gps_precise' - Note over PostgreSQL: Récupération détails complets
uniquement contenus proches - PostgreSQL-->>Backend: Détails complets (500 contenus GPS) - - Backend->>PostgreSQL: SELECT * FROM contents
WHERE city='Paris' OR dept='75'
OR region='IDF' OR geo_level='national' - Note over PostgreSQL: Contenus par niveau géographique - PostgreSQL-->>Backend: Contenus ville/région/national - - Backend->>Backend: Scoring & mixage :
- GPS proche : 70%
- Ville : 20%
- Région : 8%
- National : 2% - - Backend-->>User: JSON: [{id, title, creator, audioUrl, score}, ...]
(playlist mixée et scorée) - - Note over User,CDN: 🎵 Lecture audio (requêtes séparées) - - User->>CDN: GET /audio/content-123.m3u8 - CDN-->>User: Playlist HLS - - User->>CDN: GET /audio/content-123-segment-001.ts - CDN-->>User: Segment audio Opus - - Note over User,CDN: 🔥 Warm Cache - Utilisateur 2 à Lyon (45km+) - - participant User2 as 📱 Utilisateur 2
(Lyon) - - User2->>Backend: GET /contents?lat=45.7640&lon=4.8357&radius=50km - Backend->>Redis: EXISTS geo:catalog - Redis-->>Backend: true ✅ (cache chaud) - - Backend->>Redis: GEORADIUS geo:catalog
4.8357 45.7640 50 km - Note over Redis: Filtrage instantané
sur cache existant - Redis-->>Backend: [content:789, content:012, ...]
(~300 IDs différents) - - Backend->>PostgreSQL: SELECT * FROM contents
WHERE id IN (789, 012, ...)
AND geo_level = 'gps_precise' - PostgreSQL-->>Backend: Détails complets - - Backend->>PostgreSQL: SELECT * FROM contents
WHERE city='Lyon' OR dept='69'
OR region='Auvergne-RA' OR geo_level='national' - PostgreSQL-->>Backend: Contenus ville/région/national - - Backend->>Backend: Scoring & mixage - - Backend-->>User2: JSON: [{id, title, creator, audioUrl, score}, ...] -``` - ---- - -## Stratégie de cache - -### Cache du catalogue complet (approche choisie) - -**Principe** : Au premier cache miss, charger **TOUS** les contenus géolocalisés en une seule fois dans Redis. - -**Avantages** : -- ✅ 1 seul cache miss au démarrage de l'instance -- ✅ Toutes les requêtes suivantes servies par Redis (n'importe quelle position GPS) -- ✅ Simple à gérer (1 seule clé Redis : `geo:catalog`) -- ✅ Pas de duplication de données - -**Inconvénients** : -- ⚠️ Premier utilisateur subit le cold start (~500ms-1s) -- ⚠️ Nécessite charger toute la base (acceptable : ~20 MB pour 100K contenus) - -**Alternatives non retenues** : -- Cache par zone géographique → cache miss fréquents, complexité gestion chevauchements -- Cache à la demande → trop de cache miss, pas d'optimisation réelle - ---- - -## Détails techniques - -### 1. Données stockées dans Redis - -**Clé Redis** : `geo:catalog` - -**Structure** : -``` -GEOADD geo:catalog - 2.3522 48.8566 "content:12345" # lon, lat, member - 4.8357 45.7640 "content:67890" - ... -``` - -**Taille mémoire** : -- ~200 bytes par entrée (ID + coordonnées + index geohash) -- 100K contenus = ~20 MB -- Négligeable pour Redis (plusieurs GB RAM disponibles) - -**TTL** : 5 minutes (300 secondes) -- Le contenu géolocalisé est quasi-statique (change peu) -- Rechargement automatique toutes les 5 minutes si cache expiré -- Permet de propager les nouveaux contenus rapidement - -### 2. Niveaux géographiques - -Le cache Redis ne contient que les contenus avec **GPS précis** (`geo_level = 'gps_precise'`). - -Les autres niveaux géographiques sont gérés par filtrage applicatif : - -| Niveau | Stockage | Requête | -|--------|----------|---------| -| **GPS précis** | Redis + PostgreSQL | `GEORADIUS` puis `SELECT WHERE id IN (...)` | -| **Ville** | PostgreSQL uniquement | `SELECT WHERE city = ?` | -| **Département** | PostgreSQL uniquement | `SELECT WHERE department = ?` | -| **Région** | PostgreSQL uniquement | `SELECT WHERE region = ?` | -| **National** | PostgreSQL uniquement | `SELECT WHERE geo_level = 'national'` | - -### 3. Commandes Redis utilisées - -```bash -# Vérifier existence du cache -EXISTS geo:catalog -# Retour : 0 (n'existe pas) ou 1 (existe) - -# Charger le catalogue complet (cold start) -GEOADD geo:catalog 2.3522 48.8566 "content:1" 4.8357 45.7640 "content:2" ... -# Retour : nombre d'éléments ajoutés - -# Définir TTL 5 minutes -EXPIRE geo:catalog 300 - -# Rechercher contenus dans un rayon -GEORADIUS geo:catalog 2.3522 48.8566 50 km -# Retour : ["content:123", "content:456", ...] - -# Optionnel : obtenir distance et coordonnées -GEORADIUS geo:catalog 2.3522 48.8566 50 km WITHDIST WITHCOORD -# Retour : [["content:123", "12.5", ["2.35", "48.85"]], ...] -``` - -### 4. Algorithme de scoring - -Le backend mixe les résultats selon une pondération : - -``` -Score final = - (Pertinence GPS × 0.70) + - (Pertinence Ville × 0.20) + - (Pertinence Région × 0.08) + - (Pertinence National × 0.02) -``` - -**Critères de pertinence** : -- **GPS** : Plus proche = score élevé (distance inversée) -- **Ville/Région** : Matching exact = score maximal -- **National** : Score fixe faible (contenu générique) - -**Mixage playlist** : -1. Trier tous les contenus par score décroissant -2. Appliquer diversité créateurs (pas 3 contenus du même créateur d'affilée) -3. Injecter contenus sponsorisés/mis en avant (futurs) -4. Retourner top 50 pour la session d'écoute - ---- - -## Métriques de performance - -### Temps de réponse typiques - -| Scénario | Latence | Détail | -|----------|---------|--------| -| **Cold start** | 500-1000ms | Chargement 100K contenus dans Redis + requête | -| **Warm cache** | 5-10ms | `GEORADIUS` + `SELECT WHERE id IN (...)` | -| **TTL expiré** | 500-1000ms | Rechargement automatique | - -### Charge serveurs - -| Composant | Sans cache | Avec cache | -|-----------|------------|------------| -| **PostgreSQL CPU** | 60-80% | 10-20% | -| **Redis CPU** | N/A | 5-15% | -| **Throughput** | ~50 req/s | ~500 req/s | - ---- - -## Cas limites et optimisations futures - -### Cas limite 1 : Contenu très dense (Paris intra-muros) - -**Problème** : 10K contenus dans rayon 5km → trop de résultats - -**Solution actuelle** : -- Limiter résultats Redis à 1000 premiers (tri par distance) -- Scorer et filtrer côté application - -**Optimisation future** : -- Ajuster rayon dynamiquement selon densité -- Utiliser `GEORADIUS ... COUNT 500` pour limiter côté Redis - -### Cas limite 2 : Zones rurales (peu de contenu) - -**Problème** : Rayon 50km retourne <10 contenus - -**Solution actuelle** : -- Augmenter poids contenus région/national dans le scoring -- Suggérer contenus nationaux populaires - -**Optimisation future** : -- Augmenter rayon automatiquement jusqu'à obtenir min 20 contenus -- `GEORADIUS ... 100 km` si rayon initial insuffisant - -### Cas limite 3 : Nombreux créateurs actifs (évolutivité) - -**Problème** : Cache 100K → 1M contenus (200 MB Redis) - -**Solution actuelle** : -- 200 MB reste acceptable pour Redis - -**Optimisation future** : -- Sharding géographique : cache Europe, cache USA, etc. -- Limiter cache aux contenus actifs 90 derniers jours - ---- - -## Invalidation du cache - -### Stratégies d'invalidation - -| Événement | Action cache | Détail | -|-----------|--------------|--------| -| **Nouveau contenu publié** | Lazy (TTL) | Visible sous 5 minutes max | -| **Contenu supprimé/modéré** | Lazy (TTL) | Disparaît sous 5 minutes max | -| **Mise à jour GPS contenu** | Lazy (TTL) | Nouvelle position sous 5 minutes | -| **Déploiement backend** | Flush volontaire | `DEL geo:catalog` si schema change | - -**Pas d'invalidation immédiate** pour simplifier l'architecture (cohérence éventuelle acceptable). - -**Alternative future** : -- Pub/Sub Redis : notifier toutes les instances backend lors d'un changement -- `GEOADD geo:catalog 2.35 48.85 "content:new"` pour ajout immédiat - ---- - -## Schéma simplifié - -``` -┌─────────────────────────────────────────────────────────┐ -│ Utilisateur │ -│ (Position GPS actuelle) │ -└────────────────────────┬────────────────────────────────┘ - │ - │ GET /contents?lat=X&lon=Y&radius=Z - ▼ -┌─────────────────────────────────────────────────────────┐ -│ Backend Go (Fiber) │ -│ │ -│ 1. Vérifier cache Redis │ -│ ├─ Cache HIT → GEORADIUS rapide │ -│ └─ Cache MISS → Charger catalogue complet │ -│ │ -│ 2. Filtrer contenus GPS proches (Redis) │ -│ 3. Récupérer contenus ville/région/national (PG) │ -│ 4. Scorer et mixer selon pondération │ -│ 5. Retourner playlist │ -└────────────┬───────────────────────────┬────────────────┘ - │ │ - │ GEORADIUS │ SELECT détails - ▼ ▼ -┌─────────────────────┐ ┌───────────────────────────┐ -│ Redis Geospatial │ │ PostgreSQL + PostGIS │ -│ (Index spatial) │ │ (Données complètes) │ -│ │ │ │ -│ • geo:catalog │ │ • contents (détails) │ -│ • TTL 5 min │ │ • users │ -│ • ~20 MB mémoire │ │ • playlists │ -└─────────────────────┘ └───────────────────────────┘ -``` - ---- - -## Références - -- [ADR-005 : Base de données](../../adr/005-base-de-donnees.md) -- [Redis Geospatial Commands](https://redis.io/docs/data-types/geospatial/) -- [PostGIS Documentation](https://postgis.net/documentation/) -- [Règles métier : Algorithme de recommandation](../../domains/recommendation/rules/algorithme-recommandation.md) -- [Règles métier : Centres d'intérêt](../../domains/recommendation/rules/centres-interet-jauges.md) diff --git a/docs/domains/_shared/sequences/authentification.md b/docs/domains/_shared/sequences/authentification.md index 34ca193..218f633 100644 --- a/docs/domains/_shared/sequences/authentification.md +++ b/docs/domains/_shared/sequences/authentification.md @@ -20,9 +20,9 @@ sequenceDiagram Z-->>API: Token valide + user_id API->>DB: SELECT user WHERE id = ? DB-->>API: Données utilisateur + API->>DB: INSERT session (hash tokens, IP, device) + DB-->>API: Session créée API-->>A: Profil utilisateur - - A->>DB: INSERT session (hash tokens, IP, device) A->>U: Connexion réussie ``` diff --git a/docs/generated/bdd/advertising/index.md b/docs/generated/bdd/advertising/index.md deleted file mode 100644 index 1e43cd6..0000000 --- a/docs/generated/bdd/advertising/index.md +++ /dev/null @@ -1,55 +0,0 @@ -# Domaine : Advertising - -Ce domaine gère la diffusion de publicités audio géolocalisées, le ciblage publicitaire et la gestion des campagnes. - -## Métriques - -| Métrique | Valeur | -|----------|--------| -| Nombre de features | 7 | -| Nombre de scénarios | 21 | -| Nombre de catégories | 1 | -| Couverture domaine | Moyenne | - -## Catégories de Features - -### Publicités (7 features) -Gestion complète des publicités audio géolocalisées : création de campagnes, ciblage géographique et démographique, diffusion contextuelle et tracking des performances. - -**Features principales** : -- Création et gestion de campagnes publicitaires -- Ciblage géographique (zones, rayons, POI) -- Ciblage démographique et par intérêts -- Insertion de publicités dans le flux audio -- Limitation de fréquence (frequency capping) -- Tracking des impressions et conversions -- Reporting de performance des campagnes - -**Modèle de diffusion** : -- Publicités pré-roll, mid-roll ou post-roll -- Ciblage contextuel basé sur la localisation et les intérêts -- Priorisation par enchères (CPM, CPC) -- Respect des quotas utilisateur (max X pubs/heure) - -## Relations avec le Domaine - -### Règles métier -Consultez les [règles métier du domaine advertising](rules/index.md) pour comprendre les règles de ciblage, de diffusion et de facturation publicitaire. - -### Entités -Consultez les [entités du domaine advertising](entities/index.md) pour voir les structures de données des campagnes, annonces et métriques publicitaires. - -## Architecture Technique - -Le système publicitaire utilise : -- **Géolocalisation** : Ciblage par zones géographiques (PostGIS) -- **Interest matching** : Ciblage par jauges d'intérêt -- **Ad server** : Sélection et diffusion d'annonces -- **Analytics** : Tracking des impressions et performances - -**Intégration avec les autres domaines** : -- **Recommendation** : Utilise les jauges d'intérêt pour le ciblage -- **Analytics** : Remonte les métriques de performance -- **Monetization** : Calcul des revenus publicitaires - -Le module est implémenté dans `backend/internal/advertising/` avec intégration au système de streaming pour l'insertion dynamique de publicités. diff --git a/docs/generated/bdd/content/index.md b/docs/generated/bdd/content/index.md deleted file mode 100644 index bc6c546..0000000 --- a/docs/generated/bdd/content/index.md +++ /dev/null @@ -1,86 +0,0 @@ -# Domaine : Content - -Ce domaine gère l'ensemble du cycle de vie des contenus audio : création, édition, publication, diffusion et navigation. - -## Métriques - -| Métrique | Valeur | -|----------|--------| -| Nombre de features | 59 | -| Nombre de scénarios | 156 | -| Nombre de catégories | 6 | -| Couverture domaine | Très élevée | - -## Catégories de Features - -### Audio Guides (25 features) -Gestion complète des guides audio géolocalisés : création, édition, géolocalisation, métadonnées et diffusion. Les audio guides sont des contenus enrichis liés à des points d'intérêt géographiques. - -**Features principales** : -- Création et édition de guides audio -- Géolocalisation précise (GPS, POI) -- Métadonnées enrichies (catégories, tags, langues) -- Gestion des chapitres et segments -- Publication et modération - -### Content Creation (9 features) -Fonctionnalités de création de contenu : upload audio, édition métadonnées, prévisualisation et validation avant publication. - -**Features principales** : -- Upload de fichiers audio (multiples formats) -- Édition de métadonnées (titre, description, catégorie) -- Prévisualisation du contenu -- Workflow de validation - -### Navigation (9 features) -Navigation dans le catalogue de contenus avec filtres, tri et recherche. - -**Features principales** : -- Parcours du catalogue par catégories -- Filtres multiples (distance, popularité, durée) -- Tri personnalisable -- Exploration géographique - -### Radio Live (7 features) -Gestion des flux radio en direct avec support du streaming continu. - -**Features principales** : -- Diffusion de flux radio live -- Gestion du buffer et de la latence -- Métadonnées en temps réel (morceau en cours) -- Qualité adaptative - -### UI Navigation (8 features) -Interface utilisateur pour la navigation dans l'application mobile. - -**Features principales** : -- Écrans de navigation principaux -- Transitions et animations -- Gestion de l'état de navigation -- Deep linking - -### UI Content Creation (1 feature) -Interface utilisateur pour la création de contenu dans l'application mobile. - -**Features principales** : -- Formulaires de création -- Upload depuis le mobile -- Prévisualisation mobile - -## Relations avec le Domaine - -### Règles métier -Consultez les [règles métier du domaine content](rules/index.md) pour comprendre les contraintes de création, validation et diffusion de contenu. - -### Entités -Consultez les [entités du domaine content](entities/index.md) pour voir les structures de données des contenus audio et leurs métadonnées. - -## Architecture Technique - -Le domaine content utilise : -- **HLS Protocol** : Streaming adaptatif ([ADR-002](../../../adr/002-protocole-streaming.md)) -- **Opus Codec** : Compression audio optimisée ([ADR-003](../../../adr/003-codec-audio.md)) -- **PostGIS** : Géolocalisation des contenus -- **CDN** : Diffusion des assets audio ([ADR-004](../../../adr/004-cdn.md)) - -Le module est implémenté dans `backend/internal/content/` avec le pattern handler → service → repository. diff --git a/docs/generated/bdd/moderation/index.md b/docs/generated/bdd/moderation/index.md deleted file mode 100644 index bac599c..0000000 --- a/docs/generated/bdd/moderation/index.md +++ /dev/null @@ -1,63 +0,0 @@ -# Domaine : Moderation - -Ce domaine gère la modération des contenus, le workflow de validation, les signalements et les actions de modération. - -## Métriques - -| Métrique | Valeur | -|----------|--------| -| Nombre de features | 23 | -| Nombre de scénarios | 67 | -| Nombre de catégories | 3 | -| Couverture domaine | Élevée | - -## Catégories de Features - -### API (16 features) -API de modération pour la validation des contenus, le traitement des signalements et les actions de modération. - -**Features principales** : -- Validation de contenus en attente -- Traitement des signalements utilisateurs -- Actions de modération (approbation, rejet, suppression) -- Workflow de modération multi-niveaux -- Historique des actions de modération -- Notifications aux créateurs de contenu - -### UI (5 features) -Interface utilisateur pour les modérateurs : tableau de bord, queue de modération, détails des signalements. - -**Features principales** : -- Tableau de bord modérateur -- File d'attente de modération -- Détails des contenus à modérer -- Actions rapides (approve/reject) -- Statistiques de modération - -### Admin (2 features) -Fonctionnalités d'administration pour la gestion des modérateurs et la configuration du système de modération. - -**Features principales** : -- Gestion des rôles modérateurs -- Configuration des règles de modération -- Rapports et analytics de modération - -## Relations avec le Domaine - -### Règles métier -Consultez les [règles métier du domaine moderation](rules/index.md) pour comprendre les workflows de validation, les critères de modération et les règles de signalement. - -### Entités -Consultez les [entités du domaine moderation](entities/index.md) pour voir les structures de données des rapports, validations et actions de modération. - -## Architecture Technique - -Le système de modération s'appuie sur : -- **Workflow à états** : Machine à états pour le cycle de vie des contenus (pending → approved/rejected) -- **Queue system** : Priorisation des contenus à modérer -- **Audit trail** : Traçabilité complète des actions de modération -- **Notifications** : Alertes aux créateurs et modérateurs - -Voir [ADR-023](../../../adr/023-architecture-moderation.md) pour l'architecture détaillée du système de modération. - -Le module est implémenté dans `backend/internal/moderation/` avec gestion des états et workflow de validation. diff --git a/docs/generated/bdd/monetization/index.md b/docs/generated/bdd/monetization/index.md deleted file mode 100644 index 6d39de0..0000000 --- a/docs/generated/bdd/monetization/index.md +++ /dev/null @@ -1,62 +0,0 @@ -# Domaine : Monetization - -Ce domaine gère la monétisation pour les créateurs de contenu : revenus publicitaires, abonnements créateurs, tips et analytics financières. - -## Métriques - -| Métrique | Valeur | -|----------|--------| -| Nombre de features | 8 | -| Nombre de scénarios | 24 | -| Nombre de catégories | 1 | -| Couverture domaine | Moyenne | - -## Catégories de Features - -### Monétisation (8 features) -Gestion complète de la monétisation pour les créateurs : revenus publicitaires, abonnements créateurs, tips/dons, partage de revenus et paiements. - -**Features principales** : -- **Revenus publicitaires** : Partage des revenus publicitaires générés par les contenus -- **Abonnements créateurs** : Possibilité de proposer des contenus payants -- **Tips/Dons** : Les auditeurs peuvent envoyer des pourboires aux créateurs -- **Partage de revenus** : Répartition transparente des revenus (70% créateur, 30% plateforme) -- **Tableau de bord financier** : Analytics des revenus en temps réel -- **Paiements** : Versement automatique des revenus via Mangopay -- **Facturation** : Génération de factures et reporting fiscal -- **Seuils de paiement** : Paiement à partir de 50€ de revenus cumulés - -**Modèle de revenus** : -- Publicités : 70% créateur / 30% plateforme -- Abonnements créateurs : 80% créateur / 20% plateforme -- Tips : 95% créateur / 5% plateforme (frais de transaction) - -## Relations avec le Domaine - -### Règles métier -Consultez les [règles métier du domaine monetization](rules/index.md) pour comprendre les règles de partage de revenus, de seuils de paiement et de facturation. - -### Entités -Consultez les [entités du domaine monetization](entities/index.md) pour voir les structures de données des revenus, paiements et transactions. - -## Architecture Technique - -Le système de monétisation utilise : -- **Mangopay** : Plateforme de paiement et wallet pour créateurs ([ADR-009](../../../adr/009-solution-paiement.md)) -- **Revenue tracking** : Calcul en temps réel des revenus par source -- **Automated payouts** : Versements automatiques mensuels -- **Tax compliance** : Génération de documents fiscaux (1099, etc.) - -**Workflow de paiement** : -1. Génération de revenus (pub, abonnement, tips) -2. Agrégation dans le wallet Mangopay du créateur -3. Calcul du partage de revenus -4. Paiement automatique si seuil atteint (50€) -5. Génération de facture/reçu - -Le module est implémenté dans `backend/internal/payment/` avec intégration à l'analytics pour le tracking des revenus. - -**Intégration avec les autres domaines** : -- **Advertising** : Calcul des revenus publicitaires -- **Premium** : Gestion des abonnements créateurs -- **Analytics** : Métriques de revenus et performance diff --git a/docs/generated/bdd/premium/index.md b/docs/generated/bdd/premium/index.md deleted file mode 100644 index e06e0b1..0000000 --- a/docs/generated/bdd/premium/index.md +++ /dev/null @@ -1,68 +0,0 @@ -# Domaine : Premium - -Ce domaine gère les abonnements premium, les fonctionnalités exclusives et le mode offline. - -## Métriques - -| Métrique | Valeur | -|----------|--------| -| Nombre de features | 16 | -| Nombre de scénarios | 44 | -| Nombre de catégories | 3 | -| Couverture domaine | Élevée | - -## Catégories de Features - -### Premium (8 features) -Fonctionnalités exclusives pour les utilisateurs premium : écoute sans publicité, qualité audio supérieure, contenus exclusifs et avantages divers. - -**Features principales** : -- Écoute sans publicité -- Qualité audio haute définition (bitrate supérieur) -- Accès à des contenus exclusifs premium -- Téléchargement illimité pour mode offline -- Statistiques d'écoute avancées -- Support prioritaire - -### Abonnements (4 features) -Gestion des abonnements : souscription, paiement, renouvellement et résiliation. - -**Features principales** : -- Souscription à un plan premium (mensuel, annuel) -- Gestion du paiement récurrent via Mangopay -- Renouvellement automatique -- Résiliation et remboursement au prorata -- Essai gratuit (période d'essai) - -### Mode Offline (4 features) -Téléchargement et écoute de contenus hors connexion. - -**Features principales** : -- Téléchargement de contenus pour écoute offline -- Gestion du cache local (limite de stockage) -- Synchronisation automatique -- Qualité de téléchargement configurable - -## Relations avec le Domaine - -### Règles métier -Consultez les [règles métier du domaine premium](rules/index.md) pour comprendre les règles d'abonnement, de facturation et d'accès aux fonctionnalités premium. - -### Entités -Consultez les [entités du domaine premium](entities/index.md) pour voir les structures de données des abonnements et des avantages premium. - -## Architecture Technique - -Le système premium s'appuie sur : -- **Mangopay** : Gestion des paiements récurrents ([ADR-009](../../../adr/009-solution-paiement.md)) -- **Subscription state machine** : Gestion des états d'abonnement (trial → active → expired → cancelled) -- **Feature flags** : Activation/désactivation de fonctionnalités par plan -- **Local storage** : Cache des contenus offline (Flutter) - -**Modèles d'abonnement** : -- **Freemium** : Accès gratuit avec publicités -- **Premium mensuel** : 4.99€/mois -- **Premium annuel** : 49.99€/an (2 mois offerts) -- **Essai gratuit** : 14 jours - -Le module est implémenté dans `backend/internal/payment/` avec intégration à Mangopay pour la gestion des abonnements récurrents. diff --git a/docs/generated/bdd/recommendation/index.md b/docs/generated/bdd/recommendation/index.md deleted file mode 100644 index e82aef5..0000000 --- a/docs/generated/bdd/recommendation/index.md +++ /dev/null @@ -1,63 +0,0 @@ -# Domaine : Recommendation - -Ce domaine gère le système de recommandation de contenu basé sur la géolocalisation et les jauges d'intérêt des utilisateurs. - -## Métriques - -| Métrique | Valeur | -|----------|--------| -| Nombre de features | 17 | -| Nombre de scénarios | 48 | -| Nombre de catégories | 4 | -| Couverture domaine | Élevée | - -## Catégories de Features - -### Interest Gauges (4 features) -Gestion des jauges d'intérêt utilisateur qui permettent de personnaliser les recommandations. Les jauges évoluent dynamiquement en fonction du comportement d'écoute et des interactions de l'utilisateur. - -**Features principales** : -- Configuration et ajustement des jauges d'intérêt -- Évolution automatique basée sur l'historique d'écoute -- Pondération des catégories (automobile, voyage, musique, etc.) - -### Recommendation (9 features) -Algorithme de recommandation combinant géolocalisation et matching d'intérêts. Calcul de scores combinés distance + intérêts avec cache Redis pour les performances. - -**Features principales** : -- Recommandations géolocalisées multi-niveaux (GPS > ville > département > région > pays) -- Score combiné distance + intérêts -- Priorisation contextuelle (touriste, conducteur, etc.) -- Optimisation via cache Redis GEORADIUS - -### Recherche (3 features) -Fonctionnalités de recherche de contenu avec filtres géographiques et par catégorie. - -**Features principales** : -- Recherche textuelle avec filtres -- Recherche géographique avancée -- Tri par pertinence et distance - -### Search (1 feature) -Recherche unifiée dans l'application mobile. - -**Features principales** : -- Interface de recherche globale -- Suggestions et autocomplétion - -## Relations avec le Domaine - -### Règles métier -Consultez les [règles métier du domaine recommendation](rules/index.md) pour comprendre les contraintes et la logique de l'algorithme de recommandation. - -### Entités -Consultez les [entités du domaine recommendation](entities/index.md) pour voir les structures de données manipulées par le système de recommandation. - -## Architecture Technique - -Le système de recommandation s'appuie sur : -- **PostGIS** : Requêtes spatiales (`ST_DWithin`, `ST_Distance`) -- **Redis** : Cache géospatial pour les performances -- **Jauges dynamiques** : Scores évolutifs par catégorie d'intérêt - -Voir [ADR-005](../../../adr/005-base-de-donnees.md) pour la stratégie PostGIS et [ADR-021](../../../adr/021-solution-cache.md) pour le cache Redis. diff --git a/docs/gherkin-moderation-overview.md b/docs/gherkin-moderation-overview.md deleted file mode 100644 index 744ac3e..0000000 --- a/docs/gherkin-moderation-overview.md +++ /dev/null @@ -1,260 +0,0 @@ -# Vue d'ensemble des Features Gherkin - Modération - -Ce document récapitule l'organisation complète des features Gherkin pour le système de modération de RoadWave, alignées avec les règles métier définies dans : -- [14-moderation-flows.md](domains/moderation/rules/moderation-flows.md) -- [15-moderation-communautaire.md](domains/moderation/rules/moderation-communautaire.md) - -## Structure des Features - -### 📱 Features UI (Interface Mobile Flutter) - -**Localisation** : `features/ui/moderation/` - -| Feature | Description | Règles métier couvertes | -|---------|-------------|------------------------| -| **signalement-ui.feature** | Interface de signalement mobile (formulaire, toast, découverte badges) | 14.1.1, 14.1.2, 14.1.3, 19.1.3 | -| **historique-signalements.feature** | Historique personnel des signalements de l'utilisateur | 14.1.3 | -| **badges-statistiques.feature** | Affichage des badges, statistiques et gamification | 19.1.4, 19.2, 19.3, 19.4 | -| **sanctions-appel.feature** | Interface de consultation des sanctions et processus d'appel | 14.3.1, 14.3.2, 14.3.3, 14.3.4 | - -**Couverture** : -- ✅ Formulaire de signalement avec 7 catégories -- ✅ Toast de confirmation et modal de découverte -- ✅ Historique des signalements avec statuts -- ✅ Badges Bronze/Argent/Or et progression visuelle -- ✅ Statistiques personnelles et taux de pertinence -- ✅ Notifications multi-canal des sanctions -- ✅ Formulaire d'appel structuré -- ✅ Dark mode et accessibilité complète - -### 🖥️ Features Admin (Dashboard Modérateur Web) - -**Localisation** : `features/admin/moderation/` - -| Feature | Description | Règles métier couvertes | -|---------|-------------|------------------------| -| **dashboard-moderateur.feature** | Dashboard principal de modération avec files d'attente | 14.2.2, 14.2.3, 14.4 | -| **outils-moderateur.feature** | Outils modérateur (player audio, transcription, historique créateur, actions) | 14.2.1, 14.4 | - -**Couverture** : -- ✅ Files d'attente par priorité (CRITIQUE/HAUTE/MOYENNE/BASSE) -- ✅ Statistiques temps réel et SLA -- ✅ Player audio Wavesurfer.js avec waveform -- ✅ Transcription synchronisée avec surlignage -- ✅ Analyse IA (Whisper + NLP) avec scores de confiance -- ✅ Historique créateur 360° (strikes, contenus, patterns) -- ✅ Actions rapides avec raccourcis clavier -- ✅ Logs d'audit conformes DSA - -### 🔌 Features API (Backend Go) - -**Localisation** : `features/api/moderation/` - -| Feature | Description | Règles métier couvertes | Statut | -|---------|-------------|------------------------|--------| -| **signalement.feature** | API de signalement de contenu | 14.1 | ✅ Existant - Complet | -| **traitement-signalements.feature** | Traitement IA et priorisation | 14.2 | ✅ Existant - Complet | -| **sanctions-notifications.feature** | Sanctions et notifications multi-canal | 14.3 | ✅ Existant - Complet | -| **moderation-preventive.feature** | Validation manuelle premiers contenus | 14.5 | ✅ Existant - Complet | -| **moderation-communautaire.feature** | Badges, scores de fiabilité, anti-abus | 19 | ✅ Existant - Complet | - -**Couverture** : -- ✅ 7 catégories de signalement + commentaire optionnel -- ✅ IA pré-filtre (Whisper large-v3 + distilbert + roberta) -- ✅ SLA progressif : <2h CRITIQUE, <24h HAUTE, <72h BASSE -- ✅ Priorisation automatique (formule IA + signalements cumulés + fiabilité) -- ✅ Notifications multi-canal (push + in-app + email) -- ✅ Processus d'appel avec délai 7 jours et SLA 72h -- ✅ 3 niveaux de badges (Bronze/Argent/Or) -- ✅ Score de fiabilité et utilisateurs de confiance -- ✅ Réduction Premium -50% pour badge Or -- ✅ Anti-abus : limite 10/24h, audit trimestriel, sanctions - -## Mapping Règles Métier → Features - -### Section 14.1 - Signalement - -| Règle | Feature API | Feature UI | -|-------|------------|-----------| -| 14.1.1 Catégories (7) | signalement.feature | signalement-ui.feature | -| 14.1.2 Commentaire optionnel | signalement.feature | signalement-ui.feature | -| 14.1.3 Confirmation + historique | signalement.feature | signalement-ui.feature, historique-signalements.feature | - -### Section 14.2 - Traitement - -| Règle | Feature API | Feature Admin | -|-------|------------|--------------| -| 14.2.1 IA pré-filtre (Whisper + NLP) | traitement-signalements.feature | outils-moderateur.feature | -| 14.2.2 Délais SLA | traitement-signalements.feature | dashboard-moderateur.feature | -| 14.2.3 Priorisation automatique | traitement-signalements.feature | dashboard-moderateur.feature | - -### Section 14.3 - Sanctions - -| Règle | Feature API | Feature UI | -|-------|------------|-----------| -| 14.3.1 Notification multi-canal | sanctions-notifications.feature | sanctions-appel.feature | -| 14.3.2 Détail sanction | sanctions-notifications.feature | sanctions-appel.feature | -| 14.3.3 Processus d'appel | sanctions-notifications.feature | sanctions-appel.feature | -| 14.3.4 Délai réponse appel (72h) | sanctions-notifications.feature | sanctions-appel.feature | - -### Section 14.4 - Outils Modérateurs - -| Règle | Feature Admin | -|-------|--------------| -| Dashboard modération | dashboard-moderateur.feature | -| Player audio + waveform | outils-moderateur.feature | -| Transcription + annotations | outils-moderateur.feature | -| Historique créateur 360° | outils-moderateur.feature | -| Actions rapides (A/R/E) | outils-moderateur.feature | -| Logs audit (DSA) | outils-moderateur.feature | - -### Section 14.5 - Modération Préventive - -| Règle | Feature API | -|-------|------------| -| Validation 3 premiers contenus | moderation-preventive.feature | -| Score de confiance dynamique | moderation-preventive.feature | -| Publicités validation manuelle | moderation-preventive.feature | - -### Section 19 - Modération Communautaire - -| Règle | Feature API | Feature UI | -|-------|------------|-----------| -| 19.1 Badges (Bronze/Argent/Or) | moderation-communautaire.feature | badges-statistiques.feature | -| 19.2 Score de fiabilité | moderation-communautaire.feature | - | -| 19.3 Utilisateur de confiance | moderation-communautaire.feature | badges-statistiques.feature | -| 19.4 Réduction Premium Or | moderation-communautaire.feature | badges-statistiques.feature | -| 19.5 Anti-abus | moderation-communautaire.feature | - | - -## Stack Technique Testée - -### Backend (Features API) -- **Framework tests** : Godog (Gherkin pour Go) -- **Localisation step definitions** : `backend/tests/bdd/moderation/` -- **Technologies testées** : - - API Go + Fiber (endpoints REST) - - PostgreSQL (stockage signalements, sanctions, badges) - - Redis (cache, files d'attente, priorisation) - - Whisper large-v3 (transcription audio) - - distilbert-base-uncased (analyse sentiment) - - facebook/roberta-hate-speech (détection haine) - - Email (Brevo/Resend) - - Push notifications (APNS/FCM) - -### Frontend Mobile (Features UI) -- **Framework tests** : flutter_gherkin + integration_test -- **Localisation step definitions** : `mobile/tests/bdd/moderation/` -- **Technologies testées** : - - Flutter (UI mobile iOS/Android) - - Widgets personnalisés (formulaires, badges, statistiques) - - Animations (confettis, level up, toast) - - Dark mode et accessibilité (lecteur d'écran) - - Navigation et routing - - Gestion d'état (Provider/Riverpod) - -### Frontend Admin (Features Admin) -- **Framework tests** : Cucumber.js + Playwright -- **Localisation step definitions** : `admin-dashboard/tests/e2e/moderation/` (à créer) -- **Technologies testées** : - - React + TypeScript - - TanStack Table (tableau signalements) - - Wavesurfer.js (player audio + waveform) - - WebSocket (temps réel) - - Raccourcis clavier - -## Statistiques - -### Couverture des Règles Métier - -| Section | Scénarios | Règles couvertes | Statut | -|---------|-----------|------------------|--------| -| 14.1 Signalement | 25 | 100% | ✅ | -| 14.2 Traitement | 30 | 100% | ✅ | -| 14.3 Sanctions | 35 | 100% | ✅ | -| 14.4 Outils | 40 | 100% | ✅ Nouveau | -| 14.5 Préventive | 20 | 100% | ✅ | -| 19 Communautaire | 40 | 100% | ✅ | -| **Total** | **190** | **100%** | ✅ | - -### Répartition Features - -| Type | Nombre | Scénarios totaux | -|------|--------|------------------| -| Features API (Backend) | 5 | ~90 | -| Features UI (Mobile) | 4 | ~60 | -| Features Admin (Dashboard) | 2 | ~40 | -| **Total** | **11** | **~190** | - -## Conformité - -### Digital Services Act (DSA) -- ✅ Transparence : raison détaillée + extrait + transcription -- ✅ Délais : SLA 2h/24h/72h documentés et testés -- ✅ Recours : processus d'appel 7 jours + réponse 72h -- ✅ Traçabilité : logs audit complets avec conservation 3 ans - -### RGPD -- ✅ Anonymat signaleur vis-à-vis du créateur -- ✅ Anonymisation des logs après 3 ans -- ✅ Suppression données personnelles à la demande -- ✅ Consentement notifications - -### Accessibilité (WCAG AA) -- ✅ Contraste couleurs (dark mode testé) -- ✅ Labels lecteur d'écran -- ✅ Navigation clavier -- ✅ Tailles de police adaptatives - -## Coûts - -| Composant | Technologie | Coût MVP | Coût Scale | -|-----------|-------------|----------|------------| -| IA transcription | Whisper (self-hosted) | 0€ (CPU) | 50-200€/mois (GPU) | -| IA analyse | distilbert + roberta | 0€ | 0€ | -| Notifications email | Brevo/Resend | ~0.001€/email | ~10-50€/mois | -| Notifications push | APNS/FCM | 0€ | 0€ | -| Dashboard admin | React + TanStack | 0€ | 0€ | -| Badges communautaires | Backend Go | 0€ | 0-200€/mois (réductions Premium) | -| **Total** | - | **0-50€/mois** | **60-450€/mois** | - -**ROI** : Positif dès 2-3 utilisateurs Badge Or actifs (économie modération > coût réductions Premium) - -## Prochaines Étapes - -1. ✅ ~~Créer features UI modération mobile~~ -2. ✅ ~~Créer features dashboard modérateur~~ -3. ⏳ Implémenter step definitions backend (Godog) -4. ⏳ Implémenter step definitions mobile (flutter_gherkin) -5. ⏳ Créer dashboard admin React + implémenter step definitions (Cucumber.js) -6. ⏳ Intégrer dans CI/CD (make test-bdd) - -## Commandes de Test - -```bash -# Tous les tests BDD -make test-bdd - -# Tests modération backend uniquement -cd backend -godog run ../features/api/moderation/ - -# Tests modération mobile uniquement -cd mobile -flutter test integration_test/moderation/ - -# Tests dashboard admin (à venir) -cd admin-dashboard -npm run test:e2e -``` - -## Documentation Liée - -- [Règles métier - Modération Flows](domains/moderation/rules/moderation-flows.md) -- [Règles métier - Modération Communautaire](domains/moderation/rules/moderation-communautaire.md) -- [ADR-023 - Architecture Modération](adr/023-architecture-moderation.md) -- [ADR-013 - Stratégie Tests](adr/013-strategie-tests.md) - ---- - -**Dernière mise à jour** : 2026-02-02 -**Statut** : ✅ Features complètes - Implémentation en cours diff --git a/docs/interfaces/README.md b/docs/interfaces/README.md deleted file mode 100644 index 7e551db..0000000 --- a/docs/interfaces/README.md +++ /dev/null @@ -1,58 +0,0 @@ -# Documentation des Interfaces - -Cette section documente les interfaces utilisateur de RoadWave (mobile et web). - -## Organisation - -### Mobile (Flutter) -L'application mobile est l'interface principale pour les utilisateurs finaux (conducteurs, piétons, touristes). - -- **[Navigation & Architecture](mobile/navigation.md)** : Structure de navigation, routing -- **Écran d'accueil** : Feed de recommandations géolocalisées -- **Lecteur audio** : Player HLS, contrôles, playlists -- **Carte & découverte** : Vue carte, exploration géographique -- **Profil & réglages** : Jauges d'intérêt, paramètres - -### Web (Créateurs) -L'interface web est destinée aux créateurs de contenu et aux annonceurs. - -- **Dashboard** : Vue d'ensemble, statistiques -- **Upload de contenu** : Import audio, métadonnées, géolocalisation -- **Statistiques** : Analytics, revenus - -## Conventions de documentation - -### Captures d'écran -Placez les images dans `docs/interfaces/assets/` et référencez-les ainsi : - -```markdown -![Description](assets/mobile/home-screen.png){ width="300" } -``` - -### Diagrammes de flux -Utilisez Mermaid pour les parcours utilisateur : - -```mermaid -graph LR - A[Ouverture app] --> B{GPS actif?} - B -->|Oui| C[Chargement recommandations] - B -->|Non| D[Demande permission] - D --> C -``` - -### Onglets multi-plateformes -Pour montrer des variations iOS/Android : - -=== "iOS" - Comportement spécifique iOS - -=== "Android" - Comportement spécifique Android - -## Principes de design - -- **Mobile-first** : L'app mobile est l'expérience principale -- **Géolocalisation centrale** : L'UI doit toujours contextualiser par rapport à la position -- **Audio en arrière-plan** : Player persistant, mini-player -- **Mode sombre** : Support obligatoire (conduite de nuit) -- **Accessibilité** : WCAG 2.1 AA minimum diff --git a/docs/interfaces/assets/mobile/.gitkeep b/docs/interfaces/assets/mobile/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/docs/interfaces/assets/web/.gitkeep b/docs/interfaces/assets/web/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/docs/interfaces/mobile/navigation.md b/docs/interfaces/mobile/navigation.md deleted file mode 100644 index 93561a0..0000000 --- a/docs/interfaces/mobile/navigation.md +++ /dev/null @@ -1,208 +0,0 @@ -# Navigation & Architecture Mobile - -## Architecture de navigation - -L'application mobile utilise une navigation par onglets (Bottom Navigation Bar) avec 4 sections principales. - -```mermaid -graph TD - A[App Shell] --> B[🏠 Accueil] - A --> C[🗺️ Carte] - A --> D[🎵 Bibliothèque] - A --> E[👤 Profil] - - B --> B1[Feed Recommandations] - B --> B2[Lecteur Audio] - - C --> C1[Vue Carte] - C --> C2[Détail Point] - - D --> D1[Mes Playlists] - D --> D2[Contenus Sauvegardés] - D --> D3[Historique] - - E --> E1[Jauges Intérêt] - E --> E2[Paramètres] - E --> E3[Abonnements] -``` - -## Bottom Navigation Bar - -### Onglet 1 : Accueil 🏠 -Point d'entrée principal après le lancement de l'app. - -**Fonctionnalités** : -- Feed de recommandations basé sur la géolocalisation + intérêts -- Rafraîchissement pull-to-refresh -- Lecture directe depuis le feed - -**Navigation vers** : -- Détail d'un contenu (push) -- Lecteur plein écran (modal) -- Profil d'un créateur (push) - -### Onglet 2 : Carte 🗺️ -Exploration visuelle des contenus par géolocalisation. - -**Fonctionnalités** : -- Carte interactive (MapLibre GL) -- Markers pour contenus à proximité -- Clusters pour zones denses -- Recherche par adresse - -**Navigation vers** : -- Détail d'un point (bottom sheet) -- Lecteur audio (modal persistant) - -### Onglet 3 : Bibliothèque 🎵 -Accès aux contenus sauvegardés, historique, playlists. - -**Fonctionnalités** : -- Playlists personnelles -- Contenus favoris -- Historique d'écoute -- Téléchargements offline - -### Onglet 4 : Profil 👤 -Gestion du compte, préférences, jauges d'intérêt. - -**Fonctionnalités** : -- Visualisation/édition jauges d'intérêt -- Paramètres de l'app -- Gestion abonnement Premium -- Déconnexion - -## Lecteur Audio (Modal persistant) - -Le lecteur est un composant modal qui persiste lors de la navigation entre onglets. - -```mermaid -stateDiagram-v2 - [*] --> Collapsed: Lecture démarre - Collapsed --> Expanded: Tap sur mini-player - Expanded --> Collapsed: Swipe down - Collapsed --> [*]: Stop audio - - Expanded --> Queue: Tap "À suivre" - Queue --> Expanded: Retour -``` - -=== "État Collapsed (Mini-player)" - - Hauteur : 60dp - - Position : Bottom (au-dessus de la Bottom Nav Bar) - - Affiche : Titre, artiste, play/pause, skip - - Interaction : Tap pour expand - -=== "État Expanded (Lecteur plein écran)" - - Plein écran modal - - Cover art grande taille - - Contrôles avancés (repeat, shuffle, queue) - - Scrubber timeline - - Boutons : like, share, download, add to playlist - -## Routing Flutter - -### Configuration - -Utilisation de **go_router** (voir [ADR-020](../../adr/020-librairies-flutter.md)). - -```dart -// Exemple simplifié -GoRouter( - routes: [ - ShellRoute( - builder: (context, state, child) => AppShell(child: child), - routes: [ - GoRoute(path: '/home', builder: (context, state) => HomeScreen()), - GoRoute(path: '/map', builder: (context, state) => MapScreen()), - GoRoute(path: '/library', builder: (context, state) => LibraryScreen()), - GoRoute(path: '/profile', builder: (context, state) => ProfileScreen()), - ], - ), - GoRoute( - path: '/content/:id', - builder: (context, state) => ContentDetailScreen( - contentId: state.pathParameters['id']!, - ), - ), - ], -); -``` - -### Deep Links - -L'app supporte les deep links pour : -- `roadwave://content/{id}` : Ouvrir un contenu spécifique -- `roadwave://map?lat={lat}&lon={lon}` : Ouvrir la carte à une position -- `roadwave://profile` : Ouvrir le profil - -## Gestion d'état - -- **Provider** pour l'état global (user, player, location) -- **BLoC** pour les features complexes (recommendation, map) -- **Riverpod** pour l'injection de dépendances - -Voir [ADR-020](../../adr/020-librairies-flutter.md) pour les détails. - -## Permissions système - -La navigation gère les demandes de permissions de manière contextuelle : - -1. **Géolocalisation** : Demandée au premier lancement, avant d'afficher l'accueil -2. **Notifications** : Demandée après 3 sessions utilisateur (opt-in soft) -3. **Stockage** : Demandée lors du premier téléchargement offline - -Voir [mobile/permissions-strategy.md](../../mobile/permissions-strategy.md) pour la stratégie complète. - -## Transitions et animations - -### Transitions entre onglets -- Aucune animation (changement instantané) -- Préservation du scroll state sur chaque onglet - -### Navigation push/pop -- iOS : Slide transition (standard Cupertino) -- Android : Fade + Slide transition (Material Design) - -### Mini-player expand/collapse -- Spring animation (bounce léger) -- Durée : 300ms -- Curve : `Curves.easeInOutCubic` - -## Gestion du back button (Android) - -```mermaid -graph TD - A[Back pressed] --> B{Lecteur expanded?} - B -->|Oui| C[Collapse lecteur] - B -->|Non| D{Sur onglet Accueil?} - D -->|Non| E[Retour à Accueil] - D -->|Oui| F{Audio en cours?} - F -->|Oui| G[Dialog: Quitter?] - F -->|Non| H[Quitter app] - G -->|Confirme| H - G -->|Annule| I[Rester] -``` - -## Accessibilité - -- **Screen readers** : Labels sémantiques sur tous les boutons -- **Navigation clavier** : Support complet (pour tablettes avec clavier) -- **Contraste** : WCAG 2.1 AA minimum (4.5:1 pour texte) -- **Taille des touch targets** : 48dp minimum - -## Mode sombre - -Support obligatoire du mode sombre (conduite de nuit). - -=== "Mode Clair" - - Fond : White / Light Gray (#F5F5F5) - - Texte : Dark Gray (#212121) - - Accent : Indigo (#3F51B5) - -=== "Mode Sombre" - - Fond : Dark (#121212) - - Texte : White (#FFFFFF) - - Accent : Indigo clair (#7986CB) - -Détection automatique via `MediaQuery.platformBrightness` ou choix manuel dans les paramètres. diff --git a/mkdocs.yml b/mkdocs.yml index 99f592b..d6b384a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -25,7 +25,6 @@ theme: features: - navigation.tabs - navigation.sections - - navigation.expand - navigation.top - navigation.tracking - search.suggest @@ -60,40 +59,40 @@ markdown_extensions: nav: - Accueil: README.md - - Architecture Technique: TECHNICAL.md - - Architecture Decision Records (ADR): - - 'Vue d''ensemble': adr/README.md - - 'Core Architecture': - - 'ADR-001: Langage Backend': adr/001-langage-backend.md - - 'ADR-010: Architecture Backend': adr/010-architecture-backend.md - - 'ADR-011: ORM et Accès Données': adr/011-orm-acces-donnees.md - - 'ADR-012: Frontend Mobile': adr/012-frontend-mobile.md - - 'ADR-014: Organisation en Monorepo': adr/014-organisation-monorepo.md - - 'Data & Infrastructure': - - 'ADR-005: Base de données': adr/005-base-de-donnees.md - - 'ADR-021: Solution de Cache': adr/021-solution-cache.md - - 'ADR-015: Hébergement': adr/015-hebergement.md - - 'ADR-019: Géolocalisation par IP': adr/019-geolocalisation-ip.md - - 'Streaming & Content': - - 'ADR-002: Protocole Streaming': adr/002-protocole-streaming.md - - 'ADR-003: Codec Audio': adr/003-codec-audio.md - - 'ADR-004: CDN': adr/004-cdn.md - - 'Security & Auth': - - 'ADR-006: Chiffrement': adr/006-chiffrement.md - - 'ADR-008: Authentification': adr/008-authentification.md - - 'ADR-025: Sécurité & Secrets': adr/025-securite-secrets.md - - 'Testing & Quality': - - 'ADR-007: Tests BDD': adr/007-tests-bdd.md - - 'ADR-013: Stratégie Tests': adr/013-strategie-tests.md - - 'ADR-022: CI/CD Monorepo': adr/022-strategie-cicd-monorepo.md - - 'Features & Operations': - - 'ADR-009: Solution Paiement': adr/009-solution-paiement.md - - 'ADR-016: Service Emailing': adr/016-service-emailing.md - - 'ADR-017: Notifications Géolocalisées': adr/017-notifications-geolocalisees.md - - 'ADR-018: Librairies Go': adr/018-librairies-go.md - - 'ADR-020: Librairies Flutter': adr/020-librairies-flutter.md - - 'ADR-023: Architecture Modération': adr/023-architecture-moderation.md - - 'ADR-024: Monitoring & Observabilité': adr/024-monitoring-observabilite.md + - Architecture: + - 'Vue d''ensemble': TECHNICAL.md + - 'Decision Records (ADR)': + - 'Core Architecture': + - 'ADR-001: Langage Backend': adr/001-langage-backend.md + - 'ADR-010: Architecture Backend': adr/010-architecture-backend.md + - 'ADR-011: ORM et Accès Données': adr/011-orm-acces-donnees.md + - 'ADR-012: Frontend Mobile': adr/012-frontend-mobile.md + - 'ADR-014: Organisation en Monorepo': adr/014-organisation-monorepo.md + - 'Data & Infrastructure': + - 'ADR-005: Base de données': adr/005-base-de-donnees.md + - 'ADR-021: Solution de Cache': adr/021-solution-cache.md + - 'ADR-015: Hébergement': adr/015-hebergement.md + - 'ADR-019: Géolocalisation par IP': adr/019-geolocalisation-ip.md + - 'Streaming & Content': + - 'ADR-002: Protocole Streaming': adr/002-protocole-streaming.md + - 'ADR-003: Codec Audio': adr/003-codec-audio.md + - 'ADR-004: CDN': adr/004-cdn.md + - 'Security & Auth': + - 'ADR-006: Chiffrement': adr/006-chiffrement.md + - 'ADR-008: Authentification': adr/008-authentification.md + - 'ADR-025: Sécurité & Secrets': adr/025-securite-secrets.md + - 'Testing & Quality': + - 'ADR-007: Tests BDD': adr/007-tests-bdd.md + - 'ADR-013: Stratégie Tests': adr/013-strategie-tests.md + - 'ADR-022: CI/CD Monorepo': adr/022-strategie-cicd-monorepo.md + - 'Features & Operations': + - 'ADR-009: Solution Paiement': adr/009-solution-paiement.md + - 'ADR-016: Service Emailing': adr/016-service-emailing.md + - 'ADR-017: Notifications Géolocalisées': adr/017-notifications-geolocalisees.md + - 'ADR-018: Librairies Go': adr/018-librairies-go.md + - 'ADR-020: Librairies Flutter': adr/020-librairies-flutter.md + - 'ADR-023: Architecture Modération': adr/023-architecture-moderation.md + - 'ADR-024: Monitoring & Observabilité': adr/024-monitoring-observabilite.md - Domaines DDD: - 'Context Map': domains/README.md - 'Core Domain': @@ -104,6 +103,32 @@ nav: - Gestion Erreurs: domains/_shared/rules/gestion-erreurs.md - 'Annexe Post-MVP': domains/_shared/rules/ANNEXE-POST-MVP.md - Features BDD: + - 'Authentication': + - Appareil de confiance et 2FA: generated/bdd/_shared/features/authentication/appareil-confiance-2fa.md + - Classification par âge: generated/bdd/_shared/features/authentication/classification-age.md + - Connexion: generated/bdd/_shared/features/authentication/connexion.md + - Gestion de compte: generated/bdd/_shared/features/authentication/gestion-compte.md + - Inscription: generated/bdd/_shared/features/authentication/inscription.md + - Limite de tentatives de connexion: generated/bdd/_shared/features/authentication/limite-tentatives-connexion.md + - Sessions multi-devices: generated/bdd/_shared/features/authentication/multi-device-sessions.md + - Récupération de compte: generated/bdd/_shared/features/authentication/recuperation-compte.md + - Récupération de mot de passe avancée: generated/bdd/_shared/features/authentication/recuperation-mot-passe-avancee.md + - Sessions et tokens: generated/bdd/_shared/features/authentication/sessions-tokens.md + - Authentification à deux facteurs: generated/bdd/_shared/features/authentication/two-factor-authentication.md + - Validation mot de passe: generated/bdd/_shared/features/authentication/validation-mot-passe.md + - Vérification email: generated/bdd/_shared/features/authentication/verification-email.md + - 'Profil': + - Badge vérifié: generated/bdd/_shared/features/profil/badge-verifie.md + - Profil créateur: generated/bdd/_shared/features/profil/profil-createur.md + - Statistiques arrondies: generated/bdd/_shared/features/profil/statistiques-arrondies.md + - 'Partage': + - Partage de contenu: generated/bdd/_shared/features/partage/partage-contenu.md + - Partage de contenu Premium: generated/bdd/_shared/features/partage/partage-contenu-premium.md + - 'Error Handling': + - Aucun contenu disponible: generated/bdd/_shared/features/error-handling/aucun-contenu-disponible.md + - Contenu supprimé pendant écoute: generated/bdd/_shared/features/error-handling/contenu-supprime-pendant-ecoute.md + - Géolocalisation désactivée: generated/bdd/_shared/features/error-handling/geolocalisation-desactivee.md + - Perte réseau: generated/bdd/_shared/features/error-handling/perte-reseau.md - 'RGPD & Conformité': - Consentement: generated/bdd/_shared/features/rgpd-compliance/consentement.md - Anonymisation GPS: generated/bdd/_shared/features/rgpd-compliance/anonymisation-gps.md @@ -369,18 +394,8 @@ nav: - 'Charte Créateur': legal/charte-createur.md - 'Mentions Légales': legal/mentions-legales.md - 'Politique de Confidentialité': legal/politique-confidentialite.md - - Interfaces: - - Vue d'ensemble: interfaces/README.md - - Mobile: - - Navigation & Architecture: interfaces/mobile/navigation.md - - Mobile: - - 'Stratégie Permissions': mobile/permissions-strategy.md - - 'Validation TestFlight': mobile/testflight-validation-plan.md - Conformité & Compliance: - 'Soumission aux Stores': compliance/stores-submission.md - - Architecture & Techniques: - - Séquences: - - 'Cache Géospatial': architecture/sequences/cache-geospatial.md extra: social: diff --git a/scripts/generate-bdd-docs.py b/scripts/generate-bdd-docs.py index bef0ca6..6ed40f0 100644 --- a/scripts/generate-bdd-docs.py +++ b/scripts/generate-bdd-docs.py @@ -199,7 +199,8 @@ def format_step(step: Step, indent: str = "") -> str: if step.table: result += "\n\n" - result += format_table_markdown(step.table, indent + " ") + # Pas d'indentation pour les tableaux (sinon ils deviennent des blocs de code) + result += format_table_markdown(step.table, "") result += "\n" return result