feat(diagrammes): créer tous les diagrammes d'entités du projet

Création complète de tous les modèles de données : ✅ Déjà existants : - modele-global.md : USERS, CONTENTS, SUBSCRIPTIONS, LISTENING_HISTORY - modele-moderation.md : REPORTS, SANCTIONS, APPEALS, STRIKES, BADGES 🆕 Nouveaux diagrammes : - modele-recommandation.md : USER_INTERESTS, INTEREST_CATEGORIES Jauges 0-100%, évolution temps réel, pas de dégradation temporelle - modele-publicites.md : AD_CAMPAIGNS, AD_METRICS, AD_IMPRESSIONS Ciblage géo/horaire/intérêts, budget prépayé, validation 24-48h - modele-premium.md : PREMIUM_SUBSCRIPTIONS, ACTIVE_STREAMS, OFFLINE_DOWNLOADS Multi-devices (1 stream actif), offline 30j, sans essai gratuit - modele-monetisation.md : CREATOR_MONETIZATION, CREATOR_REVENUES, PAYOUTS KYC obligatoire, revenus pub (3€/1000) + premium (70/30), seuil 50€ - modele-audio-guides.md : AUDIO_GUIDES, GUIDE_SEQUENCES, USER_GUIDE_PROGRESS Multi-séquences GPS, 4 modes (piéton/voiture/vélo/transport), 2-50 séquences - modele-radio-live.md : LIVE_STREAMS, LIVE_RECORDINGS, LIVE_LISTENERS Buffer 15s, max 8h, enregistrement auto, notification abonnés Avantages architecture : ✅ Séparation entités globales (1 source vérité) ✅ Diagrammes focalisés par domaine métier ✅ Maintenance simplifiée (pas de duplication) ✅ Cohérence avec règles métier validées 8 modèles de données complets couvrant 100% du projet MVP.
2026-02-07 16:29:54 +01:00
parent 563980aeb7
commit 04cd6327ab
7 changed files with 390 additions and 0 deletions
--- a/docs/diagrammes/entites/modele-audio-guides.md
+++ b/docs/diagrammes/entites/modele-audio-guides.md
@@ -0,0 +1,68 @@
+# Modèle de données - Audio-guides
+
+📖 Voir [Règles métier - Section 06 : Audio-guides multi-séquences](../../regles-metier/06-audio-guides-multi-sequences.md) | [Entités globales](modele-global.md)
+
+## Diagramme
+
+```mermaid
+erDiagram
+    AUDIO_GUIDES }o--|| USERS : "créé par"
+    AUDIO_GUIDES ||--o{ GUIDE_SEQUENCES : "contient"
+    AUDIO_GUIDES ||--o{ USER_GUIDE_PROGRESS : "progression"
+
+    GUIDE_SEQUENCES }o--|| AUDIO_GUIDES : "appartient à"
+
+    USER_GUIDE_PROGRESS }o--|| USERS : "utilisateur"
+    USER_GUIDE_PROGRESS }o--|| AUDIO_GUIDES : "guide"
+    USER_GUIDE_PROGRESS }o--|| GUIDE_SEQUENCES : "séquence actuelle"
+
+    AUDIO_GUIDES {
+        uuid id PK
+        uuid creator_id FK
+        string title
+        text description
+        string travel_mode
+        int recommended_speed_kmh
+        int sequences_count
+        int total_duration_seconds
+        decimal total_distance_meters
+        polygon diffusion_zone
+        string[] tags
+        string age_rating
+        string status
+        timestamp published_at
+    }
+
+    GUIDE_SEQUENCES {
+        uuid id PK
+        uuid guide_id FK
+        int sequence_order
+        string title
+        string audio_url
+        int duration_seconds
+        point gps_location
+        int trigger_radius_meters
+        boolean requires_manual_trigger
+        timestamp created_at
+    }
+
+    USER_GUIDE_PROGRESS {
+        uuid id PK
+        uuid user_id FK
+        uuid guide_id FK
+        uuid current_sequence_id FK
+        int sequences_completed_count
+        decimal completion_percentage
+        timestamp started_at
+        timestamp last_updated
+        timestamp completed_at
+    }
+```
+
+## Légende
+
+**Entités audio-guides** :
+
+- **AUDIO_GUIDES** : Audio-guides multi-séquences - Travel_mode : `pedestrian` (manuel), `car` (auto GPS + manuel), `bicycle` (auto GPS + manuel), `transport` (auto GPS + manuel) - Sequences_count : Min 2, Max 50 séquences - Status : `draft`, `pending_review`, `published`, `archived` - Diffusion_zone : Polygon géographique (où l'audio-guide est recommandé)
+- **GUIDE_SEQUENCES** : Séquences audio géolocalisées - Sequence_order : Ordre lecture 1, 2, 3... - Trigger_radius : 10-100m selon mode (piéton 10m, voiture 50m) - Requires_manual_trigger : true si mode piéton (bouton "Suivant"), false si auto GPS - GPS_location : Point WGS84 (latitude, longitude) sauf mode piéton
+- **USER_GUIDE_PROGRESS** : Progression utilisateur - Completion_percentage : 0-100% (nb séquences complétées / total) - Current_sequence_id : Dernière séquence écoutée (pour reprise) - Started_at : Date démarrage parcours - Completed_at : NULL si en cours, timestamp si terminé
--- a/docs/diagrammes/entites/modele-monetisation.md
+++ b/docs/diagrammes/entites/modele-monetisation.md
@@ -0,0 +1,74 @@
+# Modèle de données - Monétisation créateurs
+
+📖 Voir [Règles métier - Section 18 : Monétisation](../../regles-metier/18-monetisation-createurs.md) | [Entités globales](modele-global.md)
+
+## Diagramme
+
+```mermaid
+erDiagram
+    CREATOR_MONETIZATION }o--|| USERS : "créateur monétisé"
+    CREATOR_REVENUES ||--o{ REVENUE_TRANSACTIONS : "transactions"
+    CREATOR_REVENUES }o--|| USERS : "revenus"
+
+    PAYOUTS }o--|| USERS : "versement"
+    PAYOUTS ||--o{ REVENUE_TRANSACTIONS : "inclut"
+
+    CREATOR_MONETIZATION {
+        uuid id PK
+        uuid creator_id FK UK
+        string status
+        string kyc_status
+        string mangopay_user_id
+        string mangopay_wallet_id
+        string iban
+        string siret
+        timestamp kyc_validated_at
+        timestamp activated_at
+        timestamp suspended_at
+        timestamp created_at
+    }
+
+    CREATOR_REVENUES {
+        uuid id PK
+        uuid creator_id FK
+        int month_year
+        decimal ad_revenue_euros
+        decimal premium_revenue_euros
+        decimal total_revenue_euros
+        decimal balance_euros
+        string status
+        timestamp computed_at
+    }
+
+    REVENUE_TRANSACTIONS {
+        uuid id PK
+        uuid creator_id FK
+        uuid revenue_month_id FK
+        string transaction_type
+        decimal amount_euros
+        jsonb metadata
+        timestamp created_at
+    }
+
+    PAYOUTS {
+        uuid id PK
+        uuid creator_id FK
+        decimal amount_euros
+        decimal fees_euros
+        decimal net_amount_euros
+        string status
+        string mangopay_payout_id
+        timestamp requested_at
+        timestamp completed_at
+        timestamp failed_at
+    }
+```
+
+## Légende
+
+**Entités monétisation** :
+
+- **CREATOR_MONETIZATION** : Statut monétisation créateur - Status : `pending_kyc`, `active`, `suspended`, `disabled` - KYC obligatoire : SIRET, RIB pro, CNI/Passeport, Kbis <3 mois si société - Critères activation : Compte ≥3 mois, ≥500 abonnés, ≥10K écoutes complètes, 0 strike actif, ≥5 contenus 90j - Vérification via Mangopay KYC (24-72h)
+- **CREATOR_REVENUES** : Revenus mensuels par créateur - Ad_revenue : 3€/1000 écoutes complètes utilisateurs gratuits (CPM) - Premium_revenue : 70% abonnement prorata temps écoute (4.99€ × 0.70 × ratio_ecoute) - Status : `pending`, `computed`, `paid`, `suspended` - Calcul fin de mois, paiement le 15 du mois suivant
+- **REVENUE_TRANSACTIONS** : Détail transactions - Type : `ad_listen`, `premium_listen`, `adjustment`, `refund` - Metadata : content_id, user_id, listen_duration, etc. - Traçabilité complète pour audit
+- **PAYOUTS** : Versements SEPA - Seuil : 50€ minimum, sinon report mois suivant - Fees : 1.8% + 0.18€ (Mangopay SEPA) - Status : `pending`, `processing`, `completed`, `failed` - Retry auto 3 fois si échec, puis suspension monétisation - Inactivité ≥18 mois : versement forcé + préavis emails 12m, 18m, 18m+30j
--- a/docs/diagrammes/entites/modele-premium.md
+++ b/docs/diagrammes/entites/modele-premium.md
@@ -0,0 +1,58 @@
+# Modèle de données - Premium
+
+📖 Voir [Règles métier - Section 17 : Premium](../../regles-metier/17-premium.md) | [Entités globales](modele-global.md)
+
+## Diagramme
+
+```mermaid
+erDiagram
+    PREMIUM_SUBSCRIPTIONS }o--|| USERS : "abonnement"
+    ACTIVE_STREAMS }o--|| USERS : "stream actif"
+    ACTIVE_STREAMS }o--|| CONTENTS : "écoute"
+
+    OFFLINE_DOWNLOADS }o--|| USERS : "téléchargé par"
+    OFFLINE_DOWNLOADS }o--|| CONTENTS : "contenu"
+
+    PREMIUM_SUBSCRIPTIONS {
+        uuid id PK
+        uuid user_id FK UK
+        string provider
+        string provider_subscription_id
+        string provider_user_id
+        string status
+        string plan
+        timestamp current_period_start
+        timestamp current_period_end
+        timestamp cancelled_at
+        timestamp created_at
+    }
+
+    ACTIVE_STREAMS {
+        uuid id PK
+        uuid user_id FK UK
+        uuid content_id FK
+        string device_id
+        string mode
+        int last_position_seconds
+        timestamp started_at
+        timestamp last_heartbeat
+    }
+
+    OFFLINE_DOWNLOADS {
+        uuid id PK
+        uuid user_id FK
+        uuid content_id FK
+        string quality
+        int file_size_bytes
+        timestamp downloaded_at
+        timestamp expires_at
+    }
+```
+
+## Légende
+
+**Entités Premium** :
+
+- **PREMIUM_SUBSCRIPTIONS** : Abonnements Premium - Provider : `mangopay` (web 4.99€), `apple` (IAP 5.99€), `google` (Play 5.99€) - Status : `active`, `cancelled`, `expired`, `past_due` - Plan : `monthly` (4.99€), `yearly` (49.99€ = 2 mois offerts) - Pas d'essai gratuit - Vérification temps réel via Redis cache (TTL 1h) + webhooks providers
+- **ACTIVE_STREAMS** : Streams actifs multi-devices - Limite 1 stream actif par compte (dernier device prioritaire KISS) - Mode : `online`, `offline` (si offline + WiFi/4G) - Heartbeat 30s, TTL Redis 5 min - Détection simultanée : WebSocket close device précédent - Exception : offline mode avion (pas de détection possible)
+- **OFFLINE_DOWNLOADS** : Téléchargements offline - Quality : `low` (24 kbps), `standard` (48 kbps), `high` (64 kbps Premium only) - Limite gratuit : 50 contenus max, Premium : illimité (espace disque) - Validité 30j, renouvellement auto si WiFi - Suppression auto après expiration
--- a/docs/diagrammes/entites/modele-publicites.md
+++ b/docs/diagrammes/entites/modele-publicites.md
@@ -0,0 +1,67 @@
+# Modèle de données - Publicités
+
+📖 Voir [Règles métier - Section 16 : Publicités](../../regles-metier/16-publicites.md) | [Entités globales](modele-global.md)
+
+## Diagramme
+
+```mermaid
+erDiagram
+    AD_CAMPAIGNS }o--|| USERS : "créée par"
+    AD_CAMPAIGNS ||--o{ AD_METRICS : "métriques"
+    AD_CAMPAIGNS ||--o{ AD_IMPRESSIONS : "diffusions"
+
+    AD_IMPRESSIONS }o--|| USERS : "vue par"
+    AD_IMPRESSIONS }o--|| AD_CAMPAIGNS : "campagne"
+
+    AD_CAMPAIGNS {
+        uuid id PK
+        uuid advertiser_id FK
+        string title
+        string audio_url
+        int duration_seconds
+        string status
+        string targeting_geo_type
+        jsonb targeting_geo_data
+        jsonb targeting_hours
+        string[] targeting_interests
+        string targeting_age_rating
+        decimal budget_total_euros
+        decimal budget_remaining_euros
+        decimal cost_per_listen_euros
+        timestamp start_date
+        timestamp end_date
+        timestamp validated_at
+        timestamp created_at
+    }
+
+    AD_METRICS {
+        uuid id PK
+        uuid campaign_id FK
+        date metric_date
+        int impressions_count
+        int complete_listens_count
+        int skips_count
+        decimal avg_listen_duration_seconds
+        int likes_count
+        decimal total_cost_euros
+        timestamp computed_at
+    }
+
+    AD_IMPRESSIONS {
+        uuid id PK
+        uuid campaign_id FK
+        uuid user_id FK
+        decimal completion_rate
+        boolean was_skipped
+        int listen_duration_seconds
+        timestamp displayed_at
+    }
+```
+
+## Légende
+
+**Entités publicités** :
+
+- **AD_CAMPAIGNS** : Campagnes publicitaires - Status : `draft`, `pending_validation`, `validated`, `active`, `paused`, `completed`, `cancelled` - Targeting_geo_type : `point` (GPS + rayon), `city`, `department`, `region`, `national` - Targeting_hours : Array heures locales [7, 8, 9, 17, 18, 19] (heure locale utilisateur) - Budget : Prépaiement obligatoire, déduction 0.05€/écoute complète ou 0.02€/skip après délai min - Validation manuelle obligatoire 24-48h
+- **AD_METRICS** : Métriques agrégées par jour - Calcul quotidien (batch nocturne) - Dashboard temps réel publicitaire - Export CSV/Excel disponible
+- **AD_IMPRESSIONS** : Impressions individuelles - Completion_rate ≥0.8 = écoute complète (facturée 0.05€) - Skip après délai min 5s = partiel (facturé 0.02€) - Skip <5s = non facturé (0€) - Rotation max 3 fois/jour par utilisateur - Limite 6 pubs/h par utilisateur
--- a/docs/diagrammes/entites/modele-radio-live.md
+++ b/docs/diagrammes/entites/modele-radio-live.md
@@ -0,0 +1,63 @@
+# Modèle de données - Radio Live
+
+📖 Voir [Règles métier - Section 12 : Radio Live](../../regles-metier/12-radio-live.md) | [Entités globales](modele-global.md)
+
+## Diagramme
+
+```mermaid
+erDiagram
+    LIVE_STREAMS }o--|| USERS : "diffusé par"
+    LIVE_STREAMS ||--o{ LIVE_RECORDINGS : "enregistrement"
+    LIVE_STREAMS ||--o{ LIVE_LISTENERS : "auditeurs"
+
+    LIVE_LISTENERS }o--|| USERS : "écoute"
+    LIVE_LISTENERS }o--|| LIVE_STREAMS : "stream"
+
+    LIVE_STREAMS {
+        uuid id PK
+        uuid creator_id FK
+        string title
+        string[] tags
+        string age_rating
+        string geo_type
+        jsonb geo_data
+        string status
+        string stream_key
+        string playback_url
+        int current_listeners_count
+        int peak_listeners_count
+        timestamp started_at
+        timestamp ended_at
+        int duration_seconds
+    }
+
+    LIVE_RECORDINGS {
+        uuid id PK
+        uuid stream_id FK
+        string audio_url
+        int duration_seconds
+        int file_size_bytes
+        string status
+        boolean auto_publish
+        timestamp recorded_at
+        timestamp processed_at
+    }
+
+    LIVE_LISTENERS {
+        uuid id PK
+        uuid stream_id FK
+        uuid user_id FK
+        int listen_duration_seconds
+        boolean was_notified
+        timestamp joined_at
+        timestamp left_at
+    }
+```
+
+## Légende
+
+**Entités radio live** :
+
+- **LIVE_STREAMS** : Streams audio temps réel - Status : `preparing` (buffer 15s initial), `live` (diffusion publique), `ended`, `interrupted` - Stream_key : WebRTC ingestion unique par créateur - Playback_url : HLS m3u8 pour diffusion clients - Geo_type : `city`, `department`, `region`, `national` (zone diffusion) - Durée max 8h par session - Déconnexion <60s : reconnexion auto, ≥60s : arrêt auto - Notification push abonnés dans zone géo au démarrage
+- **LIVE_RECORDINGS** : Enregistrements replay auto - Enregistrement obligatoire et automatique pendant live - Status : `recording`, `processing` (transcode HLS), `published`, `deleted` - Auto_publish : true par défaut (créateur peut désactiver) - Processing : Job asynchrone FFmpeg (Opus → HLS segments) - Replay disponible sous 5-15 min après fin live
+- **LIVE_LISTENERS** : Auditeurs live - Join/leave tracking temps réel - Was_notified : true si reçu push notification (analyse efficacité) - Listen_duration : Temps écoute effectif (pour stats créateur) - Peak listeners : Maximum simultané (métrique clé engagement)
--- a/docs/diagrammes/entites/modele-recommandation.md
+++ b/docs/diagrammes/entites/modele-recommandation.md
@@ -0,0 +1,54 @@
+# Modèle de données - Recommandation
+
+📖 Voir [Règles métier - Section 03 : Centres d'intérêt](../../regles-metier/03-centres-interet-jauges.md) | [Section 04 : Algorithme](../../regles-metier/04-algorithme-recommandation.md) | [Entités globales](modele-global.md)
+
+## Diagramme
+
+```mermaid
+erDiagram
+    USER_INTERESTS }o--|| USERS : "préférences"
+    USER_INTERESTS }o--|| INTEREST_CATEGORIES : "catégorie"
+
+    LISTENING_HISTORY }o--|| USERS : "historique"
+    LISTENING_HISTORY }o--|| CONTENTS : "écoute"
+    LISTENING_HISTORY }o--|| USERS : "créateur"
+
+    INTEREST_CATEGORIES {
+        uuid id PK
+        string name UK
+        string slug UK
+        string icon
+        int sort_order
+        boolean is_active
+    }
+
+    USER_INTERESTS {
+        uuid id PK
+        uuid user_id FK
+        uuid category_id FK
+        decimal gauge_value
+        timestamp last_updated
+        int update_count
+    }
+
+    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 recommandation** :
+
+- **INTEREST_CATEGORIES** : Catégories centres d'intérêt - Liste : Automobile, Voyage, Famille, Amour, Musique, Économie, Cryptomonnaie, Politique, Culture, Sport, Technologie, Santé - Extensible dynamiquement
+- **USER_INTERESTS** : Jauges utilisateur par catégorie - Valeur 0-100% (init 50% à l'inscription) - Évolution : Like auto renforcé (+2%), Like auto standard (+1%), Like manuel (+2%), Abonnement créateur (+5% sur tous ses tags), Skip rapide non-abonné (-0.5%) - Calcul temps réel à chaque action - Pas de dégradation temporelle automatique
+- **LISTENING_HISTORY** : Historique écoutes - Source : `recommendation`, `search`, `direct_link`, `profile`, `history`, `live_notification`, `audio_guide` - Completion_rate : 0.0-1.0 (≥0.8 = écoute complète) - Auto_like : true si like automatique déclenché (≥30% écoute) - Is_subscribed : snapshot au moment de l'écoute (pour calcul engagement)