Architecture de la Base de Données (MySQL)

1. Vue d'ensemble

L'écosystème Alta Call s'appuie sur une base de données relationnelle MySQL unifiée. Cette base de données orchestre l'administration des clients, des licences, la télémétrie en temps réel, l'analyse de qualité audio (Business Intelligence) et le diagnostic automatique d'incidents.

Ce document fait office de référence officielle pour le schéma de données, décrivant le modèle conceptuel, les dictionnaires de tables et les optimisations physiques (indexations et rétentions).

2. Modèle Conceptuel des Données (MCD)

Le diagramme d'entités-relations suivant illustre la structure des tables principales gérées par le backend Laravel et leurs cardinalités :

classDiagram
    direction LR
    class clients {
        int id PK
        string name
        string email
        string vat_number
        json config
    }
    class groups {
        int id PK
        int client_id FK
        string name
    }
    class users {
        int id PK
        int group_id FK
        string name
        string email
        string vmo_user_id
        int audiostream1_id FK
    }
    class licenses {
        int license_id PK
        int group_id FK
        string licenses_key
        bool valid
    }
    class machines {
        int id PK
        int group_id FK
        string vmo_machine_id
        string computer
        string version
    }
    class telemetries {
        bigint id PK
        int client_id FK
        int user_id FK
        string process_id
        datetime date
        json payload
    }
    class users_summaries {
        bigint id PK
        int user_id FK
        string transfo_mode
        date date
        float duration
    }
    class machines_issues {
        bigint id PK
        int machine_id FK
        string issue_code
        datetime first_update
        datetime last_update
        string var1
    }
    class audiodevices {
        int id PK
        string name
        string type
    }
    class audiostreams {
        int id PK
        int device_capture_id FK
        int device_playback_id FK
        float duration
    }

    clients "1" --> "0..*" groups : possède
    groups "1" --> "0..*" users : contient
    groups "1" --> "0..*" licenses : attribue
    groups "1" --> "0..*" machines : enregistre
    users "1" --> "0..*" telemetries : génère
    users "1" --> "0..*" users_summaries : possède
    users "0..1" --> "0..*" audiostreams : utilise
    machines "1" --> "0..*" machines_issues : subit
    telemetries "0..1" --> "0..*" machines_issues : déclenche
    audiostreams "0..1" --> "1" audiodevices : capture
    audiostreams "0..1" --> "1" audiodevices : restitue

3. Dictionnaire Exhaustif des Tables

Voici la description technique détaillée de chaque table de la base de données de production :

3.1. Table clients (Organisations)

Cette table représente les entreprises clientes d'Alta Voce (ex: centres de contacts).

3.2. Table groups (Départements / Équipes)

Un client peut diviser son organisation en plusieurs groupes logiques (ex: équipe de jour, support technique).

3.3. Table users (Agents et Superviseurs)

Cette table contient les profils des utilisateurs finaux rattachés à des groupes.

3.4. Table machines (Postes Physiques)

La table machines recense tous les ordinateurs physiques sur lesquels l'application de bureau Alta Call a été installée et validée.

