🔑 1. 登入

• 瀏覽器開啟 https://pos.36588.xyz。
• 輸入帳號與密碼登入（預設帳號密碼皆為 8888，管理員可於後端修改）。
• 登入憑證（token）存於瀏覽器 localStorage，下次自動帶入；點左下角「登出」可清除。

🧭 2. 介面總覽

• 左側導覽：裝置管理、使用說明、遠端桌面、CLI 主控台。
• 裝置管理：以卡片呈現所有已註冊裝置，每 5 秒自動更新；右上角「更新」可立即刷新。
• 在線徽章：側欄顯示「在線數 / 總數」。
• 遠端桌面 /remote：VNC 控制 PC；CLI 主控台 /cli-dashboard：進階指令操作。

📇 3. 裝置卡片

• 名稱：雙擊名稱或按「改名」可自訂顯示名稱（存於伺服器）。
• 狀態燈：🟢 綠＝在線、🔴 紅＝離線（左側色條同色提示）。
• 欄位：ID（裝置唯一碼前 8 碼）、版本、平台（android / win32）、IP（含 Tailscale 100.x 與區網 IP）、最後上線時間。
• 操作按鈕：
  • 遙控：僅 Android 電視盒顯示，開啟全螢幕即時畫面遙控。
  • 控制：開啟指令彈窗（見第 4 節）。
  • 查詢：立即下發 GET_STATUS 取得裝置狀態。
  • 改名：修改顯示名稱。

🎛 4. 控制彈窗

按「控制」開啟。於下拉選單選擇指令，部分指令需填寫參數，按「執行」後結果顯示於下方。

• 執行 Shell 指令 EXEC_SHELL：下達 shell（Android 等同 adb shell；Windows 為 cmd）。例：getprop ro.product.model、wm size。
• 查詢裝置狀態 GET_STATUS：回傳主機名/平台/版本/CPU 等。
• 截取螢幕畫面 SCREENSHOT：擷取裝置畫面並顯示（裝置端需數秒）。
• 安裝 APK 應用程式 INSTALL_APK：僅 Android，見第 6 節。
• 模擬按鍵 CONTROL_KEY：填入按鍵名如 home、back、volume_up、dpad_center。
• 其他：重新載入配置 / 刷新顯示內容 / 重啟應用程式 / 關閉應用程式 / 檢查系統更新。

🎮 5. 遙控模式（僅 Android 電視盒）

在電視盒卡片按「遙控」進入全螢幕即時畫面。

• 點擊畫面＝對應座標觸控（自動換算裝置解析度）。
• 右側按鍵面板：方向鍵（上/下/左/右）、OK、返回、Home、Menu、音量+/-。
• 自動刷新頻率（右上角選單）：關 / 快 1.5 秒 / 一般 3 秒 / 慢 6 秒。
• 刷新：手動更新一次；退出：離開遙控。

📦 6. 安裝 APK

1. 控制彈窗選「安裝 APK 應用程式」。
2. 兩種來源二選一：
   • 本機檔案上傳：選擇 .apk（≤ 48MB），先上傳到中控再讓裝置下載安裝。
   • 下載 URL：直接填 APK 的 http(s) 連結。
3. 系統自動執行 wget + pm install -r，結果顯示 ✔ 成功 或 ✘ 失敗。

🖥 7. 遠端桌面（VNC 即時控制）

像 TeamViewer 一樣看到並即時操作 Windows 裝置的完整桌面（滑鼠＋鍵盤）。僅適用於已安裝並啟用 VNC（UltraVNC）服務端的 Windows 裝置；畫面與操作經中控 ws 通道轉發，裝置不需對外開埠。

連線步驟

1. 左側導覽點「遠端桌面」（或從儀表板進入 /remote），與中控台共用同一登入。
2. 左側裝置列表選一台 🟢 在線 的 Windows 裝置（⚪ 離線無法啟動）。
3. 點右上「▶ 啟動遠端」，或雙擊裝置列快速連線。
4. 等待「正在建立 VNC 連線… → 已連線」，畫面即出現在中央。

狀態標記

• 🟢 在線／⚪ 離線／🟡 遠端中（已有工作階段，列左側綠框）。
• 頂部會顯示「N 個進行中的遠端連線」。

工具列（連線後出現）

• ⌨ CAD：傳送 Ctrl+Alt+Del（用於登入/安全畫面）。
• 🔍 縮放：循環切換「適應 / 100% / 200%」。
• ⛶ 全螢幕：瀏覽器全螢幕顯示裝置畫面。
• 📋 貼上：將本機剪貼簿文字送到裝置（再到裝置上按 Ctrl+V 貼上）。
• 📄 複製：抓取裝置剪貼簿文字到本機。
• ■ 結束遠端：中斷並釋放裝置端 VNC。

機制與限制

