Plateforme d'Administration Backend (admin-alta.alta-voce.tech)

Documentation auto-générée

Documentation API REST (Scribe) : Voir la documentation API - Documentation OpenAPI/Postman générée automatiquement.

1. Rôle d'Architecture & Spécifications

Le backend admin-alta sert de tour de contrôle centrale pour tout l'écosystème Alta Voce. Conçu en Laravel 10 / PHP 8.1, il remplit trois rôles critiques :

1. Ingestion et Nettoyage de la Télémétrie : Point d'entrée à haute fréquence (REST API) collectant les paquets envoyés par les agents, exécutant les filtres de sécurité et de nettoyage (réduction de 96 % par whitelist).
2. Portail d'Administration Filament v3 : Dashboard d'administration complet basé sur Livewire, Alpine.js et Tailwind pour piloter l'ensemble du parc client.
3. Moteur d'Orchestration Temporel (CRON / CLI) : Système automatisé d'analyse nocturne, d'agrégation décisionnelle (BI), de facturation et de maintenance préventive.

2. Authentification de l'API REST

L'API REST utilise des tokens opaques Laravel Sanctum (pas JWT). Les tokens sont créés à la connexion et transmis en tant que header Bearer sur toutes les requêtes protégées.

Cycle de vie des tokens

• Expiration : 2 heures après la création (configurable via sanctum.expiration).
• Rafraîchissement proactif : Le client frontend appelle automatiquement POST /api/refresh-token quand il reste moins de 30 minutes sur le token courant.
• Rafraîchissement réactif : Sur une réponse 401, le client tente un rafraîchissement si l'utilisateur a été actif dans les 5 dernières minutes ; sinon il force la déconnexion.

Endpoints d'authentification

Politique de mot de passe (configuration de compte)

Les nouveaux comptes configurés via le flux d'invitation doivent choisir un mot de passe contenant au moins une majuscule, une minuscule, un chiffre et un caractère spécial (minimum 8 caractères). Le lien de configuration est valide 3 jours.

Système de rôles

Trois rôles existent dans la table roles :

Impersonification

Les administrateurs peuvent impersonifier n'importe quel autre compte :

• POST /api/impersonate — Démarre l'impersonification. Retourne un nouveau token limité au compte cible. L'événement est enregistré dans la table impersonations.
• POST /api/impersonate/stop — Restaure la session et le token admin d'origine.
• Le frontend (ImpersonateWidget.vue) affiche une bannière persistante pendant l'impersonification et permet de l'arrêter à tout moment.

