lolhelper

專案概述

針對英雄聯盟「競技場 Arena」與「海克斯大亂鬥 Mayhem」兩個模式的統計平台,pnpm + Turbo monorepo 架構,含 FastAPI 後端、Next.js 15 前端與 Electron 桌面端三個元件。後端以非同步 Python(SQLAlchemy 2 async + asyncpg + ARQ)實作 Match-V5 BFS 爬蟲,自寫雙層滑動視窗 token bucket 處理 Riot 速率限制,並以 Wilson 95% 信心區間下界作為排行指標、再依百分位指派 S/A/B/C/D 分級,避免小樣本灌水。前端走 App Router 提供 SEO 與 OP.GG 風英雄頁(augment / 裝備 / 核心組建 / 隊友搭配排行),全程 zh_tw 中文化。

關鍵亮點

• 自寫雙層滑動視窗 token bucket 速率限制器,同時管理 App 層(20/s + 100/120s)與 per-method × per-region 兩種 Riot 限速,BFS 爬蟲跨 4 個 region cluster 並行,單一 personal key 可達約 5 萬場/日。
• 以 Wilson 95% 信心區間下界作為排行指標,搭配百分位分級(S/A/B/C/D),解決『5/5=100% 勝率灌爆 800/1000=80%』的小樣本問題;設計取捨記錄於 ADR(對比 Bayesian shrinkage、min-sample 門檻等替代方案)。
• 非同步資料管線:ARQ cron 依優先級與時效性派發爬取任務(SELECT ... FOR UPDATE SKIP LOCKED 確保冪等),聚合層以原生 SQL UPSERT 在分割表(Alembic 分區 migration)上重算 augment / item 統計。
• 產品決策有真實洞察:因 Riot 永久封鎖 Mayhem/Brawl 的 Match-V5 API(連 OP.GG 都拿不到),規劃以 Electron 客戶端讀本機 LCU 上傳資料聚合,並另立 tos-compliance 文件逐項對應 Riot 第三方政策邊界。

技術棧

挑戰與取捨

最大難點是在 Riot personal key 嚴苛速率限制下,跨 region 高吞吐且不被封鎖地爬取資料 —— 解法是自寫複合滑動視窗 token bucket(以 asyncio.Lock 保護、計算各視窗 time_until_available 取最大值),並讓爬蟲依 region cluster 並行。第二是統計排行的公平性:刻意捨棄直覺的原始勝率,選用 Wilson 區間下界,並把『為何不用 Bayesian / Elo / min-sample』的取捨寫進 ADR。架構面的取捨包括選 ARQ 而非 Celery(輕量、async 原生)、聚合先用原生 SQL UPSERT 全量重算(MVP 階段夠快,留待資料成長後改增量),以及為被封鎖的 Mayhem 模式從「網站爬蟲」改採「本機 LCU 上傳」的資料來源策略,並主動處理對應的政策合規風險。