visionA/local-tool/.autoflow/06-testing/m9-5-validation-plan.md

M9-5 三平台實機驗證計畫 — Kneron Dongle FW 升降版

對應 PRD：.autoflow/02-prd/features/feature-firmware-management.md（AC-FW-1.1 ~ AC-FW-1.9） 對應 TDD：.autoflow/04-architecture/v2/firmware-management.md §11（測試策略） 對應 Design：.autoflow/03-design/v2/firmware-management.md §7（失敗復原 UX 8 種） 階段：A 階段最後 milestone（M9-5、1 人天、Testing 出 plan + 自動化腳本、使用者下週實機驗證） 版本：v1.0（2026-05-25） 作者：Testing Agent

---

0. 文件結構導覽

章節	主題
§1	範圍與驗證目標
§2	測試環境前置（硬體 + 軟體）
§3	三平台 × 兩 chip × 四情境 × 一致驗證表（24 combo）
§4	功能性驗證（Functional） — happy path、4 情境
§5	可靠性驗證（Reliability） — 失敗注入 8 種 reason
§6	效能驗證（Performance） — 升級時長護欄
§7	UX 驗證 — badge / modal / 復原 UI / R-FW-11 modal 不可關
§8	整合驗證 — SIGTERM / Wails OnBeforeClose / force-quit modal
§9	自動化腳本對照表（E2E unit-style + 手動 checklist）
§10	通過 / 失敗判定規則
§11	Bug 回報格式
§12	下週執行建議順序（哪平台先 / 哪情境先）
§13	Pass → next-step / Fail → 派工建議

---

1. 範圍與驗證目標

1.1 範圍邊界

在範圍（M9-5 必驗）：

• KL520 + KL720 兩 chip 的 FW 升級流程（A 階段、KDP1 → KDP2 + KDP2 → KDP2 short-circuit）
• macOS / Windows / Linux 三平台
• 4 個升級情境（§4.1）
• 8 種失敗注入路徑（§5.2）
• AC-FW-1.1 ~ AC-FW-1.9 全部 acceptance criteria
• §8.6 graceful shutdown + Wails OnBeforeClose force-quit modal

不在範圍（B 階段或 post-launch）：

• KL630 / KL730 升降版（B 階段 M9-10 才開、AC-FW-3.5）
• 手動降版（B 階段 M9-11/12）
• 多版本目錄結構（B 階段 M9-9）
• KneronPLUS wheel 升 3.1.2 跨主版本回歸（B 階段 M9-13）
• Beta usability test（UR-1~3、post-launch）

1.2 驗證目標（pass criteria）

類別	目標
Functional	4 情境 × 6 combo（3 平台 × 2 chip）= 24 個升級實驗、success rate ≥ 95%
Reliability	8 種 reason 注入測試、UI friendly message 正確顯示、no server crash
Performance	KL520 ≤ 60s 上界、KL720 ≤ 200s 上界（AC-FW-1.7 + TDD §7.2 護欄）
UX	Badge 4 色顯示正確、modal 不可關（R-FW-11）、復原 UI 對應 8 種 reason
Integration	SIGTERM 延遲關閉、Wails OnBeforeClose force-quit modal 阻擋成功

---

2. 測試環境前置

2.1 硬體（使用者已備齊）

項目	說明
KL520 dongle	USB Boot 版（KDP1 legacy）+ KDP2 standard 版各 1 根；若只有 KDP2 dongle、可從 KDP2 跑 short-circuit 路徑
KL720 dongle	至少 1 根（已預燒 KDP2、會走 short-circuit）
macOS 機器	Apple Silicon 或 Intel x86_64（兩者皆可）
Windows 機器	Windows 10/11、x86_64、有 admin 權限（KneronPLUS WinUSB driver）
Linux 機器	Ubuntu 20.04+ 或同等 distro、udev rules 已綁定
USB hub	推薦（拔插測試方便、不必碰主機 port）

2.2 軟體

每平台需要：

• visionA-local 最新 A 階段 build（含 M9-1 ~ M9-4 commits）
• Chrome / Edge / Firefox 任一（測 UI、瀏覽器 tab）
• Terminal / Console（看 server log、跑 git log 等）

2.3 測試資料

