Contrat API frontend — suivi de consommation QoE

Base API : https://live.jmoai.net/api/v1/radius.

Ce contrat décrit les données affichables par l’application mobile ou le portail administrateur. Les routes de contrôle exigent un JWT client, un lien client valide et une licence RADIUS active. La télémétrie routeur est une route bridge séparée.

1. Lire l’état réseau

GET /qoe/status

Réponse :

{
  "nas": [
    {
      "nas_id": "uuid",
      "observed_at": "2026-08-28T10:00:00Z",
      "rtt_ms": 85,
      "jitter_ms": 12,
      "packet_loss_pct": 0.5,
      "tx_bps": 4000000,
      "rx_bps": 18000000
    }
  ],
  "congested_nas": []
}

2. Lire la consommation

GET /qoe/usage

Réponse :

{
  "date": "2026-08-28",
  "nas": [
    {
      "nas_id": "uuid",
      "daily_gb": 160,
      "last_two_hours_gb": 60,
      "acceleration_pct": 60,
      "daily_warning": true,
      "accelerating": true,
      "congested": true
    }
  ]
}

Les valeurs sont calculées à partir des compteurs WAN cumulés. daily_warning devient vrai à partir de 100 GiB dans la journée. accelerating exige simultanément 100 GiB sur la journée, 5 GiB dans les deux dernières heures et une hausse d’au moins 35 % par rapport au volume consommé avant cette fenêtre.

3. Afficher les recommandations

Une alerte d’usage est envoyée avec data.type = "QOE_USAGE_ALERT" et contient :

{
  "usage": { "daily_gb": 160, "last_two_hours_gb": 60, "acceleration_pct": 60 },
  "recommendation": {
    "mode": "SUGGEST_ONLY",
    "action": "SCHEDULE_NEXT_DAY_FAIR_QUEUE_REVIEW",
    "reason": "La hausse de consommation coïncide avec une congestion mesurée."
  }
}

Correspondance UI recommandée :

• daily_warning=true : afficher une information « consommation élevée » ;
• accelerating=true et congested=true : afficher une alerte prioritaire et proposer une revue de file équitable pour le lendemain ;
• accelerating=true et congested=false : demander une vérification des gros consommateurs, sans parler de panne réseau ;
• aucun indicateur : ne pas afficher d’alerte.

Le frontend ne doit jamais présenter cette recommandation comme un bridage déjà appliqué. Le serveur ne bloque pas les torrents ou les applications et ne déclenche pas de CoA/PoD automatique.

4. Notifications et rapport de 23 h 59

GET /qoe/preferences retourne urgent_push, daily_report_push, usage_alert_push, quiet_start, quiet_end.

PUT /qoe/preferences accepte uniquement ces cinq champs. Les heures sont des entiers de 0 à 23 ou null.

GET /qoe/reports?limit=30 retourne les rapports quotidiens. Le rapport de la veille est produit à 23 h 59, idempotent par client et par date, et son résumé inclut usage par NAS.

5. États à respecter dans l’interface

• HTTP 202 sur la télémétrie ou une demande d’action signifie « reçu/enregistré », pas « action réseau terminée » ;
• une liste vide est un état normal (« aucune mesure reçue »), pas une erreur ;
• l’absence de compteur WAN ne doit pas être affichée comme 0 GB : utiliser « données indisponibles » ;
• les données sont limitées au client authentifié et à ses NAS.

Déviations et limites connues

Le bridge RouterOS qui collecte les compteurs et l’essai sur NAS réel restent à installer. La migration SQL n’est pas appliquée par ce contrat. Le CoA/PoD automatique est exclu tant que la compatibilité et le rollback n’ont pas été prouvés sur un routeur pilote isolé.