visionA/local-tool/.autoflow/05-implementation/review/m9-4-frontend-firmware-review-round2.md

# M9-4 Reviewer Round 2 — Frontend FW UI（第 2 輪修改驗證）

> 審查日期：2026-05-25
> Reviewer：Reviewer Agent
> 審查對象：Frontend 第 2 輪修改（i18n namespace 重組 + 3 Major + 8 Minor 修法驗證）
> 審查層：A 層（per-task delta）
> 第 1 輪報告：`.autoflow/05-implementation/review/m9-4-frontend-firmware-review.md`

---

## TL;DR

- **第 2 輪審查結果：✅ 通過**
- **MJ1 方案選擇：接受方案 A（namespace = `settings.firmware.*`）** — 採納 Frontend 的 pushback、Design Spec §9 v2.2 為 SoT、未做正式 Design Spec 改寫前 Reviewer 不該翻案
- **第 1 輪 issue 修了 / 沒到位**：12/12 應修項全部到位、3 項刻意留 follow-up（Frontend 給的理由合理）、1 項 backend 不適用本輪（MJ3 屬 Backend / Testing 範圍）
- **第 2 輪新發現**：0 Critical / 0 Major / 0 Minor / 2 Suggestion（都屬 nice-to-have、不阻擋）
- **是否阻擋 M9-5**：否
- **是否需 Frontend 第 3 輪**：否
- **是否升 Security Auditor**：否（ContactSupport mailto handler 已驗證安全、無 XSS / open redirect）

---

## 方法說明

本輪採「delta-only」審查：不重審第 1 輪已通過細節（避免疲勞與 false positive），聚焦：
1. 第 1 輪每條 issue 是否真的修了 / 修對方向
2. 修改本身是否引入新問題（regression）
3. 9 個新 FirmwareErrorView tests 品質

完整 5 軸 / 文件符合性 / B 層跨檔案比對等已在第 1 輪報告做過、本輪不重做。

---

## MJ1 方案選擇（Frontend pushback 評估）

### Frontend 主張方案 A 的理由

1. Design Spec v2.2 §9 是三方對齊後的正式 SoT、未做正式 Design Spec 改寫前 Frontend 不該自行翻案
2. B 階段 M9-12 會加入 `settings.firmware` 下 §9.1 page 結構 / §9.2 device card label / §9.3 switch accordion / §9.5 downgrade modal 等更多 keys；現在 flat 結構 (`firmware.*`) 之後 M9-12 切換成 `settings.firmware.*` 會造成兩批 keys 分散維護

### Reviewer 評估

| 評估面向 | 結論 |
|---------|------|
| Design Spec §9 v2.2 是否正式 SoT | 是。三方 v2.2 已對齊、本輪 review 不應翻案 |
| 方案 A 是否會與既有 i18n 結構衝突 | 不會。`settings` 是既有 namespace、`settings.firmware` 是合理子結構（types.ts:305 加註解明示「§9.1 page / §9.2 card label / §9.3 accordion / §9.5 downgrade modal 留待 M9-12 補」、forward-compatible） |
| 方案 A vs B 的長期維護成本 | A 更低。B 階段一定要落 `settings.firmware.*`、現在做 A 等於一次到位、避免 M9-12 再 rename 一次（耗 PR + 影響 i18n test snapshot） |
| Reviewer 第 1 輪偏好 B 的理由（commit cost 低、命名更簡潔）| 不成立。Frontend 已用 trivial rename + 更新 22 既有 test、cost 實測也很低；「命名簡潔」對單一檔案有意義、但跨 PRD/Design/i18n/code 對照查找時 namespace 對齊更值錢 |

**Reviewer 最終決定**：**接受方案 A**。Frontend 的 pushback 邏輯成立、Design SoT 應優先於 Reviewer 個人偏好。本輪 MJ1 視為通過。

---

## 第 1 輪 issue 修改驗證（逐項）

### Major（3 項）