• 純淨環境：每平台跑前刪 ~/Library/Application Support/visiona-local/ 或同等位置、確保沒有 leftover state
• KL520 KDP1 dongle 是必要的（最重要的 happy path）；若沒有、降級為「KDP2 short-circuit only」+ §11 bug-report 指出此 gap

---

3. 三平台 × 兩 chip × 四情境驗證表

每個 cell = 1 個驗證實驗。理想全部 ✅，部分 ⚠ partial 可接受、❌ 阻擋發布。

#	平台	Chip	情境	預期 stage 序列	timeout 上界	驗證標準
1	macOS	KL520	KDP1 → KDP2 完整升級（4 stage）	preparing → loading → flashing → verifying → done	60s	§4.1 情境 A
2	macOS	KL520	KDP2 → KDP2 short-circuit（3 stage）	preparing → flashing → verifying → done	60s	§4.1 情境 B
3	macOS	KL720	KDP2 升級 / load_firmware_from_file	preparing → flashing → verifying → done	200s	§4.1 情境 C
4	Windows	KL520	KDP1 → KDP2 完整升級	同 1	60s	§4.1 情境 A
5	Windows	KL520	KDP2 short-circuit	同 2	60s	§4.1 情境 B
6	Windows	KL720	KDP2 升級	同 3	200s	§4.1 情境 C
7	Linux	KL520	KDP1 → KDP2 完整升級	同 1	60s	§4.1 情境 A
8	Linux	KL520	KDP2 short-circuit	同 2	60s	§4.1 情境 B
9	Linux	KL720	KDP2 升級	同 3	200s	§4.1 情境 C
10	macOS	KL520	來回升級（情境 A 完成後再跑 A）	兩次 1 stage 序列	各 60s	§4.1 情境 D
11	Windows	KL520	來回升級	同 10	各 60s	§4.1 情境 D
12	Linux	KL520	來回升級	同 10	各 60s	§4.1 情境 D

Functional combo = 12（3 平台 × 2 chip × 2 主情境 = 12；情境 D 是延伸驗證、加 3 combo = 15、但 reliability + UX + integration 各加部分 combo、合計約 24 個實驗）。

Reliability 額外實驗：

• 13-20：每平台跑「拔 USB 中斷」「kill bridge.py」「kill server」「modal R-FW-11 不可關」4 種注入，至少 macOS + Windows 各 4 = 8 combo（Linux 補上 = 12）

Integration 額外實驗：

• 21-24：每平台跑「升級期間關 Wails 視窗→force-quit modal」「升級期間 SIGTERM→延遲關閉」2 種、合計 6 combo

合計 ~24 個 combo，使用者可依時間裁切（§12 給優先順序）。

---

4. 功能性驗證（Functional）

4.1 4 個升級情境（每平台 × 每 chip 都跑）

情境 A：KDP1 → KDP2 完整升級（4 stage、AC-FW-1.2）

前置條件：插一根 KL520 KDP1 legacy dongle（firmware 字串 KDP Comp/U 或類似）。

測試步驟：

1. 確認 visionA-local 已啟動、瀏覽器開 Devices 頁
2. 確認偵測到 dongle、卡片右上角 FW badge 紅色 + 文字「KDP1 (legacy)」+ tooltip「此韌體為舊版 KDP1...」
3. 點卡片內「升級到最新」按鈕（labels：升級到 v2.2.0）
4. 確認 confirm modal 顯示：
   • 標題「升級韌體」
   • from/to：from = KDP1、to = v2.2.0
   • 警告：「升級過程約需 30 秒、期間切勿拔除裝置或關閉應用程式」
   • 「開始升級」按鈕（primary、不是 destructive）
5. 點「開始升級」、modal 切到 upgrading phase
6. 確認 progress modal：
   • 不顯示 ✕ / 取消按鈕（R-FW-11 緩解）
   • progress bar 從 0% 開始
   • 階段文字依序變化：「階段 1 / 4：準備（偵測 + 連接裝置）」→「階段 2 / 4：載入引導程式」→「階段 3 / 4：寫入韌體」→「階段 4 / 4：驗證完成」
   • 紅色 banner「請勿拔除裝置」全程顯示
   • 「已耗時」秒數遞增、「預估剩餘」秒數遞減（依 etaMs 計算）
   • ESC / 點外部不關 modal（捕獲、抖動或無反應）
