jim800121chen
8c27da7cca
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>
244 lines
7.3 KiB
Markdown
244 lines
7.3 KiB
Markdown
# 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 版本。
|
||
|
||
**完成簽核**：________________ 日期：________________
|