核心邏輯與 API (Core Logic & API)

📡 API 層 (js/api.js)

api.js 模組負責所有與後端的通訊。

fetchLatest()

• 用途：獲取市場持倉的當前快照。
• 設計哲學：Fail-Safe (故障安全)。如果網絡請求失敗，它會返回 null 而不是拋出錯誤導致頁面崩潰。這樣 UI 層可以簡單地忽略這次更新，保持顯示舊數據，直到下次成功。

fetchHistory(range)

• 用途：獲取用於繪圖的歷史數據。
• 客戶端聚合 (Client-Side Aggregation)：
  • 後端 API 可能只傳回單一資產數據。
  • 策略：為了減輕伺服器壓力，我們在前端進行「核心資產 (Hedge)」的聚合計算（例如合併 BTC 與 ETH）。
  • 這種「瘦後端，胖前端」模式有效降低了 API 延遲與運算成本。

🧮 數據工具 (js/utils.js)

這個模組負責處理原始數據的標準化與清洗。

extractData(rawData, assetType)

最關鍵的解析函數，負責：

• 命名對齊：處理後端 API 混用的 longVol 與 long_vol。
• 時區修正：確保時間戳在不同設備上顯示一致。

formatVolume(v)

將長數字轉換為易讀的「億/萬」格式，並保留中文單位，提升中文使用者的直觀感受。

⚙️ 配置與狀態管理 (Configuration)

設定檔 (js/config.js)

專案的控制中心，所有全域常數如 API_BASE, POLL_INTERVAL, ALERT_DURATION 都定義於此，方便統一管理。

Local Storage (使用者偏好)

我們將用戶的個人設置保存在瀏覽器的 localStorage 中：

• hyper_muted: 記憶靜音狀態。
• hyper_range: 記憶圖表時間範圍。

運行時狀態 (app.js)

以下變數在內存中維護，每次刷新重置：

• currentAsset: 當前選中的資產。
• allData: 最新的數據快照。
• historyData: 已下載的圖表歷史緩存，避免重複請求。