| Issue | 第 1 輪要求 | 第 2 輪修法 | 驗證結果 |
|-------|------------|------------|---------|
| **MJ1** i18n namespace 與 §9 不一致 | 二擇一：A 搬到 `settings.firmware.*` / B 改 Design Spec | 採方案 A — `types.ts:310-375`、`zh-TW.ts:305-370`、`en.ts:305-370` 三檔同步搬入 `settings.firmware.*`；`firmware-store.ts:151-199` 8 條 errorMessageKeyFor 路徑 + 4 條 primaryActionKeyFor 路徑全改；5 個元件 (`firmware-badge / firmware-upgrade-button / firmware-upgrade-dialog / firmware-progress-view / firmware-error-view`) 所有 t() 呼叫全用新路徑；22 既有 + 9 新 firmware-store.test.ts 同步 | ✅ **完全到位**。grep `t\('firmware\.` 與 `'firmware\.`（不含 `settings.` 前綴）皆 **0 hit**、無死引用 |
| **MJ2** FirmwareErrorView title 硬編碼中文 | 改 `t(...)` + 補 i18n key（或乾脆移除 title） | `firmware-error-view.tsx:158` 改 `title={t('settings.firmware.error.contactSupportTooltip')}`；types.ts:372 / zh-TW.ts:367 / en.ts:367 三檔都補 `contactSupportTooltip` key（中：「請聯絡技術支援」/ 英：`Please contact technical support`）；同時把 disabled 改 enabled、補 `handleContactSupport` 用 mailto: 開啟（line 81-88）— 算修 MJ2 + M6 一併 | ✅ **完全到位**。額外修了 M6（disabled ContactSupport 與 UX 衝突）、合理副產品 |
| **MJ3** Backend smoke test schema 用 `phase` 而非 `stage` | Backend / Testing 在 M9-5 階段補 | 本輪 Frontend 範圍外、未動 backend test | N/A — 不屬本輪 frontend 第 2 輪範圍、按計畫由 testing agent 於 M9-5 補 |

### Minor（8 項）

| # | 第 1 輪要求 | 第 2 輪修法 | 驗證結果 |
|---|------------|------------|---------|
| **M1** | 確認 1.5s modal 關閉是否與 §5.4 toast 6s 相容、加註解 | `firmware-upgrade-dialog.tsx:103-104` 註解明寫「modal 1.5s 後關閉、toast 由 showSuccess 自身 6s duration 控制」+ AC-FW-1.3 5 秒提示 | ✅ 到位 |
| **M2** | 補 TODO 條目給 M9-12 追蹤對比 | `firmware-badge.tsx:39-41` 新增 `TODO(M9-12)` 註解明示用 axe-core 實測對比、< 4.5:1 改 component token、特別注意 amber-400 + emerald-500 暗模 | ✅ 到位 |
| **M3** | 確認 estimatedDurationSeconds fallback 語意統一 / 加註解 | `firmware-store.ts:202-217` 整段 JSDoc 改寫「兩種 fallback 數值不同是刻意的：『不知道有沒有 type』和『有 type 但認不出』資訊量不同」；test (`firmware-store.test.ts:247-253`) 註解同步說明 | ✅ 到位（決定保留差異 + 文件化、合理） |
| **M4** | showSuccess 預設停留是否符合 §5.4 6 秒、不足要加 duration | `lib/toast.ts` 加 `ToastOptions { duration?: number }`、4 個 toast helper 都支援；`firmware-upgrade-dialog.tsx:99` 用 `{ duration: 6000 }` 顯式傳；註解引用 Reviewer M1+M4 | ✅ 到位 |
| **M5** | 補 FirmwareErrorView 元件渲染測試 | 新檔 `tests/components/firmware-error-view.test.tsx` 共 9 tests：destructive 3 種 brick warning + ContactSupport（it.each）/ contact mailto 點擊 / recoverable 2 種 / errorCode 顯示 / collapsible 預設收合 / Close callback | ✅ 到位（品質評估見下節）|
| **M6** | disabled ContactSupport 改 enabled + 實際動作 | `firmware-error-view.tsx:81-88` 加 `handleContactSupport`：mailto: + subject 帶 errorCode + body 帶 technicalInfo + `target="_blank"`；line 153-162 改用 destructive variant + onClick | ✅ 到位 |
| **M7** | 移除 device-card.tsx 與 button 元件的雙重 firmwareCanUpgrade gate | `device-card.tsx:61-64` 註解明示「由 FirmwareUpgradeButton 內部決定」、實際 JSX 直接 `<FirmwareUpgradeButton device={device} disabled={isBusy} />` 無 `device.firmwareCanUpgrade &&` 外層 gate；單一責任落地 | ✅ 到位 |
| **M8** | 把 fetchActiveFirmwareTasks 移到專用檔 / 加註解說明刻意設計 | `firmware-store.ts:253-262` 補完整 JSDoc「刻意設計為 module-level helper、不放 store action」+ 三個理由（無 reactive state / Wails callback / 不需 subscribe）；位置保留在 store 檔（Frontend 選擇文件化而非移檔） | ✅ 到位（文件化方案合理、避免 churn）|

