From 04cd6327ab9a45319839302cd7e593b86d769b28 Mon Sep 17 00:00:00 2001 From: jpgiannetti Date: Sat, 7 Feb 2026 16:29:54 +0100 Subject: [PATCH] =?UTF-8?q?feat(diagrammes):=20cr=C3=A9er=20tous=20les=20d?= =?UTF-8?q?iagrammes=20d'entit=C3=A9s=20du=20projet?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- .../diagrammes/entites/modele-audio-guides.md | 68 +++++++++++++++++ .../diagrammes/entites/modele-monetisation.md | 74 +++++++++++++++++++ docs/diagrammes/entites/modele-premium.md | 58 +++++++++++++++ docs/diagrammes/entites/modele-publicites.md | 67 +++++++++++++++++ docs/diagrammes/entites/modele-radio-live.md | 63 ++++++++++++++++ .../entites/modele-recommandation.md | 54 ++++++++++++++ mkdocs.yml | 6 ++ 7 files changed, 390 insertions(+) create mode 100644 docs/diagrammes/entites/modele-audio-guides.md create mode 100644 docs/diagrammes/entites/modele-monetisation.md create mode 100644 docs/diagrammes/entites/modele-premium.md create mode 100644 docs/diagrammes/entites/modele-publicites.md create mode 100644 docs/diagrammes/entites/modele-radio-live.md create mode 100644 docs/diagrammes/entites/modele-recommandation.md diff --git a/docs/diagrammes/entites/modele-audio-guides.md b/docs/diagrammes/entites/modele-audio-guides.md new file mode 100644 index 0000000..89d6bd0 --- /dev/null +++ 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é diff --git a/docs/diagrammes/entites/modele-monetisation.md b/docs/diagrammes/entites/modele-monetisation.md new file mode 100644 index 0000000..4fa30ea --- /dev/null +++ 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 diff --git a/docs/diagrammes/entites/modele-premium.md b/docs/diagrammes/entites/modele-premium.md new file mode 100644 index 0000000..a72abb6 --- /dev/null +++ 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 diff --git a/docs/diagrammes/entites/modele-publicites.md b/docs/diagrammes/entites/modele-publicites.md new file mode 100644 index 0000000..b007196 --- /dev/null +++ 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 diff --git a/docs/diagrammes/entites/modele-radio-live.md b/docs/diagrammes/entites/modele-radio-live.md new file mode 100644 index 0000000..aefeff5 --- /dev/null +++ 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) diff --git a/docs/diagrammes/entites/modele-recommandation.md b/docs/diagrammes/entites/modele-recommandation.md new file mode 100644 index 0000000..18a1a02 --- /dev/null +++ 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) diff --git a/mkdocs.yml b/mkdocs.yml index 5c758fd..7902f4c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -124,6 +124,12 @@ nav: - "Processus d'appel modération": diagrammes/sequence/processus-appel-moderation.md - Entités: - 'Modèle global': diagrammes/entites/modele-global.md + - 'Modèle recommandation': diagrammes/entites/modele-recommandation.md + - 'Modèle publicités': diagrammes/entites/modele-publicites.md + - 'Modèle premium': diagrammes/entites/modele-premium.md + - 'Modèle monétisation': diagrammes/entites/modele-monetisation.md + - 'Modèle audio-guides': diagrammes/entites/modele-audio-guides.md + - 'Modèle radio live': diagrammes/entites/modele-radio-live.md - 'Modèle modération': diagrammes/entites/modele-moderation.md - Documentation Légale: - Introduction: legal/README.md