7. 升級成功（30 秒內）、modal 短暫顯示綠勾 ✓ 「完成」+ afterVersion v2.2.0
8. 約 1.5 秒後 modal 自動關閉
9. 右上角 toast 出現：「KL520 #1 升級成功 — 從 KDP1 升級到 v2.2.0（耗時 X 秒）」、停留 6 秒
10. Devices 卡片 FW badge 變綠、firmware version v2.2.0

Pass 條件：

• ✅ 全部步驟完成、所有 UI 元素如預期
• ✅ 升級在 60s 內完成（KL520 timeout 上界）
• ✅ 4 stage 全部出現、順序正確
• ✅ Server log 沒有 panic、error

情境 B：KDP2 → KDP2 short-circuit（3 stage）

前置條件：KL520 dongle 已是 KDP2、firmware 字串為 v2.1.0 或 v2.2.x 但比 bundled current 舊（觸發 yellow badge）。或情境 A 跑完後重新跑情境 B。

測試步驟：

1. Devices 頁卡片 FW badge 黃色（older）
2. 點升級按鈕、confirm modal
3. 點「開始升級」、modal 切 upgrading
4. 確認 progress stage 序列：3 stage（不是 4）：「階段 1 / 3：準備」→「階段 2 / 3：寫入韌體」→「階段 3 / 3：驗證完成」（沒有 loading 階段）
5. 升級成功、badge 變綠

Pass 條件：

• ✅ 3 stage 而不是 4 stage（核心差異、stageOrdinal helper 邏輯驗證）
• ✅ 升級在 60s 內完成

情境 C：KL720 升級

前置條件：KL720 dongle（firmware 為 KDP2，可能與 bundled current 一樣或舊）。

測試步驟：

1. Devices 頁卡片 badge：綠 (若 already current) 或黃 (older 可升)
2. 若是黃色，點升級
3. 同情境 A/B，但 estimated duration 標 3 分鐘（180 秒）
4. progress modal stage 序列同 KDP2 short-circuit

Pass 條件：

• ✅ 升級在 200s 內完成（KL720 timeout 上界）
• ✅ progress 跑滿且沒有卡死

情境 D：來回升級（regression）

前置條件：情境 A 已跑完、再跑一次完整 KDP1 → KDP2 升級流程（如果有第二根 KL520 KDP1 legacy dongle，建議用第二根；否則只能跑一次）。

測試步驟：

1. 重新跑情境 A
2. 確認第二次升級不會：
   • 被「Error 15 SEND_DATA_TOO_LARGE」打斷（既有 KL520 reset bug fix 應該已處理 needsReset=true）
   • bridge.py 帶舊 firmware state 連線
3. 第二次升級流程跟第一次完全一樣

Pass 條件：

• ✅ 沒有 Error 15
• ✅ 連續兩次升級都成功

4.2 多裝置同時升級（per-device 隔離、firmware-store activeDeviceId 機制）

前置條件：兩根 dongle 同時連接（建議 1× KL520 + 1× KL720）。

測試步驟：

1. Devices 頁顯示兩張卡片
2. 點 KL520 卡片的升級按鈕（modal 開）
3. 升級進行中、切回 Devices 頁 看另一張 KL720 卡片狀態
4. 點 KL720 卡片的升級按鈕 — 預期：會被擋住（因為 firmware-store 一次只允許一個 activeDeviceId、其他 device 的事件被忽略）
   • 或者 modal 開但顯示「裝置正在進行其他作業」（409 FW_DEVICE_BUSY）
5. 等 KL520 完成
6. 點 KL720 升級、流程正常

Pass 條件：

• ✅ 第一個升級進行中、不會被第二個 modal 蓋掉
• ✅ Frontend store 不出現「兩個 progress event 互相覆蓋」

---

5. 可靠性驗證（Reliability、失敗注入）

5.1 對應 Design §7.1 的 8 種失敗類型