### Suggestion（5 項）

| # | 第 1 輪建議 | 第 2 輪處置 | 驗證結果 |
|---|------------|------------|---------|
| **S1** | 對齊 §5.1 寬度 480px | `firmware-upgrade-dialog.tsx:157-158` 加 `className="sm:max-w-[480px]"` + 註解引用 Reviewer S1 | ✅ 修了 |
| **S2** | M9-5 testing 階段加 stage-percent 對照測試 | 留 follow-up 給 Testing Agent M9-5 階段 | ⏸ 合理保留 — 屬 testing agent / E2E 範圍 |
| **S3** | Dialog selector 優化 re-render | 留 follow-up — 屬 perf nice-to-have、非問題 | ⏸ 合理保留 |
| **S4** | FirmwareUpgradeDialog integration test | 留 follow-up — 屬 Testing Agent M9-5 / M9-12 範圍 | ⏸ 合理保留 |
| **S5** | 抽 formatTechnicalInfo helper | `firmware-error-view.tsx:23-40` 抽出 `formatTechnicalInfo(progress: FirmwareProgressEvent): string`、JSDoc 引用 Reviewer S5；handleCopy + `<pre>` + handleContactSupport 三處共用同一輸出 | ✅ 修了（且額外用在 mailto body、複用更廣）|

**統計**：應修 / 已修 = 12 / 12（含 MJ1 / MJ2 / 8 Minor + S1 / S5），刻意保留 3 項（S2 / S3 / S4），不適用本輪 1 項（MJ3 屬 Backend）。

---

## 9 個新 FirmwareErrorView tests 品質評估

檔案：`frontend/src/tests/components/firmware-error-view.test.tsx`（165 行）

| Test 群組 | 覆蓋 | 品質 |
|---------|------|------|
| destructive reasons（3 種）`it.each` brick warning + 不顯示 Retry + 顯示 ContactSupport | `disconnect_during_op / verify_mismatch / verify_not_found` | 高 — 用 `it.each` 涵蓋三種、`getByRole('note')` 驗 brick warning、`getAllByRole('button')` + label 對比驗 Retry 不存在 + ContactSupport 存在 |
| ContactSupport mailto 點擊 | `vi.spyOn(window, 'open')` mock + `fireEvent.click` + 檢查 href schema `^mailto:` + decodeURIComponent body 含 stage / reason | 高 — 安全驗證到位（href 是 mailto: scheme 不是 http:）、技術資訊真的進 body |
| recoverable reasons（2 種）顯示 Retry | `connect_failed` Retry 按鈕 + onRetry callback；`scan_not_found` 顯示 ReplugRetry | 高 — `queryByRole('note')` 確認沒 brick warning（negative case）、`fireEvent.click` 驗 callback |
| errorCode 顯示 | `getAllByText(/FW_E102/).length >= 1`（同時在 `<p>` 與 `<pre>` 出現、刻意接受兩處）| 中-高 — 接受重複出現是對的、若用 `getByText` 會誤判 |
| collapsible 預設收合 | `container.querySelector('details').open === false` | 高 — 直接驗 DOM state |
| Close 觸發 onClose | `fireEvent.click(closeBtn) → onClose 1 次` | 高 |

**整體評估**：
- ✅ 用 `it.each` 涵蓋三 destructive reason、簡潔且維護友善
- ✅ 用 i18n label regex `/Contact|聯絡技術支援|Support/` 同時兼容中英環境、CI 切 locale 不會 fail
- ✅ jsdom `window.open` mock 寫法正確（spyOn + mockImplementation(() => null)）
- ✅ 驗 mailto href schema 是安全把關（防止意外被改成 http: 開外部頁面）
- ⚠️ 缺 **handleCopy** 測試（clipboard write 行為）— 第 1 輪 review 也沒列、不算缺陷、屬 nice-to-have
- ⚠️ 缺 **techOpen toggle** 測試（onToggle 後 open=true）— 同上、屬 nice-to-have

**結論**：9 個 tests 品質高、達到第 1 輪 M5 要求；漏的兩項屬 nice-to-have、不阻擋本輪通過。

---

## 第 2 輪新發現

### Critical

無。

### Major

無。

### Minor

無。

### Suggestion

