# 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 版本。

**完成簽核**：________________ 日期：________________