jim800121/visionA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
visionA/local-tool/.autoflow/06-testing/scripts/manual-checklist-linux.md
jim800121chen 8c27da7cca test(local-tool): M9-5 — three-platform validation plan + e2e scripts + MJ3 fix 
A 階段最後 milestone、出測試計畫 + 自動化腳本 + 三平台人工 checklist、使用者下週手動跑實機驗證。

Testing artifacts (8 檔、2630 行):
- .autoflow/06-testing/m9-5-validation-plan.md: 656 行（4 情境 × 3 平台 × 2 chip = 24 combo）
- 4 e2e specs (vitest + RTL + mock WS / mock fetch):
  - firmware-upgrade-happy-path.spec.ts (357 / 4 cases)
  - firmware-upgrade-error-recovery.spec.ts (356 / 4 cases + 8 reason it.each)
  - firmware-r-fw-11-modal-not-closable.spec.ts (303 / 6 cases)
  - wails-onbeforeclose-firmware-active.spec.ts (217 / 9 cases、含 5 todo 占位 M9-12)
- 3 manual checklists: macOS 264 / Windows 234 / Linux 243 行

設計取捨:
- 不引入 Playwright/Cypress (visionA-local frontend 沒裝、屬 architect 決策)、走 vitest + mock
- E2E 腳本放 06-testing/scripts/ 作 spec doc + 可選實作參考
- 實機驗證走人工 checklist (dongle 插拔 / kill process / SIGTERM 等需要實體互動)

MJ3 修復 (M9-4 reviewer round 1 留的 follow-up):
- server/internal/api/ws/firmware_ws_test.go: +16/-8
- "type": "firmware:progress" → "firmware_progress" (對齊 firmwareProgressMessage.Type)
- "phase" → "stage" (對齊 TDD §4.2 + FirmwareProgress.Stage)
- 不動 production code、只 test schema 對齊

執行建議 (給你下週):
- Day 1 P0: macOS+Win+Linux × KL520+KL720 happy path (~3h)
- Day 2 P1: R-FW-11 + disconnect_during_op + upgrade_mid_failed + 失敗注入 (4h)
- Day 3 P2: SIGTERM 延遲關閉 + Wails OnBeforeClose force-quit modal (2-3h)

測試:
- go test ./... -race 全綠 (server / wails / frontend 60 tests)
- MJ3 修復不破壞既有測試

A 階段開發 6/7 完成 (M9 文件 + M9-1 ~ M9-4.5)、剩 M9-5 實機驗證 (你下週跑)、跑完依結果決定 A 階段交付或派 sub-agent 修。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-25 15:34:17 +08:00

7.3 KiB
Raw Blame History

M9-5 Linux 實機驗證 checklist

對應 plan：../m9-5-validation-plan.md 平台：Ubuntu 20.04+ / Debian 11+ / 同等 distro（x86_64） 預估時間：3-4 小時 執行人：使用者（下週）

0. 前置準備（15 分鐘）

  • 確認 distro 版本：lsb_release -a 或 cat /etc/os-release、紀錄：__________
  • visionA-local A 階段 build（含 M9-1 ~ M9-4）已安裝
  • 清空舊狀態：rm -rf ~/.local/share/visiona-local/ ~/.config/visiona-local/
  • 準備硬體：
    • KL520 KDP1 legacy dongle：__________
    • KL520 KDP2 dongle：__________
    • KL720 dongle：__________
  • udev rules 已綁定（KneronPLUS Linux 必要）：
    • 確認 /etc/udev/rules.d/ 下有 KneronPLUS rule（如 99-kneron-plus.rules）
    • 確認當前使用者在 plugdev group：groups | grep plugdev
    • 若無、跑 installer / sudo usermod -aG plugdev $USER、登出再登入
  • Chrome / Firefox 任一最新版開啟、F12 DevTools 準備好
  • Terminal 開好、tail -f ~/.local/share/visiona-local/server.log

1. Functional 升級流程驗證（90 分鐘）

1.1 情境 A：KL520 KDP1 → KDP2 完整 4-stage（30 分鐘）

前置：插 KL520 KDP1 dongle

  • lsusb 確認 dongle 被 USB stack 認到（找 Kneron 或 0c45: PID）
  • 啟動 visionA-local（執行 ./visiona-local 或 .desktop launcher）
  • Wails 視窗開啟、控制台顯示 server URL
  • 點「開啟瀏覽器」、Devices 頁出現
  • 紅色 badge KDP1 (legacy) 顯示
  • 點升級、confirm modal
  • from/to 顯示 from = KDP1、to = v2.2.0
  • 點「開始升級」、upgrading phase
  • progress modal 不顯示 ✕ / 取消
  • 紅色 banner「請勿拔除裝置」顯示
  • stage 序列：preparing → loading → flashing → verifying
  • ESC 不關 modal、點外部不關
  • 升級在 60 秒內完成（實測時長：______ 秒）
  • modal 顯示綠勾、自動關閉、toast 顯示 6 秒
  • Devices 卡片 badge 變綠 + v2.2.0
  • journalctl --user -u visiona-local 或 server.log 無 panic

截圖：

  • .autoflow/06-testing/screenshots/linux-A-before.png
  • .autoflow/06-testing/screenshots/linux-A-upgrading.png
  • .autoflow/06-testing/screenshots/linux-A-success.png