| # | 檔案 / 位置 | 建議 |
|---|------------|------|
| **R2-S1** | `firmware-error-view.tsx:81-88` `handleContactSupport` | mailto: 地址 `support@kneron.com` 硬編碼在元件內。雖然 mailto 不會被 attacker 替換（純 link）、但若日後 support email 改 / 多語系不同 region 不同信箱、會要改元件本身。可考慮把 `MAILTO_SUPPORT` 抽到 `lib/config.ts` 或讀 i18n（不過 mailto 地址通常不 i18n）。屬 nice-to-have、不阻擋。 |
| **R2-S2** | `tests/components/firmware-error-view.test.tsx` | 缺 handleCopy 測試（clipboard 行為 + copied state 切換 2s 後 reset）+ techOpen toggle 測試。可在後續任務（M9-12 或 testing 補充階段）補。屬 nice-to-have、不阻擋本輪。 |

---

## Regression 檢查（修改本身是否引入新問題）

| 風險點 | 檢查結果 |
|-------|---------|
| **i18n namespace 重組漏 key** | grep `t\('firmware\.`（不含 settings 前綴）= 0 hit；grep `'firmware\.` 同 0 hit。所有舊路徑 100% 切完。中英對齊：types.ts:310-375 vs zh-TW.ts:305-370 vs en.ts:305-370 同 namespace 結構、所有 key 三邊都有對應（無 missed key） |
| **ContactSupport mailto 安全性** | mailto: scheme 是 RFC 6068 standard、不會觸發 XSS（不執行 JS）；target="_blank" 不引入 open redirect 風險（mailto: 由 OS 端 mail handler 處理、不會是 http:）；subject + body 用 `encodeURIComponent` 包裝、即使 progress.errorCode 內含特殊字元也安全 |
| **formatTechnicalInfo helper rawError leak** | helper 抽出後同時用在 (a) handleCopy clipboard / (b) `<pre>` 區 / (c) mailto body — 三處都是「使用者主動觸發 + 預設收合的 details / 主動點 copy / 主動點 contact」、不是被動曝露在主畫面；rawError 行只在有值時才加（line 37 `if (progress.rawError)`）；無 leak 到非預期位置 |
| **toast duration 6s 修改** | `lib/toast.ts` 改成支援 `ToastOptions`、向下相容（既有 caller 不傳 options 用 sonner 預設 4000ms）；只有 firmware-upgrade-dialog.tsx:99 顯式傳 6000；不影響既有 toast 行為 |
| **22 既有 firmware-store test 是否同步更新** | 看 firmware-store.test.ts:168-234 — 8 條 errorMessageKeyFor 直接 reason / 4 條 stage fallback / 7 條 primaryActionKeyFor 全部 expect 字串都改為 `settings.firmware.error.message.*` / `settings.firmware.error.action.*`，namespace 對齊完整 |
| **device-card.tsx 移除外層 gate** | line 64 `<FirmwareUpgradeButton device={device} disabled={isBusy} />` 無 `device.firmwareCanUpgrade &&`；FirmwareUpgradeButton.tsx:26 內部 `if (!device.firmwareCanUpgrade) return null` 守住、不會 render；isBusy disabled 條件保留、避免 race；single responsibility 落地 |
| **estimatedDurationSeconds 行為未變** | 函數 line 212-217 邏輯仍是 `if (!deviceType) return 60; if includes('kl720') return 180; return 30`、回傳值未變、test 三個 expect 也未變、只是 JSDoc + test 註解補充說明刻意設計 |

無 regression。

---

## §12.2 通用退出條件（6 條、Round 2 重檢）

| # | 條件 | 狀態 |
|---|------|------|
| 1 | No silent failures | ✅ 未觸發。`firmware-error-view.tsx:74-77` clipboard reject 靜默是 design 規格允許；新 handleContactSupport 失敗（window.open 回 null）也是 OS handler 沒 mailto 程式、不是 silent failure（mailto 已被 OS 開啟） |
| 2 | No dead code | ✅ 未觸發。grep TODO / FIXME 只在 `firmware-badge.tsx:39 TODO(M9-12)` — 是預留 M9-12 任務追蹤、不是 dead code |
| 3 | No hardcoded secrets | ✅ 未觸發。mailto: `support@kneron.com` 不算 secret（公開聯絡信箱）；R2-S1 提到 nice-to-have 抽常數 |
| 4 | No unsafe HTML / SQL | ✅ 未觸發。grep `dangerouslySetInnerHTML / v-html` = 0 hit；mailto subject + body 用 `encodeURIComponent` 包；React template literal 全自動 escape |
| 5 | Doc 同步 | ✅ 觸發已解。第 1 輪 MJ1 已修、namespace 100% 對齊 Design Spec §9 |
| 6 | Working tree clean | N/A — reviewer 自己只產 report |