#	失敗類型	注入方法	預期 reason	預期 UI
1	scan_not_found	升級前拔 USB → 立刻點升級	scan_not_found	error modal「找不到裝置」+「重新插拔後重試」按鈕
2	connect_failed	多開 visionA-local（兩 instance 搶 device）→ 點升級	connect_failed	「無法連接裝置」+「重試」按鈕
3	loader_write_failed	升級到 loading stage 時 pkill -9 python	loader_write_failed	「引導程式載入失敗」+「拔插後重試」
4	upgrade_mid_failed	升級到 flashing stage 時 pkill -9 python	upgrade_mid_failed	「韌體寫入失敗、聯絡技術支援」+「複製錯誤訊息」+「取得協助」（mailto:）
5	disconnect_during_op	升級到 flashing stage 時拔 USB	disconnect_during_op	brick warning banner + 「Contact Support」（不顯示 retry 按鈕）
6	timeout	修改 bridge.py 加 time.sleep(70) 模擬 KL520 ≥ 60s（或 KL720 ≥ 200s）	timeout	「操作超時」+「拔插後重新掃描」
7	verify_mismatch	升級成功但 backend 偽造 firmware 字串不對（需 mock 或實機難以重現）	verify_mismatch	brick warning + ContactSupport
8	verify_not_found	升級成功但 rescan 找不到 device	verify_not_found	brick warning + ContactSupport

實機限制：#7 verify_mismatch / #8 verify_not_found 在實機很難穩定重現、建議用 E2E 自動化（mock backend）覆蓋。

5.2 注入測試步驟模板

對每個失敗類型：

1. 啟動 visionA-local
2. 跑情境 A 或 B 升級流程到 confirm modal
3. 點「開始升級」、進入 upgrading phase
4. 等到指定 stage、執行注入動作（拔 USB / kill process / etc.）
5. 觀察 UI 變化
6. 截圖 + 紀錄 timestamp

5.3 重點驗證項

對每個失敗：

• error modal 顯示對應 friendly message（中文 / 英文視 i18n 設定）
• 顯示 errorCode（如 FW_E102）
• 技術資訊區可展開、包含 stage / reason / deviceId / rawError
• 「複製錯誤訊息」按鈕可點、複製成功變「已複製 ✓」
• 若是 destructive reason（disconnect/verify_mismatch/verify_not_found）：
  • 顯示 brick warning role=note
  • 不顯示 Retry 按鈕
  • 顯示「Contact Support」destructive 按鈕（enabled、點擊開 mailto:）
• 若是 recoverable reason（其他）：
  • 顯示 Retry / ReplugRetry / Rescan 按鈕
  • 點 Retry 後流程重啟（store 回 confirming phase + 重新打 API）
• Server log 無 panic、無 crash
• Devices 頁卡片狀態不會卡住、re-plug 後可繼續用

---

6. 效能驗證（Performance）

6.1 升級時長護欄（AC-FW-1.7、TDD §7.2）

Chip	預估	護欄上界	護欄超過行為
KL520	~30s（warrenchen 實測）	60s	timeout、UI 顯示 Reason="timeout"
KL720	~180s（warrenchen 實測）	200s	timeout、UI 顯示 Reason="timeout" + FW_UPGRADE_BRICK_RISK

6.2 量測方法

對每個 functional 升級實驗（§3 表格 1-12）：

1. 開瀏覽器 DevTools Network tab、觀察 WS 「firmware_progress」event 時序
2. 紀錄：
   • stage=preparing event 第一次出現的 timestamp
   • stage=done event 出現的 timestamp
   • 差距 = 升級實測時長
3. 對照表格：

Combo	預期時長	實測時長	Pass / Fail
macOS × KL520 × KDP1→KDP2	< 60s
macOS × KL520 × short-circuit	< 60s
macOS × KL720	< 200s
Windows × KL520 × KDP1→KDP2	< 60s
...

Pass 條件：所有 combo 升級時長 ≤ 護欄上界。 Warn 條件：時長 > 預估但 < 護欄、log 為 P3 改善項。 Fail 條件：時長 ≥ 護欄、阻擋發布、回 Backend 派工調 timeout / 修流程。

6.3 progress event 推送頻率

• 預期：每 stage 切換時推 1 個 event、每秒至少 1 個 event（含 ETA 更新）
• 若 stage 間 > 10s 沒有 event：UI ETA 失準、log 為 Backend P2 改善項

---

