# 7. Direct sportif (MatchPulse)

## 7.1 Source de données

Les données viennent d'**API-Football / API-Basketball** (API-Sports, https://api-sports.io) : une seule clé pour les deux sports.

| Donnée | Couverture API-Football |
|---|---|
| Scores, statut, minute, temps additionnel, mi-temps, tirs au but | oui |
| Événements (buts, passeurs, cartons, remplacements, VAR, penaltys manqués) | oui (selon la compétition) |
| Compositions, formation, entraîneur, remplaçants | oui (≈ 20 à 40 min avant le coup d'envoi) |
| Statistiques d'équipe (possession, tirs, corners, fautes, hors-jeu, cartons, passes, xG) | oui (xG selon la compétition) |
| Statistiques et note des joueurs | oui (selon la compétition) |
| Coups francs | non fournis par ce fournisseur : affichés seulement s'ils apparaissent |
| Classements, fiches équipes et joueurs | oui |

Rien n'est inventé : une donnée absente reste « non fournie par la source de données ». La table de couverture de chaque compétition est publiée par le fournisseur.

**Offre gratuite (constaté le 15/10/2026 sur un vrai match)** : le direct fonctionne (scores, minute, événements, compositions, statistiques et joueurs d'un match via `fixtures?id=`), mais avec 100 requêtes/jour, sans le paramètre `ids` (détails groupés), dates limitées à hier/aujourd'hui/demain et saisons limitées aux saisons passées (pas de classement ni de fiches équipes/joueurs de la saison en cours). La plateforme détecte l'offre (`/status`) et s'adapte : barre de dates réduite, détails chargés à l'ouverture d'une page de match, refus du fournisseur non réessayés pendant 6 h, messages explicites aux visiteurs.

**Offre payante** : nécessaire pour un site public Pour la production, une offre payante est nécessaire (par exemple Pro : 7 500 requêtes/jour). Indiquer le quota dans `API_SPORTS_DAILY_QUOTA`.

**Droits** : les conditions d'utilisation d'API-Sports autorisent l'affichage des données sur votre site ; la source est citée dans le pied de page et sur les pages de match. Ne pas récupérer de données sur d'autres sites de résultats (scraping).

## 7.2 Architecture

```
API-Football ──(1 appel / 30 s pendant les matchs)──> Laravel : livescore:sync (planificateur)
                                                         │  normalisation, base sport_matches,
                                                         │  relevés de statistiques (évolution), cache
                                                         ▼
                        flux JSON : /resultats/live.json, /match/{id}.json  (servis depuis le cache)
                                                         │
                     Relais Node.js (realtime/server.mjs) │  1 requête / 5 s par flux, quel que soit
                     Server-Sent Events                   │  le nombre de visiteurs
                                                         ▼
                                   Navigateurs (repli automatique : interrogation toutes les 30 s)
```

- **Quota** : seuls le planificateur et le cache appellent l'API ; un verrou évite les appels simultanés ; les appels s'arrêtent à 95 % du quota quotidien. En cas d'erreur ou de quota atteint, la dernière donnée reçue est servie.
- **Synchronisation** : la tâche ne tourne que si un match est en cours ou commence dans 10 minutes ; un appel `fixtures?live=` pour tous les matchs en direct, puis un appel `fixtures?ids=` (jusqu'à 20 matchs) pour les événements, compositions et statistiques. Un dernier appel enregistre le coup de sifflet final. Les matchs terminés sont ensuite servis depuis la base, sans nouvel appel.
- **Fiabilité** : un statut « en direct » non confirmé depuis plus de 5 minutes s'affiche « Mise à jour en attente », jamais comme direct. L'heure de la dernière mise à jour est affichée. Les horaires sont convertis dans le fuseau du visiteur.
- **AdSense** : la page et les annonces ne sont jamais rechargées ; seules les données changent.

## 7.3 Mise en service

1. Créer un compte sur https://dashboard.api-football.com (offre payante pour le direct), copier la clé.
2. Dans `.env` : `API_SPORTS_KEY=…` et `API_SPORTS_DAILY_QUOTA=…` (quota de l'offre).
3. Back-office → MatchPulse → Paramètres → Résultats sportifs : fournisseur « API-Football », compétitions suivies (football et basket).
4. Planificateur : `php artisan schedule:work` (développement) ou la tâche cron `* * * * * php artisan schedule:run` (production). Alternative : `php artisan livescore:sync --loop` sous un gestionnaire de processus.
5. Relais temps réel (facultatif) : `UPSTREAM=https://matchpulse.fr ALLOWED_HOSTS=matchpulse.fr PORT=8090 node realtime/server.mjs` derrière un proxy HTTPS (désactiver la mise en mémoire tampon : `proxy_buffering off`), puis `LIVESCORE_STREAM_URL=https://live.matchpulse.fr`.
6. Vérifier sur un match en cours : `php artisan livescore:sync --force` doit afficher « n en direct, n détails », puis la page du match se met à jour sans rechargement.