Dashboard 與介面導覽
完整走過 Stable 2.0.55 可到達的外殼與 Dashboard：onboarding、三種 Widget、自訂排序、統計與 Bridge cards、批次控制、快速導覽、健康刷新、語言與主題、System Logs，以及版本 mismatch 與 WebSocket 警告。
先認識固定外殼與可到達頁面
Stable 2.0.55 的 React 介面以頂端 App Bar、主要內容、footer 與右下角語言切換器組成。桌面寬度會直接顯示導覽 icon；較窄畫面改由右側 Drawer 呈現相同項目。點 logo 或 Dashboard 回到根路由 /。頂端還有 Status Indicator、深淺色切換與 System Logs 入口。
| 路由 | 頁面 | 主要用途 |
|---|---|---|
/ | Dashboard | 總覽、onboarding、Widget 與常用操作 |
/bridges | Bridges | 完整 Bridge 清單、建立、匯入匯出與個別操作 |
/bridges/create | Create Bridge | 範本加完整表單／JSON 建立 |
/bridges/area-setup | Area Setup | 按 HA Area 批次建立 Bridge |
/devices | Devices | 搜尋實體、查看映射與失敗項目 |
/standalone-devices | Standalone Devices | 檢視 Stable 中仍有實驗性邊界的 Server Mode 裝置 |
/network-map | Network Map | Bridge、Fabric 與拓撲視圖 |
/health | Health | 詳細服務、Controller、網路與裝置健康診斷 |
/startup | Startup Order | Bridge 啟動優先序 |
/labels | Filter Reference | HA 標籤與區域參考 |
/lock-credentials | Lock Credentials | 門鎖憑證管理；敏感內容不可截圖或分享 |
/plugins | Plugins | 實驗性 Plugin 管理與狀態 |
/settings | Settings | 系統設定、更新與其他維運入口 |
未知路由會落到 Not Found。介面「可到達」只表示 Stable 2.0.55 註冊了頁面，不代表頁面內每個功能成熟度都相同。例如 Plugins 與 Standalone Devices 路由在 Stable，但相關功能仍須另外標示 experimental-in-Stable。
沒有 Bridge 時的 onboarding
Dashboard 先呼叫詳細 health API。若尚無 Bridge，頁面不顯示可自訂 Widget，而是顯示 welcome card，提供三條建立路徑：Bridge Wizard、Setup by Area 與 Manual Setup，另有外部 Documentation 連結。這三條路徑不是成熟度等級，而是不同設定工作流。
| 入口 | 適合情境 | 建立前要知道 |
|---|---|---|
| Bridge Wizard | 希望由範本、Controller profile 與六階段引導開始 | 最後仍要核對 filter、port 與 network preflight |
| Setup by Area | HA Area 已整理好，想一個 Area 建一座 Bridge | 會批次建立多座、port 逐一增加；先確認資源與 Controller 規模 |
| Manual Setup | 需要完整 schema、精細 filter 或 JSON | 欄位較多，需自行理解 identity、session 與進階 flag |
建立至少一座 Bridge 後，Dashboard 切換為 Widget 版面。當至少一個 Fabric 出現時，會顯示首次成功訊息；關閉後瀏覽器在 local storage 記住 hamh-first-success-dismissed。這只是一個介面提示，不是配對驗證或 Controller 相容性保證。
先看頂端 Status
把指標展開，確認版本、uptime、HA connection 與 WebSocket。沒有 Bridge 時顯示 No Bridges 是預期狀態。
選擇工作流
一般首次建立可按 Bridge Wizard；HA Area 規劃完整才選 Setup by Area；需要精細 schema 才選 Manual Setup。
建立後回 Dashboard
確認 welcome card 被 Stats、Bridges 與 Quick Navigation 取代，Bridge 數與你剛建立的數量一致。
只用狀態驗證，不急著配對
先確認 HA Online、Bridge running 與 device count 合理，再進入後續 commissioning。不要在介面導覽階段公開任何配對資料。
顯示、排序與 Reset 三種 Widget
有 Bridge 時，Dashboard 標題右側出現 Customize Dashboard 的調整按鈕。對話框固定管理三個 Widget：Status Overview、Bridges、Quick Navigation。眼睛按鈕切換顯示，向上／向下按鈕交換順序，Reset 還原預設順序與全部顯示，Done 關閉對話框。
| Widget ID | 介面名稱 | 內容 |
|---|---|---|
stats | Status Overview | Bridge、Device、Fabric 與 HA connection 四張統計卡 |
bridges | Bridges | 建立入口、批次啟停／重啟與按 priority 排序的 mini cards |
quickNav | Quick Navigation | 常用頁面的捷徑 cards |
設定保存在目前瀏覽器的 local storage key hamh-dashboard-widgets。它不是後端 Bridge configuration，也不跟著 Matter Hub backup 在所有瀏覽器同步。程式載入時會忽略未知 Widget，並把新加入的已知 Widget補回 order；損壞的 local storage 則回到 default。
開啟 Customize Dashboard
回到 Dashboard 根頁，按標題右側調整圖示。若圖示不存在，先確認至少有一座 Bridge。
隱藏非必要區塊
按 Widget 左側眼睛，例如維運螢幕可只保留 Status Overview 與 Bridges。隱藏不會停止 health refresh 或 Bridge。
調整閱讀順序
用右側 Move up／Move down 把最常看的區塊移到前面；第一項不能再上移，最後一項不能再下移。
測試 Reset
若版面與預期不同，按 Reset 還原
stats → bridges → quickNav並全部顯示，再按 Done。這不會修改後端資料。
Stats、Status Indicator 與兩種 refresh 節奏
Status Overview 的四張卡來自 api/health/detailed：Bridge 總數（附 running／failed 摘要）、所有 Bridge device count 加總、Fabric count 加總、HA connection 與 uptime。Dashboard 進入後每 15 秒刷新一次；頂端 Status Indicator 另呼叫 api/health，每 30 秒刷新。因此短時間內兩處顯示可能不同步，不應立刻推論資料損壞。
| 卡片／指標 | 點擊行為 | 如何解讀 |
|---|---|---|
| Bridges | 前往 Bridges 頁 | 總數與 running／failed；不是 Controller 數 |
| Devices | 前往 Devices；failed chip 直達 ?showFailed=true | 映射後 device count 加總；failed 應進一步看原因 |
| Fabrics | 前往 Network Map | 各 Bridge fabrics 加總；不代表相同 Controller 功能支援 |
| HA Connection | 無 | Online/Offline 與應用 uptime；只代表 HA 服務連線層 |
| 頂端 Status | hover/tap tooltip | 版本、uptime、Bridge running、HA 與 WebSocket 綜合狀態 |
Status icon 在 health error/unhealthy，或任一 Bridge stopped／failed 時為 error。Health 仍 healthy 但 WebSocket 斷線，或 healthy 且沒有 Bridge／不是全部 running 的 fallback，才可能是 warning；全部 running 且連線健康才是 success。沒有 Bridge 時也會顯示對應狀態，而不是假裝「全部執行」。
Bridge mini cards、排序與 bulk actions
Bridges Widget 上方有 Bridge Wizard、Create Bridge、Area Setup，並提供 Start All、Stop All、Restart All。批次操作進行中會停用按鈕，程式還用 guard 避免重複點擊；完成後立刻重抓 health。這些按鈕是實際後端操作，不是只改 Dashboard 顯示。
mini cards 依 priority 由小到大排序，缺值以 100 處理，畫面上的 #1、#2 是當前顯示順序。每張卡顯示 icon、名稱、running/stopped/failed、device count、非零 Fabric count，若有 failed entities 會顯示警告數量。點卡片進入 Bridge details。
| 操作 | 影響 | 安全用法 |
|---|---|---|
| Start All | 嘗試啟動所有 Bridge | 維護完成後使用，觀察 failed 而非連點 |
| Stop All | 停止所有 Bridge，Controller 會失去服務 | 只在已通知的維護時段使用 |
| Restart All | 所有 Bridge 會短暫中斷並重建服務 | 不應作為單一裝置故障的第一步 |
| 點 mini card | 只導覽到該 Bridge details | 先看個別 statusReason、failed entities 與 Controller health |
Quick Navigation 的九個捷徑
Quick Navigation 不是完整頂端導覽的替代，而是把日常維運最常用的九個目標做成 cards：Bridges、Area Setup、Devices、Network Map、Health、Startup Order、Lock Credentials、Filter Reference、Settings。Standalone Devices 與 Plugins 仍可從頂端導覽到達，但沒有出現在這組 quick cards。
| 捷徑 | 你通常在何時使用 |
|---|---|
| Bridges | 檢查完整清單、匯入匯出或新增 Bridge |
| Area Setup | HA Area 整理完成後批次建立 |
| Devices | 搜尋映射、查看 failed devices |
| Network Map | 理解 Bridge 與 Fabric 拓撲 |
| Health | 查看 HA、Bridge、Controller、session 與 network diagnostics |
| Startup Order | 管理多 Bridge 的 priority |
| Lock Credentials | 管理敏感門鎖功能；操作前先讀安全章節 |
| Filter Reference | 核對 Area／Label 識別與篩選規則 |
| Settings | 系統、更新、復原及其他全域設定 |
若你把 Quick Navigation Widget 隱藏，頂端導覽仍可使用；行動版要先開右側 Drawer。介面寬度不同不代表功能被移除。
繁體中文、其他語言與 light/dark
右下角固定的 Language 按鈕開啟語言清單；Stable 2.0.55 內建 English、Deutsch、Français、Español、Italiano、Magyar、簡體中文、繁體中文、日本語、ไทย、Svenska、Türkçe、Русский、Português (Brasil)。選擇「繁體中文」對應 zh-TW。切換只影響介面翻譯，不改 HA 語言、Bridge identity 或 Controller 顯示名稱。
頂端 moon/sun icon 在 dark 與 light 間切換。桌面版直接顯示 icon；行動版在 Drawer 中顯示「Dark Mode」或「Light Mode」。主題是瀏覽器 UI 偏好，不改 Bridge、Device 或 log 內容。
切換繁體中文
按右下角 Language 按鈕，在清單選「繁體中文」。若部分字串仍是英文，這可能是該固定版本翻譯尚未覆蓋，不代表後端版本錯誤。
選擇主題
桌面按頂端主題 icon；行動版開右側選單再選 Dark／Light Mode。確認對比與可讀性。
區分瀏覽器偏好與後端資料
換一個瀏覽器檢查時，語言、Widget 或主題可能不同。不要把這種差異當成 backup 遺失。
回報翻譯時移除敏感內容
只提供固定版本、字串位置與期望譯文；不要附完整 System Logs、現場 URL 或配對畫面。
System Logs dialog：篩選、搜尋、刷新與清除
頂端 Bug Report icon 開啟 System Logs dialog。預設選取 error、warn、info，向 api/logs 要求最多 500 筆；可多選 error/warn/info/debug、輸入搜尋字串、手動 Refresh。Auto 啟用時每 5 秒刷新；點 Auto/Manual chip 可切換。
每筆項目顯示 timestamp、level、message 與可選 context。Delete 會對 log API 發出 DELETE 並清空目前 log，這是具影響性的操作；在保留故障證據前不要按。Close 只關閉 dialog，不清除資料。
| 控制項 | 用途 | 注意 |
|---|---|---|
| Level | 多選 error/warn/info/debug | debug 可能量大，只在短期排錯使用 |
| Search | 把搜尋字串交給 log API | 避免輸入或截圖敏感識別資料 |
| Refresh | 立即重新取回目前條件的 logs | 不等於重新啟動服務 |
| Auto/Manual | 控制每 5 秒自動刷新 | 長時間分析可切 Manual 保持視圖 |
| Delete | 清除 server logs | 先保存已遮蔽且必要的診斷，確認維運政策再做 |
Version mismatch 與 WebSocket connection lost
AppLayout 會在 frontend 與 backend 版本不同時顯示黃色 Version mismatch banner，並提供 Reload。這通常表示瀏覽器仍持有舊前端資源；先按 Reload 取得最新 UI。不要因此重建 Bridge 或改 storage。若 reload 後持續出現，再檢查代理 cache、Ingress 與實際後端版本。
全域 WebSocket 未連線時會顯示紅色「Connection lost, data may be outdated. Reconnecting…」。WebSocket 使用目前頁面 protocol 選擇 ws/wss，由 document base 組合 api/ws，斷線後約 3 秒重試。此時畫面資料可能過期，批次操作或設定變更應先暫停。
| 訊息 | 第一步 | 不要做 |
|---|---|---|
| Version mismatch | 按 Reload；確認 frontend/backend 顯示同一固定版本 | 不要 reset、刪 Bridge 或重新配對 |
| Connection lost | 等待自動 reconnect，檢查 Status tooltip 與 HTTP health | 不要在舊資料畫面連續執行 bulk actions |
| HA Offline 但 WebSocket connected | 到 Health 檢查 Home Assistant service connection | 不要把 UI WebSocket 當成 HA WebSocket |
| UI Online 但 Controller No Response | 檢查 Bridge、Fabric、session 與 mDNS 網路層 | 不要只刷新瀏覽器 |
Dashboard 常見卡關
Customize 按鈕不見了
它只在 hasBridges 時顯示。若 welcome card 仍在，先確認 Bridge 是否真的建立成功；到 Bridges 頁或 health API 狀態核對，不靠 local storage 判斷。
Widget 排序每台電腦不同
設定存在各瀏覽器 local storage，不是後端。需要一致時在每個受控瀏覽器設定，或按 Reset 回預設；不要還原 Matter Hub storage。
Stats 數字剛操作完沒更新
Dashboard 15 秒 refresh，頂端 Status 30 秒 refresh。先等待並用 Refresh/Health 驗證；bulk action 完成會主動抓一次，但 WebSocket 斷線時資料仍可能過期。
Connection lost 一直不消失
檢查反向代理或 Ingress 是否正確轉送
api/ws、HTTPS 是否使用 WSS、base path 是否一致。不要只反覆重啟 Bridge，因為警告是前端到後端 WebSocket 層。Version mismatch reload 後仍出現
核對 browser cache、代理 cache 與 backend 實際版本。用無快取重新載入或正確清除靜態資源 cache，不清除持久資料。
System Logs 查不到舊事件
確認 level、search 與最多 500 筆限制，並檢查是否曾按 Delete。清除後無法靠關閉 dialog 復原，因此排錯前要先按維運政策保存必要且已遮蔽的資料。
常見問題
Dashboard 的 Device 數是 HA 所有實體嗎？
隱藏 Bridges Widget 會停止 Bridge 嗎？
Stop All 可以當成一般重新整理嗎？
語言切換會改 Controller 的裝置名稱嗎？
WebSocket Offline 是否代表 Home Assistant Offline？
System Logs 的 Delete 只刪目前搜尋結果嗎？
api/logs 發 DELETE 並清空顯示，不應假設只刪目前篩選。保留診斷前不要執行。