7. UX 驗證

7.1 Badge 4 色狀態（AC-FW-1.1）

State	條件	顏色	文字
current	firmwareVersion = bundled current	綠	版本字串（如 v2.2.0）
older	firmwareVersion 比 current 舊（同 KDP2 系列）	黃	版本字串
legacy	firmwareIsLegacy = true（KDP1）	紅	KDP1
unknown	firmwareVersion 或 bundled 為空 / unknown	灰	Unknown 或 Loading...

測試步驟：

1. 在三平台分別跑：插一根 KDP1 legacy dongle、確認紅 badge
2. 升級到 v2.2.0 後、確認綠 badge
3. 修改 bundle CURRENT_VERSION（如果 A 階段沒實作則此步驟跳過、由 B 階段 M9-9 驗）→ 確認黃 badge
4. 拔 USB → 卡片消失（不該顯示灰 badge、直接 device 不在清單）
5. 連線中 bridge.py 沒回 firmware 字串 → 顯示灰 badge（過渡狀態）

7.2 升級 modal R-FW-11「不可關」驗證（AC-FW-1.9）

升級 upgrading phase 期間驗證：

• ✕ 按鈕不存在（DialogContent showCloseButton={false}）
• ESC 不關閉 modal
• 點 modal 外部（黑色 overlay）不關閉
• 「取消」按鈕不存在
• 即使刷新瀏覽器頁面後再回來、升級期間仍在進行（progress modal 由 store 重新 hydrate）

7.3 失敗 modal 復原 UI（Design §7.2）

Reason	主要按鈕	次要按鈕
scan_not_found	「重新插拔後重試」	關閉
connect_failed	「重試」	關閉
loader_write_failed	「拔插後重試」	關閉
upgrade_mid_failed	「重試」	關閉
timeout	「拔插後重新掃描」	關閉
disconnect_during_op	「Contact Support」（destructive、mailto:）	關閉、無 retry
verify_mismatch	「Contact Support」	關閉、無 retry
verify_not_found	「Contact Support」	關閉、無 retry

每種失敗都驗：

• 主要按鈕文案正確
• destructive reason 不顯示 Retry
• Contact Support 點擊開 mailto: handler（subject + body 帶 errorCode + 技術資訊）
• 「複製錯誤訊息」可複製、變「已複製 ✓」2 秒後復原
• errorCode 以 mono 字型顯示

7.4 Success toast 行為

• toast 顯示「{deviceName} 升級成功 — 從 X 升級到 Y（耗時 N 秒）」
• toast 停留 6 秒（不是預設 4 秒）
• toast 自動消失、不需手動關
• 升級成功後 Devices 頁自動 refresh、badge 變綠

---

8. 整合驗證（Integration）

8.1 升級期間 SIGTERM 延遲關閉（TDD §8.6.1）

測試步驟：

1. macOS / Linux：找出 server PID（ps aux | grep visiona-local-server 或 visionA-local 控制台顯示）
2. 啟動升級流程（情境 A 或 C、長一點的）
3. 升級到 flashing stage 時、執行 kill -TERM <PID>
4. 預期：
   • server 不立即退出
   • 透過 WS 廣播 server:shutdown-pending event 到 "system" room
   • shutdown 延遲到 firmware task 完成（最多 firmware.MaxShutdownWait = 220s）
   • firmware task 跑完才走原本 graceful shutdown 流程
5. 觀察 server log、應有：
   • firmware: N active firmware task(s) detected, delaying shutdown up to ...
   • firmware task 完成後、firmware: all firmware tasks completed, proceeding to shutdown
6. 升級結束後、server 才真正退出
7. Frontend modal 在 server 退出前該完成正常的 upgrade success toast 流程

Pass 條件：

• ✅ server 不在升級進行中退出（不 brick）
• ✅ SIGTERM event log 有 delaying shutdown 紀錄
• ✅ 升級成功完成、device 升級後狀態正常

8.2 Wails OnBeforeClose force-quit modal（TDD §8.6.2 + visiona-local/firmware_close_guard.go）

測試步驟：

