專案資訊

專案名稱

黃金儀表板｜XAUUSD 資料更新與 Fail-soft 介面

專案簡介

黃金儀表板是一個以市場研究為導向的 XAUUSD Web 儀表板，將價格、不同時間週期的 K 線、黃金新聞、市場背景與技術分析整理在同一個介面中。

這次分享的重點不是如何畫出圖表，而是當某一個資料來源暫時變慢或失敗時，如何只處理受影響的區塊，並保留其他仍然可以閱讀的內容。

開發狀態

Beta 測試中，持續改善資料更新、錯誤狀態、快取策略與多語言介面。

必要連結

專案頁面：https://copi-tools.com/zh-hant/gold-dashboard/

技術實作內容

1. 開發動機

最初的想法很直覺：使用計時器定期取得新資料，再把舊的 HTML 替換掉。

但是，當頁面同時包含價格、K 線、新聞、市場分析與交易者觀點時，整頁更新會產生幾個問題：

• 使用者選擇的時間週期可能被重設
• 圖表的縮放與捲動位置可能跳回最新 K 線
• 新聞 API 變慢時，可能拖延價格區塊的更新
• 單一 request 失敗時，其他正常區塊也可能被清空
• 使用者看不到的區塊仍然持續發送請求

因此，我希望讓每個資料區塊獨立更新，同時在新資料尚未確認有效以前，不要破壞目前仍然可讀的畫面。

2. 技術架構

這個專案主要分成以下幾層：

• MQL5：從 MT5 取得 XAUUSD 行情與 K 線資料並送出。
• Windows Server VPS：執行 Python 排程、資料轉換與分析工作。
• WordPress plugin：輸出初始 HTML、提供 REST API 並保存資料。
• JavaScript：負責圖表、局部 fragment 更新、狀態提示與使用者操作。

資料流程大致如下：

1. MQL5 將價格與 K 線資料送到 WordPress 的 gold-bars API。
2. VPS 上的 Python 工作處理分析資料，驗證結果後送到 gold-analysis API。
3. WordPress 在第一次載入時輸出有意義的 HTML。
4. JavaScript 依照各區塊的更新週期，取得並替換需要更新的 fragment。
5. 當更新失敗時，保留該區塊最後一次正常的內容，並顯示目前狀態。

3. 核心邏輯與技術挑戰

先取得並驗證，再替換畫面

前端更新時，不能在確認新資料以前就先清空目前的內容。

目前採用的處理順序是：

1. 發出該區塊的資料請求。
2. 檢查 HTTP response 和基本資料結構。
3. 在暫存區完成 fragment 的解析與渲染。
4. 確認內容有效後，才替換畫面上可見的區塊。
5. 如果 request 或渲染失敗，保留目前的內容並顯示更新延遲狀態。

這個順序可以避免暫時性的網路錯誤，直接變成空白卡片。

區分快取、延遲與無法使用

「資料比較舊」和「完全沒有資料」是不同的狀態。

例如，幾分鐘前成功取得的 K 線資料，可能仍然比空白圖表更有參考價值。因此，介面需要區分以下狀態：

• 最近更新：資料在預期時間內更新
• 使用快取：最新請求未完成，但仍有上一次有效資料
• 更新延遲：資料來源預期會更新，但目前尚未完成
• 暫時無法使用：沒有任何可安全顯示的資料
• 資料無效：收到回應，但未通過欄位或型別檢查

保留快取資料不代表要假裝它是即時資料。畫面上仍然需要標示更新時間或目前狀態。

失敗後不能立即無限重試

如果 API 失敗後每幾秒立刻重試，可能增加伺服器負擔，也會讓上游服務的問題更加嚴重。

因此，更新控制器需要記錄每個區塊的重試次數，逐漸增加重試間隔；成功更新後，再將重試計數歸零。當同一個區塊已經在載入中時，也不能因為另一個計時器觸發而重複發送 request。

圖表更新不能破壞使用者目前的位置

使用者可能正在查看較早的 K 線，而不是最新價格。如果每次更新都重新載入完整歷史資料，圖表的縮放、捲動位置與使用者目前查看的區域可能被重設。

目前的方向是：

• 已載入的歷史 K 線先保留在瀏覽器記憶體中
• 只取得最近一段資料
• 依照時間戳記合併新的 K 線
• 保留目前選擇的 timeframe
• 使用者正在追蹤最新資料時，才移動到最新端點

這樣可以讓背景更新與使用者正在閱讀的內容互相配合。

4. 解決方案

我把每個可更新區塊視為一個獨立的資料資源，並為它保留簡單的狀態：

• idle：等待下一次更新
• loading：正在取得資料
• success：已取得並通過驗證
• stale：目前顯示的是較舊但仍可使用的內容
• failed：最新請求失敗，等待重試
• paused：區塊目前不可見，暫停背景更新

更新成功時，只替換該區塊的內容；更新失敗時，保留最後一次正常結果，記錄錯誤，並顯示「更新延遲」或「使用快取資料」等簡短訊息。

這種 fail-soft 設計的重點不是讓所有資料看起來都像即時更新，而是讓使用者知道目前哪些資料有效、哪些資料可能較舊，以及哪一個區塊正在等待更新。

5. 實作上的技術挑戰

不同資料來源的更新時間不同

價格與目前 K 線可能需要較頻繁更新，新聞與市場背景則可以使用較長的週期。每個區塊需要獨立的計時器與快取策略，不能只設定一個全頁更新時間。

初始 HTML 與 JavaScript 更新要保持一致

第一次載入由 WordPress 輸出有意義的 HTML，JavaScript 載入後再加入互動與 fragment 更新。兩者需要使用一致的狀態標籤與資料格式，避免首次顯示和後續更新出現不同的錯誤處理方式。

錯誤狀態也要支援多語言

Update delayed、Using cached data 和 Currently unavailable 不只是後端錯誤代碼，也會直接出現在使用者介面中。因此，英文、繁體中文與越南文介面需要使用一致的狀態意義，再分別處理文字翻譯。

目前的限制與後續方向

目前仍有幾個部分需要改善：

• 為每個 fragment response 建立更明確的 schema 檢查
• 讓重試、取消與重複 request 更容易在除錯時觀察
• 統一 MQL5、Python、WordPress 與 JavaScript 的錯誤代碼
• 建立圖表縮放與捲動位置維持的測試案例
• 讓快取資料的年齡與資料狀態更容易被使用者理解
• 強化 VPS 工作失敗時的通知與重試機制

黃金儀表板是市場資訊整理與技術研究介面，不是交易訊號工具，也不執行自動下單。價格、新聞與分析資料可能存在延遲或缺漏，內容不構成投資建議，也不保證任何交易結果。

結語

局部更新不只是把整頁更新拆成幾個 request。它還需要處理資料驗證、快取、重試、使用者目前的圖表位置，以及部分資料來源失敗時的畫面狀態。

在這個專案中，我把 MQL5、VPS Python、WordPress REST API 與前端 JavaScript 的責任分開，讓每個資料區塊可以獨立更新與失敗。核心原則是：替換畫面前先驗證，暫時失敗時保留最後一次正常狀態，並清楚告知使用者資料是否可能較舊。

如果你也在開發需要串接多個資料來源的 dashboard，想請教大家通常如何處理以下問題：

• API 失敗時，你會保留舊內容多久？
• 你會如何避免重試造成重複 request？
• 圖表背景更新時，如何維持使用者目前的縮放與閱讀位置？