Nomenclature des Problèmes et Incidents Alta Call

Le service de télémétrie d'Alta Voce analyse en continu les rapports d'état envoyés par le client de bureau. À partir de ces données, la classe backend App\Services\Telemetry\IssueDetectionService détecte automatiquement les anomalies logicielles, matérielles et acoustiques, puis génère ou résout des incidents rattachés à chaque machine.

1. Nomenclature des États Audio Principaux

Le client Alta Call signale l'état actuel de son moteur audio via le paramètre racine audio_state :

RUN : Moteur audio opérationnel et actif (traitement en cours).
STP : Moteur audio arrêté proprement (ex: session verrouillée, ou aucun périphérique disponible).
LOD : Périphérique audio de capture/lecture précédemment configuré perdu ou débranché.
FAI : Échec d'initialisation de l'API audio avec la configuration demandée.
CRA : Plantage inattendu du moteur audio (souvent lié à des blocages d'antivirus, droits insuffisants ou pare-feu).

2. Catalogue des Incidents et Conditions de Détection

Voici la liste exhaustive des codes d'incidents gérés par le système et leurs conditions techniques réelles d'activation et de résolution :

`VERSION_NOTSUPPORTED`

Condition d'activation : La version du logiciel client installée est strictement inférieure à la version minimale globale configurée dans la base backend (VMOCALL_MIN_REQUIRED_VERSION).
Résolution : Mise à jour de l'application cliente vers une version supportée.

`AUDIO_STOPPED`

Condition d'activation : L'état audio rapporté est STP.
Exceptions (Pas d'incident créé) :
- Si la session Windows de l'utilisateur est verrouillée (session_is_locked == true).
- Si le profil de transformation audio actif correspond à l'identifiant spécifique d'arrêt programmé de transformation vocale.

`AUDIO_API_NONE`

Condition d'activation : Impossible d'établir une connexion avec l'API audio Windows WASAPI (ACP est entièrement vide dans le payload) ET l'état audio est FAI (échec).
Résolution : Nécessite généralement une intervention technique sur les permissions d'accès au microphone de la machine ou le déblocage par un antivirus.

`AUDIO_SETUP_FAILED`

Condition d'activation : L'API audio Windows est joignable (ACP non vide) mais l'initialisation du flux audio a échoué (audio_state == FAI).

`AUDIO_DEVICES_NONE`

Condition d'activation : La structure ACP est transmise, mais le client indique explicitement qu'il n'a détecté aucun périphérique de capture valide ET aucun périphérique de lecture valide.

`AUDIO_DEVICE_LOST`

Condition d'activation : Le périphérique audio en cours d'utilisation a été soudainement déconnecté ou perdu en cours de fonctionnement (audio_state == LOD), à condition que la session Windows ne soit pas verrouillée.

`AUDIO_CRASHED`

Condition d'activation : Le moteur audio a planté inopinément (audio_state == CRA).

`AUDIO_DISCONNECTED`

Condition d'activation : Les périphériques audio physiques sont opérationnels, mais aucune application cliente active (telle qu'un softphone de type Zoiper, Genesys, Teams, Skype, etc.) n'est connectée à la sortie audio virtuelle d'Alta Call pour diffuser la voix transformée, et la session est active et déverrouillée.

`MULTI_INSTANCES` (Historique)

Condition d'activation : Plus d'un processus Alta Call actif en parallèle sur la même machine (machine_nbrunningproc > 1) pour les versions de clients très anciennes (antérieures à la version 0.25.0).

`MULTI_INSTANCES_SAMESESSION`

Condition d'activation : Plusieurs processus de l'application Alta Call s'exécutent simultanément au sein de la même session Windows de l'utilisateur (nbrunningproc_insamesession > 1).

3. Anomalies de Performances Acoustiques et Système

Ces incidents sont déclenchés selon des seuils de performance paramétrables dans le fichier de configuration de l'API backend :

`HIGH_LATENCY` (Latence Élevée)

Condition d'activation : Le flux de transformation audio est actif et la latence moyenne mesurée dépasse le seuil SLA configuré.
Seuil par défaut : 150 ms (PT.full_latency.mean_ms > 150).

`EXCESSIVE_XRUNS` (Coupures / Distorsions)

Condition d'activation : Le nombre cumulé de micro-coupures de tampons audio (Underruns de lecture + Overruns de capture) dépasse le seuil acceptable, provoquant des hachures de voix perceptibles par l'interlocuteur.
Seuil par défaut : 500 occurrences (total_xruns > 500).

`HIGH_CPU` (Surcharge Processeur)

Condition d'activation : L'utilisation processeur dédiée au processus Alta Call de la machine dépasse le seuil critique.
Seuil par défaut : 50 % d'un cœur CPU complet (cpu_usage > 0.5).

`AUDIO_SATURATION` (Saturation Acoustique)

Condition d'activation : Des saturations ou écrêtages numériques du signal de la voix sont constatés à la capture ou à la lecture.
Seuil par défaut : 0 saturation tolérée (capture_saturations + playback_saturations > 0).