1. 任一平台 + 任一 chip
2. 啟動升級流程（情境 A 或 C）
3. 升級到 flashing stage 時、點 Wails 視窗的 ✕ 關閉按鈕（macOS：紅色關閉、Windows：右上 ✕、Linux：window manager close）
4. 預期：
   • Wails 視窗 不關閉
   • Wails 收到 OnBeforeClose 後查 /api/firmware/active-tasks → hasActive: true
   • emit Wails event app:firmware-in-progress 帶 task payload
   • Frontend modal 攔截、顯示「韌體切換進行中、為避免裝置損毀、無法關閉應用程式」
   • modal 顯示 task info：device name / chip / direction / stage / elapsedMs / etaSeconds
   • modal 顯示「繼續等待」（primary、回到原本升級流程）+ 「強制關閉」（destructive）按鈕
5. 點「強制關閉」、預期第二層 FORCE 確認 modal（要使用者輸入「FORCE」字串）
6. 不輸入 / 取消 → 升級繼續、modal 關閉、Wails 視窗回到正常
7. 輸入「FORCE」+ 確認 → ConfirmForceClose binding 被叫、Wails 走 graceful shutdown（會 brick 裝置、風險已接受、Design §6a）
8. 升級正常結束（不點強制關閉的情境）後、再點 ✕ → Wails 正常關閉

Pass 條件：

• ✅ 升級進行中視窗無法關
• ✅ force-quit modal 顯示 + payload 正確
• ✅ 第二層 FORCE 確認可運作
• ✅ 升級完成後視窗正常可關

8.3 升級期間 server crash 容忍

測試步驟：

1. 升級進行中、kill -9 <server-PID>（強制殺、不走 graceful shutdown）
2. Frontend WS 應於 3 秒內偵測到斷線、自動重連嘗試
3. server 重啟後（手動 / Wails 自動）、Frontend bootId 機制應觸發 reload
4. Devices 頁應重新 scan、卡片回到「device 連線中」或「沒有 device」狀態
5. 觀察 dongle 實體狀態 — 可能 brick（取決於升級 stage、屬接受風險、TDD §8.6.1 hard timeout 後也走 shutdown）

Pass 條件：

• ✅ Frontend 不卡死、UI 可繼續操作
• ✅ Server 重啟後狀態正常
• ⚠ Dongle 可能 brick（屬接受風險、需給技術支援 SOP 救磚）

---

9. 自動化腳本對照表

測試類型	涵蓋方式	對應檔
Backend smoke schema 對齊（MJ3）	已修、go test 全綠	server/internal/api/ws/firmware_ws_test.go
Frontend store 邏輯	已有 vitest 60 tests 全綠	frontend/src/tests/stores/firmware-store.test.ts
Frontend component（badge / error view）	已有 vitest 全綠	frontend/src/tests/components/firmware-*.test.tsx
E2E happy path（mock WS + UI）	M9-5 新增 vitest 風格	.autoflow/06-testing/scripts/firmware-upgrade-happy-path.spec.ts
E2E 失敗注入（8 reason × UI）	M9-5 新增 vitest 風格	.autoflow/06-testing/scripts/firmware-upgrade-error-recovery.spec.ts
E2E R-FW-11 modal 不可關	M9-5 新增 vitest 風格	.autoflow/06-testing/scripts/firmware-r-fw-11-modal-not-closable.spec.ts
E2E Wails OnBeforeClose 攔截邏輯	M9-5 新增（unit-style on Go）	.autoflow/06-testing/scripts/wails-onbeforeclose-firmware-active.spec.ts
三平台實機驗證	人工 checklist	.autoflow/06-testing/scripts/manual-checklist-{macos,windows,linux}.md

注意：因為 visionA-local 沒有 Playwright / Cypress、實機驗證需要實體 dongle、E2E 腳本走 vitest + RTL + mock WS / mock fetch 路線，模擬 backend 整條 stage 流轉、frontend 跑真實 component build。實機驗證走人工 checklist（§12）。

---

10. 通過 / 失敗判定規則

10.1 P0（阻擋發布）

任一發生 → A 階段不可進入發布流程：

• Functional 升級成功率 < 90%（24 combo 中 ≥ 3 個失敗）
• 升級期間 server crash / panic
• 升級期間 dongle 100% brick（無法復原）
• §8.1 SIGTERM 期間 server 不延遲關閉（直接中斷 firmware task）
• §8.2 Wails 視窗在升級進行中可直接關閉（OnBeforeClose 沒生效）

