Comment nous construisons chaque statistique

Tout ce que nous affichons vient de trois sources que nous gardons auditables : l'API publique de Supercell (developer.brawlstars.com), le CDN Brawlify (cdn.brawlify.com), et notre propre base Supabase, qui persiste les combats et agrégats que l'API officielle ne révèle pas au-delà des 25 derniers matchs par joueur.

L'API Supercell est la source canonique pour les données structurelles — brawlers, gadgets, star powers, hypercharges, gears et rotation des événements — mais elle laisse de côté des champs critiques comme les images, la rareté et les descriptions longues. Nous croisons ces champs avec le CDN Brawlify, qui fonctionne indépendamment et accuse parfois un retard d'un à trois jours sur Supercell. Quand un brawler nouveau apparaît sur l'API officielle sans encore exister chez Brawlify, nous gardons une carte locale de rareté (BRAWLER_RARITY_MAP) pour que sa page s'affiche correctement le jour du lancement.

Notre base stocke deux classes de lignes dans la table meta_stats : source=user (combats réels d'utilisateurs premium ayant activé la sync) et source=global (échantillonnage automatique des classements PRO). Toute statistique publique sur le site est calculée en filtrant par source=global, pour qu'aucune donnée personnelle d'un utilisateur ne fuite vers les pages publiques.

La couche « PRO » de BrawlVision est un ensemble d'agrégats calculés sur les combats récents des meilleurs joueurs du monde. Toutes les six heures, un cron (meta-poll) interroge les classements officiels de Supercell pour onze pays — ceux qui concentrent l'activité compétitive — et construit une pool dédoublonnée d'environ 2 100 joueurs uniques tirés de chaque top 200.

Sur cette pool nous appliquons un sampler probabiliste pour empêcher que les combinaisons (carte, mode) populaires écrasent le dataset et masquent les plus rares. La probabilité d'accepter un combat individuel est p = min(1, (minLive + 1) / (current + 1)), où minLive est le nombre de la combinaison la moins représentée et current celui de la combinaison du combat candidat. Les combinaisons sous-échantillonnées reçoivent plus de poids, les saturées arrêtent de croître.

Le cron itère jusqu'à META_POLL_MAX_DEPTH = 1 000 joueurs par exécution avec un budget souple de 270 secondes pour rester sous le maxDuration de 300 s de la fonction serverless. Chaque réponse inclut un bloc « adaptive » avec compteurs d'itérations, joueurs interrogés et nombres par mode, pour que tout comportement anormal du sampler reste observable en production.

Le Win Rate naïf (victoires / matchs) trompe sur les petits échantillons : un brawler à 3-0 sur une nouvelle carte affiche « 100 % WR » sans que cela signifie rien. BrawlVision utilise un lissage bayésien pour corriger cela et renvoyer un nombre comparable entre brawlers ayant des tailles d'échantillon très différentes.

La formule est WR_bayésien = (wins + α) / (battles + α + β), où α et β sont des hyperparamètres encodant une croyance préalable centrée sur 50 % de WR. En pratique α = β = 25, équivalent à « supposer 50 combats préalables 50/50 avant de voir les vraies données ». Un brawler à 3 wins et 0 losses passe de 100 % naïf à (3 + 25) / (3 + 50) = 52,8 %, beaucoup plus représentatif de l'état réel de l'échantillon.

À mesure que l'échantillon grandit, le poids du prior décroît : avec 1 000 combats et 530 wins, le WR bayésien est à (530 + 25) / (1 000 + 50) = 52,9 %, quasi identique au naïf 53,0 %. Le lissage ne « pénalise » que lorsque l'échantillon est réellement petit. C'est exactement la propriété voulue : pénaliser le bruit, pas le signal.

Le Comfort Score est la métrique maison de BrawlVision pour répondre à la question « avec quel brawler joues-tu vraiment mieux que la moyenne ? ». Ce n'est pas un Win Rate brut : il combine trois composantes avec des poids 60/30/10 pour couvrir différentes dimensions de la performance personnelle.

La composante principale (60 %) est le WR du joueur avec ce brawler, lissé bayésiennement comme le meta global, pour qu'un brawler joué peu de fois ne fausse pas le classement. La composante intermédiaire (30 %) est l'écart entre ce WR personnel et le WR meta du brawler en général : un joueur à 55 % sur SHELLY quand le meta global est à 48 % gagne plus de comfort qu'un joueur à 55 % sur un brawler dont le meta est 53 %, parce que la progression relative est plus grande.

La composante finale (10 %) est la fréquence d'usage normalisée : à conditions égales, jouer un brawler 100 fois compte plus que 10, parce que la régularité est récompensée. Les formules exactes et les poids vivent dans src/lib/analytics/compute.ts et s'appliquent identiquement à chaque appel d'endpoint, pour que le classement reste reproductible.

Chaque brawler public porte un indicateur de tendance « +X,Y% » ou « −X,Y% » qui mesure comment son WR meta a changé sur les 7 derniers jours par rapport aux 7 précédents (fenêtre totale de 14 jours). Le calcul tourne sur source=global avec un minimum de MIN_BATTLES_PER_TREND_WINDOW = 3 combats dans chaque moitié de la fenêtre — si l'une des deux moitiés n'atteint pas le seuil, nous renvoyons null et l'UI cache la flèche au lieu d'inventer un nombre à faible signal.

La tendance est précalculée toutes les six heures dans une petite table (public.brawler_trends, une ligne par brawler) via un job pg_cron. Le faire dans la base — plutôt que dans la réponse de l'endpoint — évite de scanner des dizaines de milliers de lignes de la fenêtre de 14 jours à chaque rafraîchissement ISR. Si la table précalculée a plus de 12 heures ou est vide, l'endpoint bascule vers une route inline paginée sur meta_stats qui renvoie la même réponse à un coût plus élevé. La pagination est requise parce que PostgREST tronque silencieusement les requêtes non paginées à 1 000 lignes, ce qui avait fait retourner null à la majorité des brawlers pour fausse insuffisance d'échantillon.

La logique vit dupliquée par design : une version TypeScript dans src/lib/brawler-detail/trend.ts (route détail) et une version SQL dans supabase/migrations/022_*.sql (route bulk). Les deux utilisent le même seuil, la même fenêtre et le même filtre source=global. Si elles divergent un jour, la page individuelle d'un brawler et la page agrégée afficheraient des nombres différents pour le même brawler, donc tout changement est appliqué aux deux.

La fréquence à laquelle une donnée est rafraîchie influence comment la lire, alors nous la documentons explicitement. Les pages statiques (celle-ci comprise) utilisent ISR (Incremental Static Regeneration) avec une revalidation de 24 heures. Les pages avec données dynamiques mettent en cache la réponse de l'API jusqu'à ce que le job pertinent l'invalide.

Brawlers, gadgets et star powers se synchronisent depuis l'API Supercell avec un cache serveur de 24 heures. Le meta-poll (données PRO) tourne toutes les 6 heures et produit des lignes meta_stats fraîches. La précalcul des tendances 7 jours tourne en pg_cron à « 17 */6 * * * » (minute 17 de toutes les six heures) pour ne pas entrer en conflit avec le meta-poll. La rotation in-game des événements se rafraîchit toutes les 30 minutes.

Les combats individuels d'utilisateurs premium ayant activé la sync sont téléchargés juste après chaque match dans une fenêtre glissante via le cron de sync. Une fois en base, ils alimentent meta_stats avec source=user et servent aux analyses privées de la section profil ; ils n'apparaissent jamais dans des agrégats publics et ne se mélangent jamais à source=global.