• 網路瞬斷會自動重連（最多 5 次，退避 2/3/5/8/13 秒）；畫面 30 秒無更新會自動請求全畫面重刷。
• 同一裝置同時只能有一個遠端工作階段；若顯示「🟡 遠端中」表示已被連線（可能是你其他分頁），可點「結束遠端」接手或等其結束。

故障排除

• 「裝置端 VNC 啟動失敗」：確認該 Windows 機已安裝並啟用 UltraVNC 服務端。
• 「載入畫面逾時 / 等待 VNC 握手逾時」：裝置端 VNC 未正確回應（服務模式/認證設定），點「結束遠端」後重試。
• 裝置離線無法啟動：先回「裝置管理」確認 agent 在線。

⌨ 8. CLI 主控台

終端機風格介面，適合快速巡檢與批次操作：可對單一台、或一次「廣播」對所有在線裝置下指令。與儀表板共用登入（同一 token）。從左側「CLI 主控台」或 /cli-dashboard 進入。

介面組成

• 左側裝置列表：主機名 + ID + 🟢/⚪ 狀態，點擊選取（每 10 秒自動刷新）。
• 目標裝置下拉：選單一裝置；勾選「廣播所有在線裝置」則指令對所有在線裝置同時下發。
• 快捷按鈕：📊 狀態（GET_STATUS）、📷 截圖（SCREENSHOT）、🖼️ 查看截圖（取回最新截圖並彈窗顯示/下載）、🔄 重啟（RESTART_APP）、⬆️ 更新（UPDATE_NOW）、📝 重載設定（RELOAD_CONFIG）。
• 中間輸出區：類似終端，以顏色區分——紫＝指令、綠＝成功、紅＝錯誤、灰＝系統訊息。
• 下方 PS> 輸入框：輸入任意 shell 指令（EXEC_SHELL），按 Enter 或「執行」送出。

指令範例

• Windows：whoami、Get-Process、ipconfig
• Android：getprop ro.product.model、wm size、pm list packages -3

🤖 9. Android 電視盒遠端自動化

電視盒（Android）除了遙控點選，還能遠端執行腳本：靜默開啟網頁、點擊網頁元素、模擬按鍵/滑動/輸入。全部透過 EXEC_SHELL（等同 adb shell）與 App 内建指令送達，可在「CLI 主控台」或控制彈窗下發。

現成可用的指令

指令	用途	参數格式（JSON）
EXEC_SHELL	執行 adb shell（input/am/sleep…）	{"command":"input tap 960 540"}
CONTROL_KEY	方向/OK/返回/Home/選單/音量	{"key":"CENTER"}
OPEN_SITE	開網頁（App 内嵌 WebView）	{"url":"https://..."}
RUN_AUTOMA	執行站點自動化腳本	{"siteId":"site_001"}
SCREENSHOT	抓圖驗證結果	{}

① 靜默開啟網頁（四種做法）

1. 走 POS App 内嵌 WebView（最推薦、最靜默）：OPEN_SITE {"url":"https://..."}。不跳出瀏覽器 App、不佔返回棧，由 POS App 直接控制畫面。
2. 叫系統瀏覽器（EXEC_SHELL）：am start -a android.intent.action.VIEW -d "https://example.com"。會跳出 Chrome/内建瀏覽器（非靜默），可加 -f 0x10000000（NEW_TASK）。
3. 指定某 App 的 Activity 開 URL：am start -n com.android.chrome/.Main -d "https://example.com"。
4. 深連結給 POS App：am start -a android.intent.action.VIEW -d "myapp://openweb?url=https%3A%2F%2F..."（需 App 已註冊 intent-filter scheme）。

② 點擊網頁（四種做法，難易遞增）

• A. 座標 tap（現成可用）：input tap 1035 690。遙控模式點畫面已自動換算座標；CLI 也可直接打。缺點：解析度/版面一改就錯位。
  相關：input swipe 500 1200 500 400 300（滑動）、input text "hello"（輸入，限 ASCII）、input keyevent 4（返回）、input keyevent 66（Enter）。
• B. RUN_AUTOMA（站點自動化腳本）：把操作步驟寫成 automation JSON（如 [{action:'click',selector:'#submit'},…]），存在站點設定，再用 RUN_AUTOMA {"siteId":"site_XXX"} 播放。優：依 CSS 選擇器定位、不怕座標；缺：只能操作 POS App 自己載入的網頁。
• C. JS 注入（需 App 新增 EXEC_JS）：EXEC_JS {"code":"document.querySelector('#login').click()"}。目前指令型別尚未實作，需在 App 端加 handler。
• D. AccessibilityService（跨 App）：App 注册無障礙服務，可對任何 App（含 Chrome）的節點依 id/text 定位並 performAction(ACTION_CLICK)。需在裝置「設定→無障礙」一次性開啟權限。