10.2 P1（嚴重但可繞過）

任一發生 → 開 P1 bug ticket、視 release window 決定是否阻擋：

• 升級時長 > 護欄但 < 護欄 × 1.5（KL520 60-90s / KL720 200-300s）
• Frontend store 多裝置隔離失效（兩個 progress modal 互相覆蓋）
• destructive reason 仍顯示 retry 按鈕
• force-quit modal 第二層 FORCE 確認字串可繞過

10.3 P2（一般問題）

• Badge 顏色顯示錯誤（如 older 顯示成 current）
• toast 持續時間錯誤
• i18n key 漏譯 / 文案錯誤

10.4 P3（改善建議）

• progress event 推送頻率太低（卡頓 > 5s）
• error modal 「技術資訊」展開後排版錯亂

---

11. Bug 回報格式

對每個發現的問題，使用以下格式回報到 .autoflow/06-testing/bugs/M9-5-BUG-{NN}.md：

# M9-5-BUG-NN: [標題]

## 嚴重程度：P0 / P1 / P2 / P3
## 發現方式：Functional / Reliability / Performance / UX / Integration
## 環境：macOS 14.3 / Windows 11 / Ubuntu 22.04
## 對應驗證：§4.1 情境 A / §5.1 #3 loader_write_failed / etc.
## 對應 AC：AC-FW-1.X / R-FW-11 / R-FW-13

## 重現步驟
1. ...
2. ...

## 預期行為
（依 PRD / TDD / Design Spec、引用具體章節）

## 實際行為
（觀察到的差異）

## 截圖
（路徑：.autoflow/06-testing/screenshots/M9-5-bug-NN-{step}.png）

## Server log 片段

（從 ~/Library/Application Support/visiona-local/wails.log 或對應位置）

## Frontend WS event log

（從 browser DevTools Network → WS frames）

## 建議修復方向（如有）
（不一定要、但 testing 觀察過程的線索）

---

12. 下週執行建議順序（給使用者）

12.1 第 1 天：smoke + happy path（必驗、~3 小時）

優先順序：

1. macOS × KL520 × KDP2 short-circuit（最快、不需 KDP1 dongle、5 分鐘）
2. macOS × KL520 × KDP1 → KDP2 完整升級（happy path 核心、10 分鐘）
3. macOS × KL720 × 升級（單一 chip 驗證、5 分鐘 + 3 分鐘升級 = 10 分鐘）
4. 重複 1-3 在 Windows
5. 重複 1-3 在 Linux

→ 若 macOS 1-3 全綠、且 Windows / Linux 至少 1 個 combo 綠、可進入第 2 天。 → 若 macOS 任一失敗：停下、回報 bug、不繼續其他平台。

12.2 第 2 天：reliability + UX（4 小時）

對 macOS（或第 1 天最穩的平台）跑：

1. R-FW-11 modal 不可關（5 分鐘）
2. Badge 4 色顯示（10 分鐘）
3. 失敗注入 #1 scan_not_found（5 分鐘）
4. 失敗注入 #3 loader_write_failed（10 分鐘）
5. 失敗注入 #4 upgrade_mid_failed（10 分鐘）
6. 失敗注入 #5 disconnect_during_op（10 分鐘）
7. 失敗注入 #6 timeout（10 分鐘）
8. UX checklist：toast / 復原 UI / mailto: 開啟（30 分鐘）

再對 Windows + Linux 跑 #5 disconnect_during_op + #4 upgrade_mid_failed（兩個 brick risk 最高的）作為 sanity check。

12.3 第 3 天：integration（2-3 小時）

對任一最穩平台跑：

1. §8.1 SIGTERM 延遲關閉（macOS / Linux 推薦、Windows SIGTERM 不直觀）
2. §8.2 Wails OnBeforeClose force-quit modal（三平台都要驗）

12.4 整體建議優先順序

P0 must-have（必跑）：
  - §4.1 情境 A × 三平台（核心 happy path）
  - §4.1 情境 B × 三平台（short-circuit 驗證）
  - §8.2 Wails OnBeforeClose × 三平台（避免 brick）

