League API 工程 (League API Engineering)
請選擇並只使用一種主要模式。如果是混合請求，請在開始前說明主導模式及次要交付項目。
| 模式 (Mode) | 使用時機 (Use for) | 必要結果 (Required result) |
|---|---|---|
implement | 新增或修改資料整合 | 來源決策 → 轉接器合約 → 清理過的 Fixtures/測試 → 實作計畫或程式碼 → 閘門檢查 |
audit | 評估現有整合 | 盤點 → 證據標籤 → 風險矩陣 → 按來源排序的優先修正項目 |
debug | 處理失敗或誤導的整合 | 重現步驟 → 失敗分類 → 傳輸/結構/快取/備援檢查 → 修正證明 |
research | 選擇資料來源或查詢當前事實 | 附有日期的證據圖 → 來源評估 → 決策 |
policy | 判斷資料使用或產品行為是否允許 | 產品/資料審查 → 政策閘門 → 決定為「允許」、「受限」或「禁止」 |
非協商閘門 (Non-negotiable gates)
不要繞過失敗的閘門，而是拒絕該設計：
- 金鑰與隱私 (Secrets and privacy): 絕不內嵌、持久化或記錄 Riot API 金鑰、LCU 憑證、Bearer Token、Cookie、個人識別資訊 (PII) 或真實玩家歷史。
- 本地客戶端安全 (Local-client safety): 禁止注入、掛鉤、處理程序記憶體存取、記憶體掃描、反作弊繞過、隱藏狀態提取，或宣稱獨占全螢幕控制。迴圈回送 (Loopback) 憑證放寬僅限於明確綁定到
127.0.0.1或localhost的客戶端；絕不能用於遠端 HTTPS。 - 權威與條款 (Authority and terms): 不要將未記錄的端點或提供者描述為官方支援。請在使用前驗證適用的條款、歸屬、重新分發、驗證及速率限制條件。
- 備援真實性 (Fallback truthfulness): 備援方案必須保留母體、範圍、新鮮度、版本、地區、佇列及來源語意。本質上不同的資料應視為獨立的結果，而不是靜默的替代品。
- 不支援的請求 (Unsupported requests): 請勿憑空捏造 MMR/ELO 估算、推斷隱藏狀態，或揭露無法取得的玩家資訊。請針對此類請求回傳
policy_blocked或unsupported_context，並附上限制條件說明。
來源決策工作流程 (Source-decision workflow)
- 分類請求的資料：本地連線階段、進行中的對戰、靜態/版本化資料、遠端帳號/對戰/排名資料、彙總趨勢資料，或是不支援/隱藏狀態。
- 從
source-decision-tree.md開始；根據權威性、存取方式、路由、新鮮度、穩定性、版本涵蓋範圍、延遲、條款、隱私、歸屬、速率限制及失敗行為來選擇候選來源。 - 先套用硬性閘門再進行評分。需要內嵌生產金鑰、不安全的本地存取、禁止的資料、未經審查的重新分發，或不相容備援方案的來源，將被拒絕。
- 為每項實質聲明記錄一個證據類別：
verified-current: 直接由附有日期的權威來源或當前的可重現觀察結果支援；observed-undocumented: 重現的行為，但未獲得權威來源保證；historical: 過去有文件記錄或被觀察到，但不能假定當前仍有效；inference: 經推理得出的結論，需要在投入生產前進行驗證。
- 使用
adapter-contract.md撰寫或更新轉接器合約，然後採用快取/備援、測試以及金絲雀 (Canary) 控制機制。
失敗詞彙 (Failure vocabulary)
使用一個主要的錯誤類別，並分別保留未經處理但已清理的診斷資訊：offline、unauthorized、rate_limited、not_found、no_data、unsupported_context、transport、http_status、parse、schema_drift 或 policy_blocked。
絕不要盲目重試 unauthorized、policy_blocked、parse 或 schema_drift。請參閱 caching-and-fallbacks.md。
審計輸出合約 (Audit output contract)
一份審計報告應產出一個附有日期的工件，包含以下內容：
- 範圍、資料類別及轉接器盤點；
- 來源/端點對應圖，包含權威性、穩定性、證據類別及條款審查日期；
- 憑證、隱私、本地存取、路由、版本控制及歸屬方面的發現；
- 快取、無資料、重試、結構漂移及備援相容性的發現；
- 一個風險矩陣：嚴重程度、可能性、受影響的行為、證據及具體補救措施；
- 按優先順序排列的修正項目、被封鎖的項目及驗證標準。
請勿將假設標記為已驗證。請勿僅僅因為一個來源能成功運作一次就稱其為安全的。
漸進式揭露 (Progressive disclosure)
- 官方及本地來源選擇：
riot-web-apis.md、lcu.md、live-client-data.md、data-dragon.md、communitydragon.md。 - 外部來源及產品政策：
third-party-providers.md、policy-and-product-gates.md。 - 工程控制項：
adapter-contract.md、caching-and-fallbacks.md、testing-and-canaries.md。 - 選擇性的有限範圍範例：
case-study-lolcompanion.md。
如果套件根目錄中存在驗證器，請在發佈前從該目錄執行 python scripts/validate.py .。