3.5. Table licenses (Clés d'Authentification)

Stocke les licences d'accès nécessaires pour utiliser le logiciel de bureau Alta Call.

3.6. Table telemetries (Rapports Bruts Optimisés)

Stocke les paquets de métriques brutes envoyés par les clients de bureau.

3.7. Table users_summaries (Résumés d'Activité Quotidiens)

Table optimisée contenant les résumés d'appels consolidés quotidiens pour l'analyse décisionnelle (Business Intelligence) et la facturation.

3.8. Table machines_issues (Registre d'Incidents)

Registre de diagnostic automatique pour l'administration et le support technique. Les incidents résolus sont supprimés lors des nettoyages automatiques.

3.9. Table audiodevices (Périphériques Audio Référencés)

Catalogue de tous les microphones et casques d'écoute recensés sur le parc de machines.

3.10. Table audiostreams (Flux Audio Actifs)

Cette table représente l'état d'activité dynamique des flux de traitement audio ouverts par l'application client.

3.11. Tables Annexes, Utilitaires et Logs

En dehors des tables principales d'exécution du flux audio et de télémétrie, la base de données MySQL contient des tables annexes dédiées à la facturation, la sécurité, l'A/B Testing et l'historique de diagnostic.

Catégorie A : Facturation, Tarifs et Historiques de Consommation

• invoices : Répertoire des factures générées mensuellement pour les organisations. Contient les montants, les états de paiement et les liens vers les fichiers PDF de facturation.
• pricings et pricing_clients : Grilles tarifaires de base et tarifs personnalisés par client (définissant le coût à la seconde d'appel transformé).
• daily_usages et monthly_usages : Consommation consolidée de durée de voix transformée et de bande passante calculée par client de manière quotidienne et mensuelle.
• accounts : Comptes de facturation Stripe ou Gandi liés à l'abonnement de chaque client.
• addresses : Adresses de facturation physiques associées à chaque client.

Catégorie B : Administration et Configuration de l'A/B Testing

• transfos : Catalogue des modes de transformation acoustique disponibles (avec leur configuration de base, ex : preset SMA).
• abtest_transfos : Table de pivot associant une campagne d'A/B Test à ses presets de transformations vocales cibles.
• labels : Skill-tags ou étiquettes métiers (ex : "Langue - Anglais", "Service Client Premium") pouvant être attribués aux agents pour filtrer les A/B tests.
• user_labels : Table de pivot reliant les utilisateurs (users) à leurs étiquettes métiers (labels).

Catégorie C : Systèmes de Diagnostics Applicatifs et Logs

• processes2 : Suivi en direct de chaque processus actif d'Alta Call sur toutes les machines (utilisé pour la détection d'instances multiples concurrentes).
• telemetry_incidents : Table d'agrégation d'incidents critiques pour déclencher des alertes par mail aux administrateurs.
• altacall_log_entries et altacall_log_records : Fichiers de logs système envoyés périodiquement par le client de bureau en cas d'erreur bloquante ou d'exception fatale.
• plugin_logs : Registre d'événements techniques envoyés par les modules d'intégration intégrés aux softphones des agents.
• events : Trace historique d'actions clés de l'application (ex : "Démarrage Moteur Audio", "Changement de micro").
• user_request_logs : Journal de requêtes HTTP utilisé pour sécuriser l'API et appliquer du rate limiting contre les attaques DDoS.

Catégorie D : Métriques Audio et Qualité

• audio_data : Métadonnées associées aux fichiers d'enregistrements audio de tests.
• recordings et recording_clients : Règles d'activation d'enregistrement audio de diagnostic configurées à distance par client ou groupe.
• machine_summaries et user_daily_summaries : KPI pré-calculés chaque nuit pour accélérer l'affichage des graphiques administrateur sans relire les tables brutes.
• metrics et performance_metrics : Mesures de latence réseau et d'utilisation CPU cumulées pour les bilans de performance.

Catégorie E : Sécurité, Versioning et Notifications

• access_attempts : Journalisation des tentatives de connexion à l'administration Laravel Filament (avec IP et statut) pour prévenir les attaques par force brute.
• api_keys : Clés privées/publiques d'API fournies aux tiers pour interagir avec le backend Alta Voce.
• impersonations : Logs d'audit des administrateurs Alta Voce se connectant en tant que client (pour le support technique).
• configs : Configuration système globale de l'application Laravel (ex : version minimale requise).
• software_versions : Catalogue des versions logicielles publiées avec leurs chemins de fichiers d'installation, utilisé pour la mise à jour automatique.
• outdated_machines : Registre temporaire recensant les ordinateurs physiques tournant sous des versions du logiciel jugées obsolètes ou non supportées.
• notifications : Boîte de réception des messages système ou alertes envoyés aux administrateurs d'organisation.
• suggestions : Retours utilisateurs ou tickets de suggestion saisis par les agents depuis l'application de bureau.

4. Recommandations Physiques & Indexation (MySQL)

[!IMPORTANT] Indexation Stratégique pour les Requêtes de BI et de Diagnostics Afin de garantir des temps de réponse inférieurs à 100 ms sur les tableaux de bord Filament Admin et l'Espace Client, les index MySQL suivants doivent impérativement être présents et optimisés en production :

1. Index Composite sur telemetries :
   CREATE INDEX idx_telemetries_user_date ON telemetries (user_id, date);
   Pourquoi : Utilisé en continu lors des calculs nocturnes de résumés d'activités pour agréger les télémétries d'un utilisateur sur un jour donné.

2. Index Composites sur users_summaries :
   CREATE INDEX idx_users_summaries_date_user ON users_summaries (date, user_id);
   Pourquoi : Indispensable pour l'affichage instantané des graphes de durées d'appels et statistiques de Pitch par agent dans l'Espace Client Vue.js.

3. Index d'état sur machines_issues :
   CREATE UNIQUE INDEX idx_machines_issues_lookup ON machines_issues (machine_id, issue_code);
   Pourquoi : Permet de récupérer instantanément et sans doublons les incidents ouverts d'une machine sans balayage complet.