Come costruiamo ogni statistica

Tutto ciò che mostriamo proviene da tre fonti che manteniamo verificabili: l'API pubblica di Supercell (developer.brawlstars.com), il CDN di Brawlify (cdn.brawlify.com) e il nostro database Supabase, che persiste battaglie e aggregati che l'API ufficiale non espone oltre le ultime 25 partite per giocatore.

L'API di Supercell è la fonte canonica per i dati strutturali — brawler, gadget, star power, hypercharge, gear e rotazione eventi — ma omette campi critici come immagini dei brawler, rarità e descrizioni lunghe. Incrociamo questi campi con il CDN di Brawlify, che opera in modo indipendente e a volte ritarda da uno a tre giorni rispetto a Supercell. Quando rileviamo un brawler nuovo nell'API ufficiale che ancora non esiste su Brawlify, manteniamo una mappa locale di rarità (BRAWLER_RARITY_MAP) perché la pagina del brawler renderizzi correttamente al lancio.

Il nostro database memorizza due classi di righe in meta_stats: source=user (battaglie reali di utenti premium che hanno attivato la sync) e source=global (campionamento automatico delle classifiche PRO). Ogni statistica pubblica è calcolata filtrando su source=global, per evitare che dati personali di un singolo utente trapelino nelle pagine pubbliche.

Il livello "PRO" di BrawlVision è un insieme di aggregati calcolati sulle battaglie recenti dei migliori giocatori al mondo. Ogni sei ore un cron job (meta-poll) interroga le classifiche ufficiali di Supercell per undici paesi — quelli che concentrano l'attività competitiva — e costruisce una pool dedduplicata di circa 2.100 giocatori unici dal top 200 di ciascuno.

Su questa pool applichiamo un sampler probabilistico per impedire che le combinazioni (mappa, modalità) popolari dominino il dataset e mascherino quelle rare. La probabilità di accettare una battaglia individuale è p = min(1, (minLive + 1) / (current + 1)), dove minLive è il conteggio della combinazione meno rappresentata e current quello della combinazione candidata. Le combinazioni sotto-campionate ricevono più peso; quelle sature smettono di crescere.

Il cron itera fino a META_POLL_MAX_DEPTH = 1.000 giocatori per esecuzione con budget flessibile di 270 secondi per restare entro il maxDuration di 300 s della funzione serverless. Ogni risposta include un blocco "adaptive" con conteggi di iterazioni, giocatori interrogati e conteggi per modalità, perché qualsiasi comportamento anomalo del sampler resti osservabile in produzione.

Il Win Rate ingenuo (vittorie / partite) inganna su campioni piccoli: un brawler 3-0 su una mappa nuova mostra "100 % WR" senza che significhi nulla. BrawlVision usa lo smoothing bayesiano per correggere e restituire un numero comparabile tra brawler con dimensioni di campione molto diverse.

La formula è WR_bayesiano = (wins + α) / (battles + α + β), dove α e β sono iperparametri che codificano una credenza precedente centrata su 50 % di WR. In pratica α = β = 25, equivalente a "assumere 50 battaglie precedenti 50/50 prima di vedere i dati reali". Un brawler con 3 wins e 0 losses passa da 100 % ingenuo a (3 + 25) / (3 + 50) = 52,8 %, molto più rappresentativo dello stato reale del campionamento.

Man mano che il campione cresce, il peso del prior decade: con 1.000 battaglie e 530 wins, il WR bayesiano è a (530 + 25) / (1.000 + 50) = 52,9 %, quasi identico all'ingenuo 53,0 %. Lo smoothing "fa male" solo quando il campione è genuinamente piccolo. È esattamente la proprietà desiderata: penalizzare il rumore, non il segnale.

Il Comfort Score è la metrica interna di BrawlVision per rispondere "con quale brawler giochi davvero meglio della media?". Non è un Win Rate puro: combina tre componenti con pesi 60/30/10 per coprire dimensioni diverse della performance personale.

La componente principale (60 %) è il WR del giocatore con quel brawler, smoothed bayesianamente come il meta globale, perché un brawler giocato di rado non distorca il ranking. La componente intermedia (30 %) è la differenza tra questo WR personale e il WR meta del brawler in generale: un giocatore al 55 % su SHELLY quando il meta globale è al 48 % guadagna più comfort di uno al 55 % su un brawler con meta 53 %, perché il guadagno relativo è maggiore.

La componente finale (10 %) è la frequenza d'uso normalizzata: a parità di tutto il resto, giocare un brawler 100 volte conta più che 10, perché la coerenza viene premiata. Le formule esatte e i pesi vivono in src/lib/analytics/compute.ts e si applicano identicamente a ogni chiamata di endpoint, perché il ranking sia riproducibile.

Ogni brawler pubblico ha un indicatore di tendenza "+X,Y%" o "−X,Y%" che misura come il suo WR meta è cambiato negli ultimi 7 giorni rispetto ai 7 precedenti (finestra totale di 14 giorni). Il calcolo gira su source=global con un minimo di MIN_BATTLES_PER_TREND_WINDOW = 3 battaglie in ciascuna metà della finestra — se una delle due metà non raggiunge la soglia, restituiamo null e l'UI nasconde la freccia invece di inventare un numero a basso segnale.

La tendenza è precalcolata ogni sei ore in una piccola tabella (public.brawler_trends, una riga per brawler) tramite un job pg_cron. Farlo nel database — invece che nella risposta dell'endpoint — evita di scansionare decine di migliaia di righe della finestra 14 giorni a ogni refresh ISR. Se la tabella precalcolata è vecchia più di 12 ore o vuota, l'endpoint cade su una rotta inline paginata su meta_stats che restituisce la stessa risposta a costo maggiore. La paginazione è necessaria perché PostgREST tronca silenziosamente le query non paginate a 1.000 righe, cosa che una volta ha fatto ritornare null alla maggior parte dei brawler per falsa sotto-campionatura.

La logica vive duplicata by design: una versione TypeScript in src/lib/brawler-detail/trend.ts (rotta dettaglio) e una SQL in supabase/migrations/022_*.sql (rotta bulk). Entrambe usano la stessa soglia, la stessa finestra e lo stesso filtro source=global. Se divergessero, la pagina individuale e quella aggregata mostrerebbero numeri diversi per lo stesso brawler, quindi ogni cambio si applica a entrambe.

Quanto spesso un dato si aggiorna influenza come interpretarlo, quindi lo documentiamo esplicitamente. Le pagine statiche (questa inclusa) usano ISR (Incremental Static Regeneration) con revalidazione di 24 ore. Le pagine con dati dinamici cachano la risposta dell'API finché il job rilevante non la invalida.

Brawler, gadget e star power si sincronizzano dall'API Supercell con cache server di 24 ore. Il meta-poll (dati PRO) gira ogni 6 ore e produce righe meta_stats fresche. La precomputazione delle tendenze 7d gira in pg_cron a "17 */6 * * *" (minuto 17 di ogni sesta ora) per non scontrarsi con il meta-poll. La rotazione eventi in-game si rinfresca ogni 30 minuti.

Le battaglie individuali di utenti premium con sync attiva sono scaricate subito dopo ogni partita in una finestra mobile via cron di sync. Una volta nel nostro database, alimentano meta_stats con source=user e sono la base delle analisi private nella sezione profilo; non appaiono mai in aggregati pubblici e non si mescolano mai a source=global.