---

## A 層 verification（Round 2 simplified）

本輪屬 delta-only review、不重做第 1 輪完整 5 軸；以下為 Round 2 必過項：

- [x] **R-A1（delta）**：逐項驗每條第 1 輪 issue 的修法（見「第 1 輪 issue 修改驗證」表）
- [x] **R-A2**：i18n namespace 重組後 PRD/TDD/Design Spec §9 對齊一致（grep 0 hit 死引用 + 中英 + types 三邊對齊）
- [x] **R-A3**：第 2 輪新發現 0 Major、2 Suggestion 都附建議
- [x] **R-A4**：優點段落見下節
- [x] **R-A5**：Needs investigation：0（本輪所有疑點都已決議）
- [x] **R-A6**：§12.2 通用 6 條全跑過

---

## 優點（R-A4）

1. **Frontend 的 pushback 邏輯紮實**：採方案 A 並用 SoT 論證、加 forward-compatible 註解（types.ts:303-309）讓 M9-12 接手更平順、不是被動接受 reviewer 也不是無腦堅持。是好的協作姿態。
2. **M6 「順便修」做得對**：第 1 輪只標 disabled / UX 衝突、Frontend 把它升格為實際可用按鈕（mailto + subject + body 帶 errorCode + technicalInfo）；不只修「Reviewer 抓出來的」、還主動改善 UX。
3. **formatTechnicalInfo helper 抽出後三處共用**：handleCopy / `<pre>` / handleContactSupport mailto body —— S5 不只解決 readability、實際讓「複製 vs 寄信」內容保證一致、是有實效的重構。
4. **i18n duration: 6000 配 §5.4** + lib/toast.ts 補 ToastOptions API：解 M4 同時把 toast util 介面 forward-compatible（未來其他 toast 也能調 duration），不是只 patch firmware-upgrade-dialog 一處。
5. **9 個新 FirmwareErrorView tests 涵蓋完整**：mailto href schema 驗證（`^mailto:`）+ body decodeURIComponent 內容驗證、是測試到「行為 + 安全」兩面、不是只測 render。
6. **JSDoc 引用 Reviewer ticket 編號**：`(Reviewer S5)` / `(Reviewer M1+M4)` / `(Reviewer S1)` / `(M3 釐清)` — 修改可追溯回 review 條目、未來看 code 知道為什麼這樣寫。
7. **M3 處置成熟**：沒急著統一 fallback 數值（避免行為 regression）、改用 JSDoc + test 註解雙重文件化「刻意設計」；是「文件化 over 程式變更」的好範例。

---

## 結論

**Round 2 審查結果：✅ 通過、無需 Frontend 第 3 輪**

第 1 輪 12 項應修 issue 全部到位、3 項刻意 follow-up 理由合理、1 項 (MJ3) 屬 Backend 範圍按計畫外延。MJ1 採方案 A 是正確選擇、Frontend pushback 邏輯成立、Reviewer 接受。第 2 輪新發現僅 2 個 Suggestion、都屬 nice-to-have、不阻擋。

**是否阻擋 M9-5**：否。本輪完全不阻擋 M9-5 三平台 KL520+KL720 實機 E2E。

**是否需 Frontend 第 3 輪**：否。除非 M9-5 階段 testing agent 發現新 issue、否則 M9-4 frontend 部分本輪結案。

**剩餘待 follow-up**（非阻擋）：
- MJ3：Backend smoke test schema、由 Testing Agent / Backend Agent 在 M9-5 階段補
- S2：stage-percent 對照測試、Testing Agent M9-5
- S3：Dialog selector 優化、perf nice-to-have
- S4：FirmwareUpgradeDialog integration test、Testing M9-5 / M9-12
- R2-S1：mailto 地址抽常數、nice-to-have
- R2-S2：handleCopy / techOpen toggle 測試、nice-to-have

**是否升 Security Auditor**：否。ContactSupport mailto handler 已驗證安全（RFC 6068 scheme + encodeURIComponent + 不引入 XSS / open redirect / hardcoded secret）。