Como construímos cada estatística

Tudo que mostramos vem de três fontes que mantemos auditáveis: a API pública da Supercell (developer.brawlstars.com), a CDN do Brawlify (cdn.brawlify.com) e nosso próprio banco no Supabase, que persiste batalhas e agregados que a API oficial não expõe além das últimas 25 partidas por jogador.

A API da Supercell é a fonte canônica para dados estruturais — brawlers, gadgets, star powers, hypercharges, gears e rotação de eventos — mas deixa de fora campos críticos como imagens, raridade e descrições longas. Cruzamos esses campos com a CDN do Brawlify, que opera independentemente e às vezes atrasa de um a três dias em relação à Supercell. Quando detectamos um brawler novo na API oficial que ainda não existe no Brawlify, mantemos um mapa local de raridade (BRAWLER_RARITY_MAP) para que a página do brawler renderize certo no dia do lançamento.

Nosso banco guarda duas classes de linhas em meta_stats: source=user (batalhas reais de usuários premium que ativaram sync) e source=global (amostragem automática dos rankings PRO). Toda estatística pública do site é calculada filtrando por source=global, para que dados pessoais de qualquer usuário não vazem para páginas públicas.

A camada "PRO" do BrawlVision é um conjunto de agregados calculados sobre batalhas recentes dos melhores jogadores do mundo. A cada seis horas, um cron job (meta-poll) consulta os rankings oficiais da Supercell para onze países — os que concentram atividade competitiva — e constrói uma pool deduplicada de aproximadamente 2.100 jogadores únicos do top 200 de cada um.

Sobre essa pool aplicamos um sampler probabilístico para impedir que combinações (mapa, modo) populares dominem o dataset e mascarem as raras. A probabilidade de aceitar uma batalha individual é p = min(1, (minLive + 1) / (current + 1)), onde minLive é a contagem da combinação menos representada e current a da combinação da batalha candidata. Combinações sub-amostradas recebem mais peso; as saturadas param de crescer.

O cron itera até META_POLL_MAX_DEPTH = 1.000 jogadores por execução com orçamento flexível de 270 segundos para ficar dentro do maxDuration de 300 s da função serverless. Cada resposta inclui um bloco "adaptive" com contagens de iterações, jogadores consultados e contagens por modo, para que qualquer comportamento anormal do sampler fique observável em produção.

Win Rate ingênuo (vitórias / partidas) engana em amostras pequenas: um brawler 3-0 num mapa novo mostra "100 % WR" sem que isso signifique nada. O BrawlVision usa smoothing bayesiano para corrigir e devolver um número comparável entre brawlers com tamanhos de amostra muito diferentes.

A fórmula é WR_bayesiano = (wins + α) / (battles + α + β), onde α e β são hiperparâmetros que codificam uma crença prévia centrada em 50 % de WR. Na prática α = β = 25, equivalente a "assumir 50 batalhas prévias 50/50 antes de ver os dados reais". Um brawler com 3 wins e 0 losses sai de 100 % ingênuo para (3 + 25) / (3 + 50) = 52,8 %, muito mais representativo do estado real da amostragem.

À medida que a amostra cresce, o peso do prior decai: com 1.000 batalhas e 530 wins, o WR bayesiano fica em (530 + 25) / (1.000 + 50) = 52,9 %, quase idêntico ao ingênuo 53,0 %. O smoothing só "dói" quando a amostra é genuinamente pequena. É exatamente a propriedade desejada: penalizar ruído, não sinal.

O Comfort Score é a métrica própria do BrawlVision para responder "com qual brawler você joga melhor que a média?". Não é um Win Rate puro: combina três componentes com pesos 60/30/10 cobrindo dimensões diferentes do desempenho pessoal.

O componente principal (60 %) é o WR do jogador com aquele brawler, com smoothing bayesiano como o meta global, para que um brawler pouco jogado não dominhe o ranking. O componente intermediário (30 %) é a diferença entre esse WR pessoal e o WR meta do brawler no geral: um jogador com 55 % em SHELLY quando o meta global está em 48 % ganha mais comfort que outro com 55 % num brawler com meta 53 %, porque o ganho relativo é maior.

O componente final (10 %) é a frequência de uso normalizada: tudo igual, jogar um brawler 100 vezes vale mais que 10, porque consistência é recompensada. As fórmulas exatas e os pesos vivem em src/lib/analytics/compute.ts e se aplicam idênticos em cada chamada de endpoint, para que o ranking seja reproduzível.

Cada brawler público tem um indicador de tendência "+X,Y%" ou "−X,Y%" que mede como o WR meta mudou nos últimos 7 dias em comparação aos 7 anteriores (janela total de 14 dias). O cálculo roda em source=global com mínimo de MIN_BATTLES_PER_TREND_WINDOW = 3 batalhas em cada metade da janela — se uma das metades não atingir o limite, retornamos null e a UI esconde a seta em vez de inventar um número de baixo sinal.

A tendência é pré-calculada a cada seis horas numa tabela pequena (public.brawler_trends, uma linha por brawler) por um job pg_cron. Fazer isso no banco — em vez da resposta do endpoint — evita escanear dezenas de milhares de linhas da janela de 14 dias a cada refresh ISR. Se a tabela pré-calculada tiver mais de 12 horas ou estiver vazia, o endpoint cai numa rota inline paginada sobre meta_stats que retorna a mesma resposta com custo maior. A paginação é necessária porque o PostgREST trunca silenciosamente queries não paginadas a 1.000 linhas, o que uma vez fez a maioria dos brawlers retornar null por subamostragem falsa.

A lógica vive duplicada por design: uma versão TypeScript em src/lib/brawler-detail/trend.ts (rota detalhe) e uma SQL em supabase/migrations/022_*.sql (rota bulk). Ambas usam o mesmo limiar, a mesma janela e o mesmo filtro source=global. Se divergirem, a página individual e a agregada mostrariam números diferentes para o mesmo brawler, então qualquer mudança vai nas duas.

A frequência com que um dado é atualizado afeta como interpretá-lo, então documentamos explicitamente. Páginas estáticas (incluindo esta) usam ISR (Incremental Static Regeneration) com revalidação de 24 horas. Páginas com dados dinâmicos cacheiam a resposta da API até que o job relevante invalide.

Brawlers, gadgets e star powers sincronizam da API Supercell com cache de servidor de 24 horas. O meta-poll (dados PRO) roda a cada 6 horas e gera linhas meta_stats frescas. A pré-computação de tendências 7d roda em pg_cron a "17 */6 * * *" (minuto 17 de cada sexta hora) para não colidir com o meta-poll. A rotação de eventos do jogo atualiza a cada 30 minutos.

Batalhas individuais de usuários premium que ativaram sync são baixadas logo após cada partida numa janela móvel via cron de sync. Uma vez no nosso banco, alimentam meta_stats com source=user e são a base das análises privadas da seção de perfil; nunca aparecem em agregados públicos e nunca se misturam com source=global.