docs(shared): ajouter documentation complète entités, états et séquences

- Entités: 7 nouveaux schémas (sessions, devices, consents, location-history, interest-gauges, reports, exports) - États: 5 diagrammes lifecycles (compte, contenu, session, signalement, export) - Séquences: 6 flows (auth, refresh token, modération, signalement, export, suppression) - Renommage: modele-global.md → entities-overview.md - MkDocs: organisation hiérarchique par catégories Format concis: diagrammes Mermaid + règles essentielles uniquement
2026-02-07 21:38:02 +01:00
parent cf7a46be27
commit e63603551d
22 changed files with 1047 additions and 97 deletions
--- a/docs/domains/_shared/entities/consents.md
+++ b/docs/domains/_shared/entities/consents.md
@@ -0,0 +1,40 @@
+# User Consents
+
+📖 Consentements RGPD avec historique et versioning
+
+## Diagramme
+
+```mermaid
+erDiagram
+    USERS ||--o{ USER_CONSENTS : "donne"
+
+    USER_CONSENTS {
+        uuid id PK
+        uuid user_id FK
+        string consent_type
+        string consent_version
+        boolean accepted
+        timestamp given_at
+        inet ip_address
+        string user_agent
+    }
+```
+
+## Légende
+
+**Types de consentement** :
+- `geolocation_precise` : Géolocalisation GPS précise (obligatoire pour contenu hyperlocal)
+- `analytics` : Analytics Matomo (optionnel)
+- `push_notifications` : Notifications push (optionnel)
+- `cookies_analytics` : Cookies analytiques (optionnel)
+
+**Versioning** :
+- Chaque changement de CGU/politique = nouvelle version
+- Historique complet conservé (preuve légale)
+- Format version : `v1.0`, `v2.0`, etc.
+
+**Conformité RGPD** :
+- Granularité : fonctionnel / analytique / marketing
+- Consentement libre et éclairé
+- Révocable à tout moment
+- Historique = preuve en cas de contrôle CNIL
--- a/docs/domains/_shared/entities/devices.md
+++ b/docs/domains/_shared/entities/devices.md
@@ -0,0 +1,45 @@
+# Devices
+
+📖 Appareils de confiance et gestion multi-device
+
+## Diagramme
+
+```mermaid
+erDiagram
+    USERS ||--o{ DEVICES : "possède"
+    DEVICES ||--o{ SESSIONS : "a"
+
+    DEVICES {
+        uuid id PK
+        uuid user_id FK
+        string device_name
+        string os
+        string browser
+        string device_type
+        boolean is_trusted
+        timestamp trusted_until
+        timestamp first_seen_at
+        timestamp last_seen_at
+        inet last_ip
+        string last_city
+        string last_country_code
+    }
+```
+
+## Légende
+
+**Types d'appareil** :
+- `mobile` : Smartphone Android/iOS
+- `tablet` : Tablette
+- `desktop` : Ordinateur
+- `car` : Système embarqué (CarPlay/Android Auto)
+
+**Appareil de confiance** :
+- Option "Ne plus demander sur cet appareil" → bypass 2FA pendant **30 jours**
+- Révocable depuis paramètres compte
+- Liste des appareils de confiance visible
+
+**Sécurité** :
+- Détection automatique nouveau device → notification push + email
+- Localisation suspecte (pays différent) → alerte
+- Révocation individuelle ou globale possible
--- a/docs/domains/_shared/entities/entities-overview.md
+++ b/docs/domains/_shared/entities/entities-overview.md
@@ -0,0 +1,216 @@
+# Modèle de données - Entités globales
+
+📖 Entités de base utilisées dans tous les domaines métier
+
+## Diagramme
+
+```mermaid
+erDiagram
+    USERS ||--o{ CONTENTS : "crée"
+    USERS ||--o{ SUBSCRIPTIONS : "s'abonne à"
+    USERS ||--o{ LISTENING_HISTORY : "écoute"
+    USERS ||--o{ SESSIONS : "possède"
+    USERS ||--o{ DEVICES : "possède"
+    USERS ||--o{ USER_CONSENTS : "donne"
+    USERS ||--o{ LOCATION_HISTORY : "génère"
+    USERS ||--o{ INTEREST_GAUGES : "possède"
+    USERS ||--o{ REPORTS : "signale"
+    USERS ||--o{ DATA_EXPORTS : "demande"
+
+    CONTENTS ||--o{ LISTENING_HISTORY : "écouté"
+    CONTENTS }o--|| USERS : "créé par"
+    CONTENTS ||--o{ REPORTS : "reçoit"
+
+    DEVICES ||--o{ SESSIONS : "a"
+
+    USERS {
+        uuid id PK
+        string email UK
+        string pseudo UK
+        date birthdate
+        string role
+        string account_status
+        timestamp created_at
+        timestamp last_login_at
+        boolean email_verified
+        boolean kyc_verified
+        string phone_number
+        int trust_score
+        timestamp deletion_requested_at
+        timestamp inactivity_notified_at
+    }
+
+    CONTENTS {
+        uuid id PK
+        uuid creator_id FK
+        string title
+        string audio_url
+        string status
+        string moderation_status
+        string age_rating
+        string geo_type
+        point geo_location
+        string[] tags
+        int duration_seconds
+        timestamp published_at
+        int reports_count
+        text moderation_notes
+    }
+
+    SUBSCRIPTIONS {
+        uuid id PK
+        uuid subscriber_id FK
+        uuid creator_id FK
+        timestamp subscribed_at
+    }
+
+    LISTENING_HISTORY {
+        uuid id PK
+        uuid user_id FK
+        uuid content_id FK
+        uuid creator_id FK
+        boolean is_subscribed
+        decimal completion_rate
+        int last_position_seconds
+        string source
+        boolean auto_like
+        timestamp listened_at
+    }
+
+    SESSIONS {
+        uuid id PK
+        uuid user_id FK
+        uuid device_id FK
+        string access_token_hash
+        string refresh_token_hash
+        timestamp access_token_expires_at
+        timestamp refresh_token_expires_at
+        inet ip_address
+        string user_agent
+        string city
+        string country_code
+        timestamp created_at
+        timestamp last_activity_at
+        timestamp revoked_at
+    }
+
+    DEVICES {
+        uuid id PK
+        uuid user_id FK
+        string device_name
+        string os
+        string browser
+        string device_type
+        boolean is_trusted
+        timestamp trusted_until
+        timestamp first_seen_at
+        timestamp last_seen_at
+    }
+
+    USER_CONSENTS {
+        uuid id PK
+        uuid user_id FK
+        string consent_type
+        string consent_version
+        boolean accepted
+        timestamp given_at
+    }
+
+    LOCATION_HISTORY {
+        uuid id PK
+        uuid user_id FK
+        geography location
+        string geohash
+        boolean anonymized
+        string context
+        timestamp created_at
+        timestamp anonymized_at
+    }
+
+    INTEREST_GAUGES {
+        uuid id PK
+        uuid user_id FK
+        string category
+        decimal score
+        timestamp last_updated
+        int interactions_count
+    }
+
+    REPORTS {
+        uuid id PK
+        uuid content_id FK
+        uuid reporter_id FK
+        uuid moderator_id FK
+        string category
+        string status
+        text comment
+        timestamp reported_at
+        timestamp reviewed_at
+        text moderator_notes
+        string action_taken
+    }
+
+    DATA_EXPORTS {
+        uuid id PK
+        uuid user_id FK
+        string status
+        string export_url
+        bigint size_bytes
+        string format
+        timestamp requested_at
+        timestamp generated_at
+        timestamp expires_at
+    }
+```
+
+## Légende
+
+**Entités de base** :
+
+- **USERS** : Utilisateurs plateforme
+  - Rôles : `listener`, `creator`, `moderator`, `admin`
+  - Account status : `active`, `suspended`, `grace_period`, `deleted`
+  - Trust score : 0-100 (anti-spam, accès fonctionnalités avancées)
+
+- **CONTENTS** : Contenus audio
+  - Status : `draft`, `pending_review`, `published`, `moderated`, `deleted`
+  - Moderation status : `pending_review`, `approved`, `rejected`
+  - Geo-type : `geo_ancre` (70% geo), `geo_contextuel` (50% geo), `geo_neutre` (20% geo)
+  - Age rating : `all`, `13+`, `16+`, `18+`
+
+- **SUBSCRIPTIONS** : Abonnements créateurs
+  - Utilisé pour filtrer recommandations et calculer engagement
+
+- **LISTENING_HISTORY** : Historique écoutes
+  - Source : `recommendation`, `search`, `direct_link`, `profile`, `history`, `live_notification`, `audio_guide`
+  - Utilisé pour scoring recommandation et statistiques créateur
+
+**Entités authentification & sécurité** :
+
+- **SESSIONS** : Sessions utilisateur OAuth2/OIDC ([détails](sessions.md))
+  - Access token : 15 min, Refresh token : 30 jours (rotatif)
+
+- **DEVICES** : Appareils de confiance ([détails](devices.md))
+  - Types : `mobile`, `tablet`, `desktop`, `car`
+  - Appareils de confiance : bypass 2FA pendant 30 jours
+
+**Entités RGPD & conformité** :
+
+- **USER_CONSENTS** : Consentements RGPD avec versioning ([détails](consents.md))
+  - Types : `geolocation_precise`, `analytics`, `push_notifications`
+
+- **LOCATION_HISTORY** : Historique GPS avec anonymisation 24h ([détails](location-history.md))
+  - Geohash précision 5 (~5km²) après 24h
+
+- **DATA_EXPORTS** : Exports de données utilisateur ([détails](exports.md))
+  - Portabilité RGPD Article 20, délai 48h max
+
+**Entités recommandation & modération** :
+
+- **INTEREST_GAUGES** : Jauges de centres d'intérêt ([détails](interest-gauges.md))
+  - Score 0-100 par catégorie (automobile, travel, music, etc.)
+  - Algorithme : 70% géo + 30% intérêts
+
+- **REPORTS** : Signalements de contenu ([détails](reports.md))
+  - Catégories : `spam`, `hate_speech`, `violence`, `sexual_content`, `misinformation`, etc.
+  - Workflow modération avec priorisation
--- a/docs/domains/_shared/entities/exports.md
+++ b/docs/domains/_shared/entities/exports.md
@@ -0,0 +1,52 @@
+# Data Exports
+
+📖 Exports de données utilisateur (portabilité RGPD Article 20)
+
+## Diagramme
+
+```mermaid
+erDiagram
+    USERS ||--o{ DATA_EXPORTS : "demande"
+
+    DATA_EXPORTS {
+        uuid id PK
+        uuid user_id FK
+        string status
+        string export_url
+        bigint size_bytes
+        string format
+        timestamp requested_at
+        timestamp generated_at
+        timestamp expires_at
+        timestamp downloaded_at
+    }
+```
+
+## Légende
+
+**Formats d'export** :
+- `json` : Machine-readable (données brutes)
+- `html` : Human-readable (page web stylée)
+- `zip` : Archive complète (JSON + HTML + audio files)
+
+**Contenu de l'export** :
+- Profil utilisateur (email, pseudo, date inscription, bio)
+- Historique d'écoute (titres, dates, durées)
+- Contenus créés (audio + métadonnées)
+- Abonnements et likes
+- Centres d'intérêt (jauges)
+- Historique consentements RGPD
+
+**Statuts** :
+- `pending` : Demande en file d'attente
+- `generating` : Génération en cours (worker background)
+- `ready` : Export disponible au téléchargement
+- `downloaded` : Export téléchargé par l'utilisateur
+- `expired` : Export expiré (supprimé automatiquement)
+
+**Règles** :
+- Génération asynchrone (worker background)
+- Délai max : **48h** (conformité RGPD)
+- Conservation : **7 jours** après génération
+- Limite : **1 export/mois** (anti-abus)
+- Notification par email avec lien de téléchargement
--- a/docs/domains/_shared/entities/interest-gauges.md
+++ b/docs/domains/_shared/entities/interest-gauges.md
@@ -0,0 +1,45 @@
+# Interest Gauges
+
+📖 Jauges de centres d'intérêt dynamiques pour recommandation personnalisée
+
+## Diagramme
+
+```mermaid
+erDiagram
+    USERS ||--o{ INTEREST_GAUGES : "possède"
+
+    INTEREST_GAUGES {
+        uuid id PK
+        uuid user_id FK
+        string category
+        decimal score
+        timestamp last_updated
+        int interactions_count
+    }
+```
+
+## Légende
+
+**Catégories** :
+- `automobile` : Voitures, mécanique, course automobile
+- `travel` : Voyages, tourisme, découverte
+- `music` : Musique, concerts, artistes
+- `news` : Actualités, politique, économie
+- `sport` : Sports, événements sportifs
+- `culture` : Cinéma, livres, expositions
+- `food` : Gastronomie, restaurants, recettes
+- `tech` : Technologie, innovation, gadgets
+- `history` : Histoire, patrimoine, musées
+- `nature` : Nature, randonnée, écologie
+
+**Score** :
+- Échelle : **0-100**
+- Augmentation : +2% par like, +5% par abonnement créateur
+- Diminution : -1% par skip rapide (<30s), -5% par signalement
+- Calcul combiné : Distance GPS + matching intérêts
+
+**Algorithme recommandation** :
+- **70% géolocalisation** : Proximité GPS
+- **30% centres d'intérêt** : Score jauges
+- Boost si créateur suivi : +0.3 au score final
+- Limite : 6 contenus/heure pour éviter spam
--- a/docs/domains/_shared/entities/location-history.md
+++ b/docs/domains/_shared/entities/location-history.md
@@ -0,0 +1,47 @@
+# Location History
+
+📖 Historique de géolocalisation avec anonymisation automatique
+
+## Diagramme
+
+```mermaid
+erDiagram
+    USERS ||--o{ LOCATION_HISTORY : "génère"
+
+    LOCATION_HISTORY {
+        uuid id PK
+        uuid user_id FK
+        geography location
+        string geohash
+        boolean anonymized
+        string context
+        float speed_kmh
+        float accuracy_meters
+        timestamp created_at
+        timestamp anonymized_at
+    }
+```
+
+## Légende
+
+**Anonymisation progressive** :
+- Données précises conservées **24h** (recommandation personnalisée)
+- Après 24h : conversion en **geohash précision 5** (~5km²)
+- Coordonnées originales supprimées définitivement
+- Job quotidien PostGIS automatique
+
+**Exceptions** :
+- Historique personnel visible (liste trajets) : conservation intégrale tant que compte actif
+- Analytics globales : uniquement geohash anonyme
+- Suppression complète si suppression du compte
+
+**Contexte** :
+- `listening` : Position pendant écoute de contenu
+- `search` : Position lors d'une recherche
+- `background` : Tracking en arrière-plan
+- `manual` : Position partagée manuellement
+
+**Conformité RGPD** :
+- Vraie anonymisation (CNIL compliant)
+- Permet analytics agrégées (heatmaps trafic)
+- PostGIS natif, 0€
--- a/docs/domains/_shared/entities/modele-global.md
+++ b/docs/domains/_shared/entities/modele-global.md
@@ -1,69 +0,0 @@
-# Modèle de données - Entités globales
-
-📖 Entités de base utilisées dans tous les domaines métier
-
-## Diagramme
-
-```mermaid
-erDiagram
-    USERS ||--o{ CONTENTS : "crée"
-    USERS ||--o{ SUBSCRIPTIONS : "s'abonne à"
-    USERS ||--o{ LISTENING_HISTORY : "écoute"
-
-    CONTENTS ||--o{ LISTENING_HISTORY : "écouté"
-    CONTENTS }o--|| USERS : "créé par"
-
-    USERS {
-        uuid id PK
-        string email UK
-        string pseudo UK
-        date birthdate
-        string role
-        timestamp created_at
-        boolean email_verified
-    }
-
-    CONTENTS {
-        uuid id PK
-        uuid creator_id FK
-        string title
-        string audio_url
-        string status
-        string age_rating
-        string geo_type
-        point geo_location
-        string[] tags
-        int duration_seconds
-        timestamp published_at
-        boolean is_moderated
-    }
-
-    SUBSCRIPTIONS {
-        uuid id PK
-        uuid subscriber_id FK
-        uuid creator_id FK
-        timestamp subscribed_at
-    }
-
-    LISTENING_HISTORY {
-        uuid id PK
-        uuid user_id FK
-        uuid content_id FK
-        uuid creator_id FK
-        boolean is_subscribed
-        decimal completion_rate
-        int last_position_seconds
-        string source
-        boolean auto_like
-        timestamp listened_at
-    }
-```
-
-## Légende
-
-**Entités de base** :
-
- **USERS** : Utilisateurs plateforme - Rôles : `listener`, `creator`, `moderator`, `admin`
- **CONTENTS** : Contenus audio - Status : `draft`, `pending_review`, `published`, `moderated`, `deleted` - Geo-type : `geo_ancre` (70% geo), `geo_contextuel` (50% geo), `geo_neutre` (20% geo) - Age rating : `all`, `13+`, `16+`, `18+`
- **SUBSCRIPTIONS** : Abonnements créateurs - Utilisé pour filtrer recommandations et calculer engagement
- **LISTENING_HISTORY** : Historique écoutes - Source : `recommendation`, `search`, `direct_link`, `profile`, `history`, `live_notification`, `audio_guide` - Utilisé pour scoring recommandation et statistiques créateur
--- a/docs/domains/_shared/entities/reports.md
+++ b/docs/domains/_shared/entities/reports.md
@@ -0,0 +1,60 @@
+# Reports
+
+📖 Signalements de contenu et workflow de modération
+
+## Diagramme
+
+```mermaid
+erDiagram
+    USERS ||--o{ REPORTS : "signale"
+    CONTENTS ||--o{ REPORTS : "reçoit"
+    USERS ||--o{ REPORTS : "modère"
+
+    REPORTS {
+        uuid id PK
+        uuid content_id FK
+        uuid reporter_id FK
+        uuid moderator_id FK
+        string category
+        string status
+        text comment
+        string evidence_url
+        timestamp reported_at
+        timestamp reviewed_at
+        text moderator_notes
+        string action_taken
+    }
+```
+
+## Légende
+
+**Catégories de signalement** :
+- `spam` : Contenu publicitaire non sollicité
+- `hate_speech` : Discours haineux, discrimination
+- `violence` : Violence explicite
+- `sexual_content` : Contenu sexuel inapproprié
+- `misinformation` : Désinformation, fake news
+- `copyright` : Violation de droits d'auteur
+- `wrong_age_rating` : Classification d'âge incorrecte
+- `other` : Autre raison (commentaire obligatoire)
+
+**Statuts** :
+- `pending` : En attente de revue
+- `under_review` : En cours d'examen par modérateur
+- `actioned` : Action prise (contenu retiré/édité)
+- `dismissed` : Signalement rejeté (contenu valide)
+- `duplicate` : Doublon d'un signalement existant
+
+**Actions possibles** :
+- `content_removed` : Contenu supprimé
+- `content_edited` : Métadonnées modifiées (âge, tags)
+- `warning_sent` : Avertissement au créateur
+- `strike_issued` : Strike ajouté au créateur
+- `account_suspended` : Compte créateur suspendu
+- `no_action` : Aucune action (signalement infondé)
+
+**Workflow modération** :
+- **3 premiers contenus** : Modération préalable obligatoire
+- **Après validation** : Modération a posteriori (signalements)
+- **Priorisation** : Nombre de signalements (>3 = urgent)
+- **Délai de traitement** : <48h pour signalements critiques
--- a/docs/domains/_shared/entities/sessions.md
+++ b/docs/domains/_shared/entities/sessions.md
@@ -0,0 +1,45 @@
+# Sessions
+
+📖 Gestion des sessions utilisateur et tokens d'authentification OAuth2/OIDC
+
+## Diagramme
+
+```mermaid
+erDiagram
+    USERS ||--o{ SESSIONS : "possède"
+    DEVICES ||--o{ SESSIONS : "associé"
+
+    SESSIONS {
+        uuid id PK
+        uuid user_id FK
+        uuid device_id FK
+        string access_token_hash
+        string refresh_token_hash
+        timestamp access_token_expires_at
+        timestamp refresh_token_expires_at
+        inet ip_address
+        string user_agent
+        string city
+        string country_code
+        timestamp created_at
+        timestamp last_activity_at
+        timestamp revoked_at
+    }
+```
+
+## Légende
+
+**Durées de vie** :
+- Access token : **15 minutes**
+- Refresh token : **30 jours** (rotatif)
+- Inactivité : Déconnexion automatique après **30 jours**
+
+**Sécurité** :
+- Tokens stockés en **SHA256** (jamais en clair)
+- Rotation automatique des refresh tokens
+- Détection replay attack
+
+**Multi-device** :
+- Sessions simultanées **illimitées**
+- Révocation individuelle ou globale possible
+- Alertes si connexion depuis nouveau device ou pays différent