③ 端到端範例（CLI 主控台依序下發）

• 開網頁：OPEN_SITE {"url":"https://pos.example.com/settle"}
• 等載入：EXEC_SHELL {"command":"sleep 3"}
• 點確認：EXEC_SHELL {"command":"input tap 1035 690"}
• 再等：EXEC_SHELL {"command":"sleep 1.5"}
• 截圖核對：SCREENSHOT {}

也可一句串起：am start -a android.intent.action.VIEW -d "https://..."; sleep 3; input tap 1035 690

④ 想更聰明的點擊，需要加什麼

目標	需新增	難度
用 CSS 選擇器而非座標	App 加 EXEC_JS → evaluateJavascript()	⭐⭐（改 Android App）
跨 App 也能點	App 加 AccessibilityService + FIND_AND_CLICK	⭐⭐⭐
條件流程（看到 X 就點 Y）	寫一組 RUN_AUTOMA automation JSON	⭐（資料層）

📋 10. 指令一覽表

指令	用途	Android	Windows
EXEC_SHELL	執行 Shell 指令	✅	✅
GET_STATUS	查詢裝置狀態	✅	✅
SCREENSHOT	截取螢幕畫面	✅	✅
INSTALL_APK	安裝 APK	✅	—
CONTROL_KEY	模擬按鍵	✅	—
RELOAD_CONFIG / RELOAD_CONTENT	重載配置 / 刷新內容	✅	—
UPDATE_NOW	檢查系統更新	✅	—
RESTART_APP / CLOSE_APP	重啟 / 關閉應用（會短暫離線）	✅	✅

❓ 11. 常見問題

裝置顯示離線？

• 確認裝置端 agent / 客戶端執行中、網路與 Tailscale 連線正常。
• Windows 機若剛下過「重啟/關閉」，會短暫離線數十秒後自動重連。

截圖/遙控無反應？

• Windows 無 UI agent 的截圖需有已登入的互動桌面（console session）才能取圖。
• Android 截圖到回傳約需 1–3 秒，連續操作時請稍候新畫面。

遙控感覺卡？

• 瓶頸多在裝置截圖而非頻寬；把自動刷新調慢（如 6 秒）可降低負載。

🧬 12. Ghost / Clone 與 deviceId 唯一性

大量裝機常以 Ghost / 磁碟鏡像 / MDT 一次部署多台 PC；Android 電視盒也適用同樣的 ROM 量產 / APK 預裝。若 master image 內已快取過 deviceId，所有複製出去的機器都會用同一個 id 上線 → 儀表板看起來像「同一台一直在跳」、指令會錯/random 失靈、pending_commands 互相污染。

怎麼被污染

• Windows：C:\ProgramData\hub\pos-agent-device.json 若已在 master 生成 → clone 後每台讀到同一 id。
• VM snapshot：MAC / ComputerName / MachineGuid 若未 reseed，就算沒 device.json 也會算出同一 hash。
• Android：ROM 內 APK 已寫入 SharedPreferences 的 deviceId，或 Build.SERIAL 讀不到時 fallback 用的 ANDROID_ID 在 /data 鏡像下相同。

三道防線

1. 安裝器自癒（已上線）：install_posagent.ps1 在註冊排程前強制刪除 pos-agent-device.json，讓 agent 下次啟動依當前機器重算。
   Remove-Item -Force -EA 0 (Join-Path $DataDir 'pos-agent-device.json')
2. 中控漂移偵測：同 deviceId 短時間從不同 hostname 或不同 MachineGuid 送 REGISTER → 標記 suspect_shared_id，前端徽章提示。
3. 部署 SOP：封裝前 checklist 明確要求 — Windows 走 sysprep /generalize 且不預先跑過 agent；Android 請廠商量產 ROM 內 APK 保持「首次啟動前不 cache deviceId」。

疑似中招的排查

1. 儀表板若看到同一 hostname 有兩筆記錄、或多台機器 device_ip 完全相同 → 立即用「CLI 主控台」對可疑 id 下 EXEC_SHELL: hostname，看實際回應的主機名稱與本應的對應。
2. 對每台跑 EXEC_SHELL: powershell -c "Get-Content C:\ProgramData\hub\pos-agent-device.json -Raw"，比對 deviceId 欄是否多台相同。

自救一行指令

• Windows：管理員 PowerShell 跑 iwr https://pos.36588.xyz/updates/install_posagent.ps1 -useb | iex → 內建已含清 device.json 步驟，會依當前機器重算 → 下次 PosHubAgent 排程啟動就會以新 id 註冊。
• Android：在中控對受影響 id 下 EXEC_SHELL: pm clear <package> 清 App 資料（會要求重新登入），或 RESTART_APP 觸發 APK 重算。注意：這會短暫離線 5–30 秒。