1.2 情境 B：KL520 KDP2 short-circuit（15 分鐘）

  • 黃色 badge / 點升級
  • 3 stage 序列
  • 60 秒內完成（實測：______ 秒）

1.3 情境 C：KL720 升級（15 分鐘）

  • 點升級、confirm 顯示「3 分鐘」
  • 3 stage
  • 200 秒內完成（實測：______ 秒）

1.4 情境 D：來回升級（15 分鐘）

  • 重跑情境 A 一次
  • 無 Error 15
  • 兩次都成功

1.5 多裝置同時連接（15 分鐘）

  • KL520 + KL720 同時插
  • 兩張卡片
  • KL520 升級時、KL720 升級被擋
  • KL520 完成後 KL720 可升級

2. Reliability 失敗注入（45 分鐘）

2.1 #1 scan_not_found（5 分鐘）

  • 拔 USB、點升級
  • error modal「找不到裝置」

2.2 #3 loader_write_failed（10 分鐘）

注入：loading stage 時、pkill -9 python3 或 pkill -9 -f kneron_bridge.py

  • error modal「引導程式載入失敗」
  • 「拔插後重試」按鈕
  • 無 brick warning

2.3 #4 upgrade_mid_failed（10 分鐘）

注入：flashing stage 時、pkill -9 python3

  • error modal「韌體寫入失敗」
  • errorCode FW_UPGRADE_*
  • 「重試」按鈕

2.4 #5 disconnect_during_op（10 分鐘）

注入：flashing stage 時、拔 USB

  • error modal「裝置已斷開」
  • brick warning role=note
  • 無 Retry 按鈕
  • Contact Support destructive 按鈕
  • 點 Contact Support、xdg-open 預設 mail handler 應開（如 Thunderbird）

2.5 #6 timeout（10 分鐘）

  • 拔 USB 後等 > 60s（KL520）/ > 200s（KL720）
  • error modal「操作超時」

3. UX 驗證（30 分鐘）

3.1 Badge 4 色

State 觸發 紀錄
current（綠） [ ]
older（黃） [ ]
legacy（紅） KDP1 [ ]
unknown（灰） scan 過渡期 [ ]

3.2 Modal 警告 banner 全程顯示

  • 4 個 stage 都顯示「請勿拔除裝置」

3.3 Toast 停留 6 秒

  • 計時驗證

3.4 複製錯誤訊息

  • 點複製、變「已複製 ✓」
  • xclip -selection clipboard -o 確認內容含 stage / reason / errorCode / rawError

3.5 mailto: 開啟

  • destructive reason 點 Contact Support
  • Thunderbird / Evolution / 預設 mail client 開啟（透過 xdg-open 或 gio open）
  • 若無預設 mail client → log 為 P3、不算 fail

4. Integration 驗證（30 分鐘）

4.1 SIGTERM 延遲關閉（Linux 最直觀、推薦在此平台驗）

前置：終端機跑 pgrep -f visiona-local-server、紀錄 PID

  • 啟動升級流程（情境 A 慢一點）
  • 升級進入 flashing stage 時、Terminal 跑 kill -TERM <PID>
  • server 不立即退出
  • tail -f ~/.local/share/visiona-local/server.log：
    • log 含「firmware: N active firmware task(s) detected, delaying shutdown up to 220s」
  • 升級正常完成
  • log 含「firmware: all firmware tasks completed, proceeding to shutdown」
  • server 完成升級後才退出
  • Wails 視窗收到 server offline overlay

4.2 Wails OnBeforeClose 攔截

  • 啟動升級
  • flashing stage、點 Wails 視窗 ✕（window manager 的關閉按鈕）
  • 視窗不關
  • Frontend modal「韌體切換進行中...」
  • modal 顯示 task info
  • 「繼續等待」+「強制關閉」按鈕
  • 點強制關閉、第二層 FORCE 確認
  • 輸入「force」小寫 → disabled
  • 輸入「FORCE」 → enabled
  • 點「繼續等待」→ modal 關、升級繼續
  • 升級完成、再點 ✕ → 視窗正常關

4.3 SIGINT（Ctrl+C）測試

⚠ Linux 特有、若 visionA-local 從 terminal 跑：

  • terminal 跑 visionA-local
  • 升級進行中、Ctrl+C
  • server SIGINT handler 應視同 SIGTERM、走 delayed shutdown
  • 升級完成才退出

5. Linux 特有觀察點

5.1 USB 權限

  • dmesg | tail 升級期間沒 USB permission denied
  • device re-enumerate 後 udev rules 自動套用

5.2 systemd / desktop integration

  • visiona-local.desktop 若有、launcher 啟動正常
  • gnome-shell / kwin 對 Wails 視窗的 close button 處理正確

5.3 server.log 路徑

依 distro 可能在：

  • ~/.local/share/visiona-local/server.log（XDG_DATA_HOME）
  • ~/.config/visiona-local/server.log
  • 或 systemd journal（journalctl --user）

確認 log 寫入位置：__________

6. 驗證結果摘要

類別 結果 備註
§1 Functional
§2 Reliability
§3 UX
§4 Integration
§5 Linux 特有

升級時長實測：

Combo 實測 護欄 Pass / Fail
KL520 KDP1→KDP2 __秒 60s
KL520 short-circuit __秒 60s
KL720 __秒 200s

7. Bug 回報

依 ../m9-5-validation-plan.md §11 格式、標題前綴「[Linux]」+ distro 版本。

完成簽核：________________ 日期：________________