P1 should-have（強烈建議）：
  - §4.1 情境 C × 三平台（KL720 驗證）
  - §5.1 #5 disconnect_during_op × 三平台（brick 風險最高）
  - §8.1 SIGTERM × macOS + Linux
  - §7.3 失敗 modal 復原 UI × 至少一個平台

P2 nice-to-have（時間允許）：
  - §4.1 情境 D 來回升級 × 任一平台
  - §5.1 #1-4 + #6 其他失敗注入
  - §6 effective 時長量測

---

13. Pass → Next-step / Fail → 派工建議

13.1 Pass（所有 P0 都綠 + P1 大部分綠）

→ A 階段可進入發布流程：

1. 給 Orchestrator 「A 階段交付」訊號
2. Orchestrator 啟動 Reviewer agent 對 M9-5 plan + scripts + manual checklist 做最終 review
3. Reviewer 通過後、A 階段五人天宣告完成、可進入：
   • 法律合規確認（Kneron firmware redistribution 授權、R-FW-5 / Q-FW-1）
   • 發布 A 階段 visionA-local（含 KL520/KL720 升級 only、KL630/KL730 延 B 階段）
   • 或 進入 B 階段 M9-6 強驗證 + M9-7 啟動

13.2 Fail（任一 P0 失敗 / 多個 P1 失敗）

依失敗類型分流派工建議：

Fail 類型	派誰
§4.1 升級流程崩潰、stage 不正確	Backend（修 firmware_handler / bridge.py / driver）
§5 reason 對應錯誤、UI friendly message 沒顯示	Frontend（修 firmware-store errorMessageKeyFor / firmware-error-view）
§6 時長 ≥ 護欄	Backend（調 bridge.py timeout 或優化流程）
§7.1 Badge 4 色錯誤	Frontend（修 firmware-badge computeBadgeState）
§7.2 R-FW-11 modal 可關	Frontend（修 firmware-upgrade-dialog onOpenChange）
§8.1 SIGTERM 不延遲	Backend（修 firmware/shutdown.go + server/main.go signal handler）
§8.2 Wails 視窗可關	Wails layer（修 visiona-local/firmware_close_guard.go + frontend modal）

回報給 Orchestrator 的 escalation 範本：

[M9-5 驗證失敗]
- 失敗 combo：[macOS × KL520 × KDP1→KDP2 / 情境 A]
- 失敗類型：[P0 升級流程崩潰]
- bug ticket：.autoflow/06-testing/bugs/M9-5-BUG-NN.md
- 建議派工：Backend（修 bridge.py upgrade_mid 處理）
- A 階段交付狀態：阻擋

---

14. 附錄

14.1 重要 log 位置

平台	wails.log	server.log
macOS	~/Library/Application Support/visiona-local/wails.log	~/Library/Application Support/visiona-local/server.log
Linux	~/.local/share/visiona-local/wails.log	~/.local/share/visiona-local/server.log
Windows	%APPDATA%\visiona-local\wails.log	%APPDATA%\visiona-local\server.log

14.2 重要 WS endpoint

• ws://127.0.0.1:<port>/ws/devices/:id/firmware-progress — firmware progress room
• broadcast type=firmware_progress、stage=preparing|loading|flashing|verifying|done|error

14.3 重要 API endpoint

• POST /api/devices/:id/firmware/upgrade — 觸發升級
• GET /api/firmware/active-tasks — 查詢進行中 task（Wails 用）

14.4 主要相依檔（給 bug 回報時引用）

檔	角色
server/internal/firmware/service.go	升級 service goroutine
server/internal/firmware/shutdown.go	SIGTERM graceful shutdown
server/internal/api/handlers/firmware_handler.go	API + WS broadcast
server/scripts/kneron_bridge.py	bridge.py upgrade handler
visiona-local/firmware_close_guard.go	Wails OnBeforeClose
frontend/src/components/firmware/firmware-upgrade-dialog.tsx	modal lifecycle
frontend/src/stores/firmware-store.ts	phase / reason mapping

---

變更紀錄

日期	版本	變更	作者
2026-05-25	v1.0	初版 — M9-5 三平台實機驗證 plan + 自動化腳本對照表 + 人工 checklist 索引 + 下週執行建議順序	Testing Agent