D-20260814-18｜玩家賽事歷史採有界 cold lazy pagination¶
背景與驅動力¶
單場查詢已能在 hot miss 後拉取 cold partition，但玩家最近賽事 API 只讀 hot，超出保留窗的結果會 靜默消失。若直接無界掃描所有季度，又會讓一次首頁請求的網路與記憶體成本隨歷史長度成長。
考慮過的選項¶
- 只顯示 hot：快速但會把資料保留窗誤當完整歷史，棄。
- 一次掃完全部 cold：結果完整但成本無界，且 pinning 缺塊會讓整頁長時間懸掛，棄。
- 有界分頁、明確 partial／failure 與可重試游標（採納）。
決定¶
- 先讀 hot，再按 quarter 由新到舊 lazy fetch cold；以
matchId去重，固定按finishedAt DESC, matchId ASC排序。 - 預設單頁 20、單頁上限 50、單次最多掃描 4 partitions，集中為具名參數並在 API 邊界 clamp。
- opaque cursor 綁定 PeerId；達頁面／掃描上限回
partial + nextCursor，不可靜默截斷。 - 區塊缺失時停在原 partition：有既有列為
partial，無列為failure；回報失敗 partition，retry 從同一位置續讀且不重複資料。 - online-ready 首頁是首個 UI consumer，呈現載入、部分、失敗、續載與重試四語文案；列可開啟既有 正式結果頁。本機測試結果不混入這份 ledger 歷史。
後果與影響¶
舊比賽不再因 hot window 靜默消失，單次 cold 成本仍有硬上限；pinning 暫時缺塊不會被誤判為歷史 到底。游標是 API 契約而非可供 UI 解讀的資料格式，未來可改內部編碼而不改頁面行為。