Services Web et APIs

Cette section décrit l'architecture, le développement et le déploiement des services web d'Alta Voce.

Architecture générale

Nos services web sont construits autour d'un monolithe Laravel assurant à la fois le panneau d'administration et l'API REST, couplé à un frontend Vue.js 3 SPA autonome :

  • Backend (Monolithe Laravel) : API REST unifiée, tableau de bord d'administration Filament et tâches CRON planifiées
  • Frontend (SPA Vue.js) : Tableau de bord client déployé sous forme de fichiers statiques
  • Base de données : Stockage centralisé MySQL (base de données unifiée voimooo)
  • Monitoring : Surveillance des performances et de la santé via Laravel Telescope

Dépôts de développement

Le développement des services web se fait dans les dépôts principaux suivants :

Stack technique

Backend (API & Administration)

  • Framework : Laravel 10 / PHP 8.1
  • Interface Admin : Filament Admin v3 (gestion des utilisateurs, licences, périphériques)
  • Base de données : MySQL (base de données unifiée voimooo)
  • Authentification : Laravel Sanctum (tokens opaques) et sessions sécurisées natives
  • WebSockets : Laravel Reverb (pour les notifications en temps réel)
  • Outil de débogage : Laravel Telescope
  • Documentation API : Scribe (générée automatiquement)

Frontend (Espace Client)

  • Framework : Vue.js 3 (Composition API)
  • Outil de build : Vite
  • Styling : TailwindCSS v3
  • Gestion d'état : Vuex 4 avec persistance locale chiffrée AES (vuex-persist + crypto-js)
  • Traduction (i18n) : Runtime vue-i18n, avec extraction des traductions via Easygettext (fichiers .po compilés)
  • Monitoring d'erreurs : SDK Sentry (remontée des exceptions JavaScript côté client)

Hébergement & Déploiement

  • Hébergement : Gandi Simple Hosting (environnement Apache / PHP managé)
  • Déploiement : Automatisé via GitHub Actions / runners GitLab CI (transfert SFTP/Rsync + commandes post-déploiement SSH)
  • Tâches planifiées : Planificateur HTTP externe (ex: cron-job.org) appelant des routes sécurisées /cron/*

Processus de développement

1. Environnement de développement Backend (API & Admin)

# Cloner le dépôt backend
git clone https://gitlab.com/altaCall/admin-alta.alta-voce.tech.git
cd admin-alta.alta-voce.tech

# Installer les dépendances PHP et Node
composer install
npm install

# Configurer l'environnement local
cp .env.example .env
# Éditer le fichier .env avec vos identifiants locaux (DB, mail, Sentry, etc.)

# Générer la clé d'application et jouer les migrations
php artisan key:generate
php artisan migrate

# Lancer le serveur de développement local
php artisan serve

2. Environnement de développement Frontend (Espace Client)

# Cloner le dépôt frontend
git clone https://gitlab.com/altaCall/client-alta.alta-voce.tech.git
cd client-alta.alta-voce.tech/client-alta

# Installer les dépendances
npm install

# Démarrer le serveur de développement local Vite
npm run dev

3. Tests et outils qualité

# Lancer les tests unitaires et d'intégration PHP (Backend)
php artisan test

# Exécuter l'analyseur de code statique PHP
vendor/bin/phpstan analyse

# Extraire et compiler les clés de traduction (i18n — Frontend)
npm run i18n-extract
npm run i18n-compile

4. Déploiement

Les déploiements sont automatisés via les pipelines CI/CD dès qu'un merge est effectué sur la branche de production. Consultez le runbook complet dans DevOps & CI/CD.

Authentification

L'API utilise les tokens opaques Laravel Sanctum (pas des JWT). Après une connexion réussie, le serveur retourne un token bearer à inclure dans toutes les requêtes suivantes.

// 1. S'authentifier et récupérer le token bearer
const response = await fetch('https://admin-alta.alta-voce.tech/api/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'password'
  })
});
const { token } = await response.json();

// 2. Utiliser le token dans les requêtes suivantes
const data = await fetch('https://admin-alta.alta-voce.tech/api/groups', {
  headers: { 'Authorization': `Bearer ${token}` }
});

[!NOTE] Les tokens expirent après 2 heures d'inactivité. Le client frontend (http.js) gère le rafraîchissement automatique lorsque le token a moins de 30 minutes de validité restante.

API du Client de Bureau (Plugin AltaCall)

Le plugin de bureau communique via un ensemble de routes dédiées sous /api/altacall/, authentifiées par une clé de licence (envoyée dans l'en-tête X-License ou intégrée dans le payload) :

EndpointMéthodeDescription
/api/altacall/licenseGET / POSTValider la clé de licence et récupérer la configuration du groupe
/api/altacall/telemetryPOSTSoumettre un payload de télémétrie de diagnostic périodique
/api/altacall/eventPOSTNotifier le serveur d'un branchement/débranchement de périphérique
/api/altacall/processPOSTDéclarer une nouvelle instance de processus en cours d'exécution
/api/altacall/consentGET / POSTLire ou mettre à jour le consentement de collecte de données de l'agent
/api/altacall/configGETRécupérer la configuration active de l'agent
/api/altacall/logsPOSTEnvoyer un bundle de logs de diagnostic

Bonnes pratiques de sécurité

  • Toutes les communications utilisent HTTPS
  • L'authentification API utilise des tokens opaques Sanctum — ne jamais les stocker en clair dans localStorage (le frontend utilise le chiffrement AES via crypto-js)
  • Le rate limiting est appliqué sur les routes sensibles (throttle:sensitive sur login/register/reset-password)
  • La table user_request_logs journalise toutes les requêtes API pour l'audit et la mitigation DDoS
  • Les clés de licence sont validées côté serveur à chaque soumission de télémétrie ; une clé révoquée retourne immédiatement HTTP 403

Dépannage

Pour les incidents opérationnels courants (HTTP 500 après déploiement, rejets de télémétrie, saturation disque, statistiques BI manquantes), consultez le runbook dédié :

👉 DevOps & CI/CD — Guide de résolution d'incidents

Pour plus d'informations techniques, référez-vous à la documentation spécifique de chaque service dans les sections ci-dessus.