roadwave/docs/domains/_shared/entities/entities-overview.md

# 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