3. API Plugin Desktop (/api/altacall/*)

Routes utilisées exclusivement par le client Windows AltaCall. L'authentification est gérée par un AltaAuthMiddleware personnalisé qui supporte simultanément trois schémas : PHP Basic Auth (PHP_AUTH_USER/PHP_AUTH_PW), HTTP Basic Auth (Authorization: Basic ...), et un schéma Digest propriétaire (Authorization: Digest clientId:userId:sha256checksum).

Toutes les routes plugin passent également par AltacallMonitoringMiddleware, qui enregistre les métriques de requêtes (durée, mémoire, taille de réponse, IP, infos licence).

Gestion des événements

L'endpoint POST /api/altacall/event distribue chaque événement à un handler typé :

Retourne {"actions": ["config.update"]} quand le client doit rafraîchir sa config, {"actions": []} sinon.

4. Architecture du Portail Admin (Filament v3)

Le portail s'appuie sur Filament Admin v3, structuré autour de Resources gérant les modèles Eloquent. Chaque ressource définit ses formulaires de saisie, ses grilles avec filtres et ses actions métier personnalisées :

4.1. ABTestsResource (Gestion des Campagnes A/B Testing)

• Description : Créer, configurer et monitorer les tests comparatifs d'algorithmes acoustiques (SMA, VMO, Smile).
• Colonnes : id, name, status (badges : active/pending/completed), start_date, end_date, goal_progress (barre de progression dynamique).
• Formulaire : Configuration générale, sélection des presets de transformation, ciblage par labels d'agents.
• Actions :
  • Télécharger le CSV : Export brut de toutes les télémétries et KPIs liés au test.
  • Forcer la Rotation : Déclenche immédiatement la rotation des algorithmes.

4.2. ClientResource (Administration des Comptes Clients)

• Description : Gestion des entreprises et centres d'appels clients.
• Colonnes : name, email, email_billing, vat_number, groups_count.
• Formulaire : Informations fiscales, contact, Éditeur JSON config (restrictions réseau, règles d'alertes).

4.3. UserResource (Agents Alta Call)

• Description : Profils des agents enregistrés via télémétrie (différents des comptes portail).
• Colonnes : name (username Windows), vmo_user_id, last_update, status.
• Actions : Export Usage Trace (CSV/JSON) — historique quotidien des durées et médianes F0/Pitch.

4.4. AccountsResource (Comptes du Portail)

• Description : Comptes des utilisateurs admin et client-admin qui se connectent au dashboard web. Distinct de users (les agents Alta Call sur les postes). Les comptes portail utilisent email/mot de passe via Sanctum.

4.5. MachinesResource (Inventaire & Diagnostic du Parc)

• Description : Administration de tous les postes physiques exécutant Alta Call.
• Colonnes : computer (hostname), vmo_machine_id, version, local_ip_address, status (vert/rouge selon les incidents ouverts).
• Actions : Onglet de diagnostic listant les anomalies ouvertes (depuis machines_issues).

4.6. InvoicesResource (Module de Facturation Automatisée)

• Description : Création et suivi financier des abonnements mensuels.
• Colonnes : invoice_number, client.name, period_start, period_end, amount_excl_tax, amount_incl_tax, status (paid/unpaid/frozen).
• Actions :
  • Télécharger le PDF : Facture légale générée depuis un template Blade.
  • Notifier par Email : Envoi automatique au contact de facturation.

4.7. LicenseResource (Clés d'Accès)

• Description : Génération et activation des clés de licences logicielles.
• Formulaire : Génération automatique, champ fancyname pour le support, toggle valid pour révocation immédiate.

4.8. TransformationsResource (Presets de Transformation Vocale)

• Description : Gestion des algorithmes de transformation vocale (transfos). Chaque preset définit le transfo_mode (SMA, VMO, MANUAL) et son payload de paramètres JSON injecté dans les configs plugin.

4.9. GroupsResource & MonitoringResource

• GroupsResource : Gestion des départements/équipes clients. Les groupes relient clients, utilisateurs, machines et licences.
• MonitoringResource : Inspection des métriques de requêtes enregistrées par AltacallMonitoringMiddleware (latences, taux d'erreur, requêtes lentes).

4.10. AltacallLogResource & PluginLogResource

• Description : Consulter et télécharger les bundles de logs système et les logs d'intégration softphone envoyés par les postes.

4.11. SoftwareVersionResource (Versioning et Déploiement)

• Description : Gérer les packages logiciels (MSI/EXE) et définir les versions minimales requises pour forcer les mises à jour de sécurité.

4.12. RecordingsResource, SuggestionResource & ExternalUtilityResource

• RecordingsResource : Règles et fichiers d'enregistrement audio à distance, utilisés pour le contrôle qualité des A/B tests.
• SuggestionResource : Tickets de feedback utilisateurs envoyés depuis le client de bureau.
• ExternalUtilityResource : Téléchargements d'outils complémentaires distribués via le portail.

5. Moteur d'Orchestration Temporel (CRON / CLI)

[!IMPORTANT] Architecture de contournement HTTP (FastCGI) Le backend étant hébergé sur Gandi Simple Hosting avec un timeout HTTP de 30 secondes, les tâches planifiées utilisent une méthode asynchrone :

1. Un planificateur externe (cron-job.org) appelle les routes sous /cron/* via HTTP GET.
2. La route appelle fastcgi_finish_request(), retournant HTTP 200 immédiatement pour couper la connexion réseau.
3. PHP continue l'exécution en arrière-plan (set_time_limit(170)) pour terminer les longs calculs.

Référence complète des endpoints cron

6. Gestion de la Télémétrie (Pipeline d'Ingestion)

Toute télémétrie soumise par un client de bureau traverse un pipeline rigoureux géré par TelemController@postTelemetry :

graph TD
    A[Paquet de Télémétrie Entrant] --> B[AltaAuthMiddleware — Auth Licence/Digest]
    B --> C{Auth valide ?}
    C -- Non --> X1[401 Non autorisé]
    C -- Oui --> D[Vérification de la version vs version minimale requise]
    D --> E[Résolution des entités : Utilisateur / Machine / Processus]
    E --> F{Payload de rattrapage ?}
    F -- Oui --> G[Stocker la télémétrie brute & retour anticipé]
    F -- Non --> H["TelemetryCleaningService — réduction 96% du payload"]
    H --> I[Traitement des périphériques audio & Audiostream]
    I --> J[Calcul des statistiques de processus actifs]
    J --> K["Transaction atomique DB : Update Processus, Machine, Utilisateur"]
    K --> L["IssueDetectionService — scan des anomalies"]
    L --> M[Écriture dans machines_issues & telemetry_incidents si anomalie détectée]
    M --> N[Broadcast IncidentCreated via Laravel Reverb si nouvel incident]
    N --> O[Retour 200 OK]

• Auth : AltaAuthMiddleware valide PHP Basic Auth, HTTP Basic Auth, ou le schéma Digest propriétaire.
• Nettoyage : TelemetryCleaningService applique une whitelist de clés approuvées, réduisant chaque entrée JSON de 96 % (de ~14 Ko à ~535 octets en moyenne).
• Détection d'incidents : IssueDetectionService scanne le payload pour les anomalies (HIGH_LATENCY, EXCESSIVE_XRUNS, AUDIO_CRASHED, etc.) et ouvre ou résout des enregistrements dans machines_issues.
• Broadcast temps réel : Quand un nouvel TelemetryIncident est créé, l'événement IncidentCreated est diffusé sur le canal incidents via Laravel Reverb (WebSockets), permettant des alertes en direct dans le tableau de bord admin.