# PM 互審報告：Architect TDD v2.2 + Design v2.2 firmware

> 審查日期：2026-05-24
> 審查者：PM Agent
> 對應 PRD：`.autoflow/02-prd/features/feature-firmware-management.md` v2.2-draft
> 審查範圍：
> - `.autoflow/04-architecture/v2/firmware-management.md`（TDD v2.2，466 行）
> - `.autoflow/04-architecture/adr/ADR-001-firmware-management.md`（152 行）
> - `.autoflow/03-design/v2/firmware-management.md`（Design v2.2，920 行）

---

## TL;DR

**整體結論：通過 with Minor + 少數 Major**。三份文件對 PRD 的 4 個 user story（US-FW-1 ~ US-FW-3）與成功指標的覆蓋度極高、R5-Q9 翻案的範圍切割與 PRD 完全一致、ADR-001 寫得清楚可追溯。

但有 **3 個 Major 問題**需要 Architect / Design 修改後才能 merge：
1. PRD 寫了 US-FW-2 包含「進階使用者切換 FW 版本」的 user story（含「就是想試試看」「測試環境」等情境），但 Design 文案策略卻是「**對一般使用者過於負面**、用『版本切換』中性詞」——這兩個 framing 的隱含 persona 不一致、PM 需與 Design 對齊
2. ADR-001 編號錯誤：PRD 引用的是 ADR-009（`feature-firmware-management.md` §2.5 / §11.4），但實際檔名是 ADR-001——需統一
3. R5-Q9 行號爭議（L776 vs L854）PM 在 PRD 明示要 Architect cross-check、但 ADR-001 + TDD 沒有處理這點

另外有 **8 個 Minor**（建議改但不阻擋）、4 個建議性回饋。詳見下方分項。

---

## 對 Architect TDD 的審閱

### 🟢 通過項

1. **§1.1 痛點對應 PRD §1.1 完全一致**：3 個列出的痛點（拿到 KDP1 不能用 / KL520 Error 15 / KL630/KL730 偵測不到）與 PRD §1.1 + §1.2 對齊
2. **§1.2 範圍邊界對應 PRD §2.4 完全一致**：「升級到官方 KDP2 標準版本」做、「使用者燒任意 model 到 flash」繼續砍——R5-Q9 翻案的範圍切割對齊 PRD §2.4 表格
3. **§3 API 設計覆蓋 PRD US-FW 全部 4 個 user story**：
   - `GET /api/devices` 衍生欄位 → AC-FW-1.1 FW badge
   - `POST /api/devices/:id/firmware/upgrade` → AC-FW-1.2 升級
   - `GET /api/devices/:id/firmware/versions` → AC-FW-2.3 版本列表
   - `POST /api/devices/:id/firmware/downgrade` + `confirmToken` → AC-FW-2.6 / AC-FW-2.9 強制二次確認
   - WebSocket room `firmware:<deviceId>` → AC-FW-1.2 progress modal
4. **§3.3 錯誤碼涵蓋 PRD 8.1 / 8.2 R-FW-1 ~ R-FW-12 對應 mitigation**：6 個錯誤碼（`FW_DEVICE_BUSY` / `FW_VERSION_NOT_FOUND` / `FW_INVALID_DIRECTION` / `FW_NO_CONFIRM_TOKEN` / `FW_UPGRADE_FAILED` / `FW_UPGRADE_BRICK_RISK`）與 PRD §8.1 / §8.2 風險清單對齊
5. **§5.2 降版流程完整對應 AC-FW-2.6 ~ AC-FW-2.10**：二次確認 + DOWNGRADE 輸入 + 不可關 modal + persistent banner + driver guards 都有設計
6. **§8.1 watchServer Error state 解耦對應 AC-FW-1.8**：明示 FW 升降版失敗不觸發 server Error state、與 PRD §8.3「衝突已釐清項」一致
7. **§8.2 KL520 reset bug 對應 PRD §1.1 痛點 #2**：明示「升級成功後 needsReset=true、下次連線走完整 reset、避開 Error 15」——這正是 2026-04-21 fix 機制的延續
8. **§9 工時 15.5 人天對齊 PRD §10.3**：A 5 + B 10.5 = 15.5、milestone 切分 M9-1 ~ M9-13 一致
9. **§10 風險表 R-FW-1 ~ R-FW-12 + R-TAR-1 ~ R-TAR-4 對齊 PRD §8.1 / §8.2**：除編號略有偏移外、實質內容對齊
10. **§11 測試策略涵蓋 AC-FW-1.8（watchServer 不誤判）+ 既有 KL520/KL720 回歸**：§11.4 明示「watchServer 機制不會把 FW timeout 誤判為 server 死亡」、且涵蓋 KL520 / KL720 既有 E2E 回歸

### 🟡 Minor（不阻擋、建議改）

| # | 章節 | 問題 | 建議修法 |
|---|------|------|---------|
| M-A1 | §10 R-FW-5 | 風險表內欄位 `等級` 寫「待釐清」、不是 PRD §8.1 用的「P0（發佈 gate）」 | 統一用 PRD 的 P0/P1/P2/P3 分級語彙、或在 §10 表頭加註「等級 = PRD R-FW 對應的優先級」說明 |
| M-A2 | §11.3 異常路徑測試 | 缺一條「升級 timeout（mock 180s 不回）」對應 AC-FW-1.7「KL720 預估 180 秒」的明確上界測試 | 加一行「KL720 升級實測時長 ≤ 200s（PRD §7.2 護欄）」測試案例 |
| M-A3 | §3.1 API 端點清單 | 表格沒有列出 PRD AC-FW-2.3「版本說明文案」「預估時間」這些 metadata 從哪個 API 取 | 在 `GET /firmware/versions` 的 response 範例中明示是否含 `notes` / `estimatedDurationSec` 欄位（Design §3.3 wireframe 顯示了「2024-08 發行」「與舊模型相容」等資訊、後端需提供） |
| M-A4 | §6.2 chip 判斷 | KL520 / KL720 / KL630 / KL730 product_id 都列了、但 PRD §1.1 痛點表列「KDP1 legacy pid=0x0200」、TDD §6.2 卻把 0x0200 對到 KL720——這是 KL520 KDP1 legacy 還是 KL720？需與 PRD 痛點表對齊 | Architect 互審時確認：0x0200 到底是 KL520 KDP1 legacy（PRD §1.1）還是 KL720（TDD §6.2 L322）。若兩者皆是不同 product_id、PRD §1.1 痛點表應更正為「KDP1 legacy pid=0x0100」或實際正確值 |
| M-A5 | §9 M9-6 「純研究、Architect 自身產出、不過 Reviewer」 | 與 PRD Q-FW-2 「結論定 B 階段 scope」存在關聯——若 SDK 驗證結論是「不支援」、需重派 PM 微調 PRD（PRD §14.2 A-FW-4），但 TDD 沒寫此 reflow 條件 | §9「Reviewer 切點」段落補一條：「M9-6 結論若觸發 AC-FW-3.5 降級條件，須回 Orchestrator 重派 PM 微調 PRD 後再啟動 M9-7」 |
| M-A6 | §13.1 「PM 互審注意」 | Architect 列了 4 個 PM 互審注意點、但漏列 PRD §14.2 A-FW-4 / A-FW-5 / A-FW-6 的 6 個 Architect 待回覆項——PM 不知道哪些是 Architect 已回覆、哪些待回 | §13.1 補一節「PM PRD §14.2 待回覆項對應」列出 A-FW-1 ~ A-FW-6 各自在本 TDD 哪一節已回覆（或標「未處理、留 follow-up」） |

### 🟠 Major（建議改後 merge）

| # | 章節 | 問題 | 建議修法 |
|---|------|------|---------|
| MJ-A1 | 整檔 ADR 編號 | PRD §2.5 + §11.4 明示「ADR-009-firmware-management」、但 Architect 實際檔名是 `ADR-001-firmware-management.md`——這是專案歷史上的第幾個 ADR？與 PRD 引用差 8 號需要解釋 | 三方需對齊：(1) 改 ADR 檔名為 `ADR-009-firmware-management.md`、或 (2) PRD §2.5 / §11.4 改為引用 `ADR-001`。PM 傾向 (1)，因為「009」對應 R5 第 9 個議題、語意較豐富。但若 ADR 編號規則是「按時間順序、本專案第 1 個 ADR」、那 PRD 該改為 ADR-001。需 Architect 確認 ADR 編號規則後統一 |
| MJ-A2 | §1 (整體) | TDD 沒處理 PRD §2.1 標明的「R5-Q9 行號 L776 vs L854 不一致、Architect 互審時 cross-check」 | TDD §1（或新增 §1.4）補一段「R5-Q9 行號釐清」：說明 Architect 確認 progress.md 當前 L854 為 R5 第二輪 Q9 條目、L776 是 research summary 引用的歷史快照行號、決策本身內容一致 |

### 🔴 Critical（必須改、阻擋 merge）

無。Architect TDD 與 PRD 的需求覆蓋度足以推進開發。

---

## 對 Design Spec 的審閱

### 🟢 通過項

1. **§1 定位職責對齊 PRD §3.2 + AC-FW-2.1**：明示「韌體管理在 Settings 第 5 分頁、不在 Devices 頁主流程」、避免誤觸——與 PRD §4 user story 一致
2. **§3.1 ~ §3.3 wireframe 完整覆蓋 US-FW-1 + US-FW-2**：裝置卡片 + FW badge 三色 + 「版本切換」accordion 設計符合 PRD AC-FW-1.1 / AC-FW-2.3
3. **§4 Devices 頁 FW Badge 對應 AC-FW-1.1**：綠 / 黃 / 紅三色 + tooltip + deep-link ⚙ icon、與 PRD US-FW-1 直接對齊
4. **§5 升級流程完整覆蓋 US-FW-1 全部 AC**：
   - §5.1 確認 modal → AC-FW-1.2
   - §5.2 進度 modal 不可中斷 → AC-FW-1.5
   - §5.3 6 stage 對應 → PRD AC-FW-1.2「全程顯示階段」+ TDD §4.3
   - §5.4 成功 toast → AC-FW-1.3「自動關閉 + 觸發 rescan + badge 變綠」
   - §5.5 失敗復原 → §7
5. **§6.1 降版二次確認 modal 對應 AC-FW-2.5 + AC-FW-2.6 + AC-FW-2.7 + AC-FW-2.8 全部**：警告語 4 條、輸入 DOWNGRADE 字串、不可外部關閉、進行中無取消按鈕——一條一條都對上 PRD 的 AC
6. **§6.2 KDP1 額外警告**：超出 PRD AC-FW-2.5 既有 4 條警告語、Design 主動加「KDP1 不支援多模型」這條——這個延伸符合 PRD US-FW-2 第 2 個情境「跟某個 third-party tool 不相容、要回 KDP1」的精神
7. **§7 失敗復原 8 種類型對應 PRD AC-FW-1.4 + AC-FW-2.8**：每種 stage 失敗都有 friendly message + 復原行動、超出 PRD 既有要求
8. **§10 A11y 對應 PRD US-FW-2 一般使用者**：focus trap、aria-live、role="alertdialog"、reduced motion——這對「面向一般使用者」的承諾是必要的
9. **§11.2 新增 6 個 component-level tokens** 不是亂增、有推導表與對比比率驗證
10. **§12 R-FW 風險的 Design 對策**：對應 PRD §8.2 R-FW-11 「一般使用者誤觸降版 brick 風險」、列出 7 條 mitigation 全部對應 PRD AC 條目
11. **§14.4 給 Orchestrator 懸而未決 3 條**：對應 PRD §9 未解決問題、Design 補上 3 個 PRD 沒提到的（i18n 化 / metadata 來源 / 控制台關閉攔截）——這是好的延伸

### 🟡 Minor（不阻擋、建議改）

| # | 章節 | 問題 | 建議修法 |
|---|------|------|---------|
| M-D1 | §9 i18n keys 52 個 | PRD §10.2 引用 research 42 §5.6 估算 46 keys、Design 實際 52 keys——多 6 keys 是合理的（含 settings.tabs.firmware + Devices badge tooltip 4 keys + 1-2 個技術資訊）| 不用改、但 PRD §10.2 應在下次補丁更新為 52 keys、或在當前 PRD 加註「實際以 Design §9 為準」 |
| M-D2 | §3.3 「版本切換」accordion | accordion 樣式對應 PRD AC-FW-2.3 「dropdown」，Design 改用 radio list、§3.3 末段已說明理由（< 3 個版本、a11y 友善）——這是好的延伸但 PRD AC-FW-2.3 文字仍寫「dropdown」 | PRD §4 US-FW-2 AC-FW-2.3 應在下次補丁更新為「radio list 或同等選擇 UI」、或 PM 採納 Design 決定後改 PRD |
| M-D3 | §6.1 「DOWNGRADE」字串 i18n 化 | Design §14.4 第 4 點懸而未決提到、PRD §9 Q-FW-3 「降版」用詞策略已說明 UI 不用「降版」字眼但 PRD 沒明示 DOWNGRADE 字串本身要不要 i18n | PRD §9 應在下次補丁新增 Q-FW-8「DOWNGRADE 字串 i18n 化」對應 Design §14.4 第 4 點 |
| M-D4 | §3.1 裝置卡片配色 | 圓點 🔴 / 🟡 / 🟢 對應 PRD AC-FW-1.1 三色 badge、但 Design 把「KDP1」+「has newer」都用紅色（Design L101）vs PRD AC-FW-1.1 寫「黃 = 比 current 舊但可升」、「紅 = legacy KDP1 或損毀」——Design 表格分了 3 colour 但 wireframe 圖示 KDP1 用紅、PRD 文字寫「v2.1.0」應為黃。需確認 wireframe legend 是否清楚 | Design wireframe 加註釋「KDP1 → 紅 / v2.1.0 較舊 → 黃 / v2.2.0 current → 綠」，避免讀者只看 wireframe 不看 §3.1 表格時誤解 |
| M-D5 | §11.2 token Dark 模式對比 | Design 自己標「Architect 互審重點：請確認 Dark 模式下 `legacy.fg` 用黑色對紅底對比是否真的足夠（推算 4.8:1、但實作時需用 contrast checker 工具驗證）」 | 這個是 Architect 互審的事、不是 PM 互審範圍。但 PM 確認：對比 4.8:1 達 WCAG AA（≥ 4.5:1）、不違反 PRD 對 a11y 的承諾。Design 可以將 §11.2 結尾「Frontend 需用 contrast checker 工具驗證」改為更明示的 AC（如「實作後 Frontend M9-12 驗收必跑 axe-core / Lighthouse a11y 測試、對比比率必達 4.5:1」） |

### 🟠 Major（建議改後 merge）

| # | 章節 | 問題 | 建議修法 |
|---|------|------|---------|
| MJ-D1 | §2.1 「分頁名稱不能叫『降版』——對一般使用者過於負面」 vs PRD §5.1 / US-FW-2 | **這是本次互審最大的 framing 分歧**：PRD §5.1 引用 architect research 42 結論、明示「手動降版面向一般使用者」、§5.3 列出 5 個情境（含「就是想試試看」「測試環境」）。Design §2.1 卻說「降版對一般使用者過於負面、一律稱『韌體』或『韌體管理』」——這兩個 framing 的隱含 persona 不一致：PRD 把一般使用者當「有能力理解風險的進階使用者」、Design 把一般使用者當「需要保護不要看到負面詞彙的非技術使用者」。需 PM + Design 對齊「一般使用者」的具體定義 | **建議方案**：PRD + Design 對齊到 Design 立場（UI 文案中性、`downgrade` 只留技術文件）、因為 R5 Persona 表已明示 P1 是 FAE / P2 是「外部開發者」、但實際 dongle 也會給「跟著開發者一起使用的客戶現場 demo 觀察者」、後者並非技術人員。PRD §5.1 H3 假設「藏在 dev mode 反而讓真正需要降版的人找不到」仍成立、Design §2.1 中性文案不違反此假設。**具體修法**：PRD §9 Q-FW-3 「降版這個詞是否用於 UI 文案」應從「待 Design Agent 最終決定」改為「已決定：UI 用『版本切換』中性詞、技術文件保留 downgrade」，並在 PRD §4 US-FW-2 敘述中將「按下『降版』按鈕」改為「按下『切換到此版本』按鈕」 |
| MJ-D2 | §3.3 第 3 個 user story（「進階使用者切換 FW 版本」）的 PRD 對應 | Design §14.4 第 5 點 + §3.3 accordion 設計都暗示存在「進階使用者主動切版本」的 user story、但 PRD §4 只有 US-FW-1（自動升級）+ US-FW-2（降版 + 多版本切換）+ US-FW-3（KL630/KL730）——PRD 沒有獨立的「進階使用者切換 FW 版本」US。Design 把這個假設藏在「accordion」設計中，但若 PM 沒明示這個 user story、可能造成實作時 Frontend 缺少對應的 AC 驗收標準 | **建議方案**：PM 在下次 PRD 補丁將 US-FW-2 拆分為兩個：(1) **US-FW-2 一般使用者主動切版本**（含降版到舊版 / KDP1 兩個情境）+ (2) **US-FW-2.5 進階使用者跨版本切換**（含「升回上一個版本」「測試環境切版本」等情境）。這樣 Design 的「accordion + 中性文案」策略才有對應的 PRD source-of-truth。**或**：PRD §4 US-FW-2 敘述加一段「本 user story 同時覆蓋進階使用者主動跨版本切換的情境（含升回上版 / 測試環境切版本）、UI 上以中性『版本切換』詞彙呈現、不區分『升 / 降』」 |

### 🔴 Critical（必須改、阻擋 merge）

無。Design Spec 與 PRD 的需求覆蓋度足以推進開發。MJ-D1 + MJ-D2 雖是 Major、但屬 framing 對齊問題、不是設計錯誤、可在下次 PRD 補丁修正後直接 merge Design Spec。

---

## 對 ADR-001 的審閱

### 結論：通過 with 1 個 Minor + 對齊 ADR 編號的 Major（已在 TDD 章節列出 MJ-A1）

| 項 | 評估 |
|----|------|
| Status: Accepted | ✅ 對齊使用者 2026-05-24 拍板紀錄 |
| Context 引用歷史紀錄正確嗎？ | ✅ 4 個痛點背景對齊 PRD §1.1 / progress.md；R5-Q9 砍 flash 歷史決策推測的 4 個原因與 PRD §2.2 一致 |
| Decision / Consequences 跟 PRD 結論一致嗎？ | ✅ 5 項決策（A+B 一次做 / R5-Q9 範圍切割 / KneronPLUS Python C API / 選項 C metadata / 保守 +7MB）全部對齊 PRD §3 / §6 |
| Alternatives Considered 完整嗎？ | ✅ 列了 5 個替代方案、含 DFUT.exe / dev mode only / 多版本目錄選 A B C / 等 A 階段驗證再評估 B——這是好的留痕 |
| Compliance checklist | ✅ 含 firmware redistribution 授權標未完成、與 PRD §9 Q-FW-1 一致 |

### 🟡 Minor

| # | 章節 | 問題 | 建議修法 |
|---|------|------|---------|
| M-ADR1 | Related 表 | 列了「R5-B4」「R5-E」「2026-04-21 commit」「watchServer」「research-kl520-fw-management/」——但沒列「`feature-firmware-management.md`」（PRD）| 加一行「`feature-firmware-management.md` / PRD v2.2 對應 user story 與成功指標」 |

### 🟠 Major（與 TDD 互審共用）

MJ-A1：ADR 編號 ADR-001 vs PRD 引用的 ADR-009 不一致——詳見 Architect TDD 互審 MJ-A1。

---

## 結論

| 文件 | 結論 |
|------|------|
| Architect TDD v2.2 | ✅ 通過 with 6 Minor + 2 Major（MJ-A1 ADR 編號 + MJ-A2 行號 cross-check） |
| Design Spec v2.2 | ✅ 通過 with 5 Minor + 2 Major（MJ-D1 「降版」文案 framing + MJ-D2 user story 拆分） |
| ADR-001 | ✅ 通過 with 1 Minor + 共用 MJ-A1 編號修正 |
| 整體 | **通過 with Major 修正**——三份文件對 PRD 需求覆蓋度高、R5-Q9 翻案的範圍切割三方一致、ADR 留痕完整。需 Architect 統一 ADR 編號、PM 在下次 PRD 補丁對齊 Design 的「中性文案」立場 + 拆分 user story。所有 Major 修完後即可 merge、進 M9-1 開發。 |

---

## 給 Orchestrator 的建議

### 建議派 Architect 修改項

| # | 項目 | 工作量 |
|---|------|-------|
| 1 | **MJ-A1 ADR 編號統一**：與 Architect 確認 ADR 編號規則後、決定 `ADR-001` 還是 `ADR-009`、修改檔名 + 內部引用 + 通知 PM 同步改 PRD §2.5 / §11.4 | 0.1 人天 |
| 2 | **MJ-A2 R5-Q9 行號 cross-check**：TDD §1 補一段釐清 L776 vs L854 | 0.1 人天 |
| 3 | M-A1 ~ M-A6（Minor）| 0.2 人天（或全部 留為 follow-up）|

**建議**：Architect 修 2 個 Major 後即可 merge。Minor 全部留 follow-up、在 M9-1 啟動前的 prep 階段一次處理。

### 建議派 Design 修改項

| # | 項目 | 工作量 |
|---|------|-------|
| 1 | **MJ-D1 對齊 PRD「降版」文案立場**：等 PM 修 PRD §9 Q-FW-3 後、Design 不用改檔（Design 立場已是中性、PRD 對齊到 Design 即可）| 0 人天（Design 端）|
| 2 | **MJ-D2 user story 拆分**：等 PM 修 PRD §4 US-FW-2 後、Design 在 §1 加註對應 PRD 哪個 user story、確保未來查閱可追溯 | 0.1 人天 |
| 3 | M-D1 ~ M-D5（Minor）| 0.2 人天（或全部留為 follow-up）|

**建議**：Design 等 PM 改完 PRD 後再做小幅對齊、目前 Design Spec 不需要主動改。

### 建議派 PM（我自己）修改項

| # | 項目 | 工作量 |
|---|------|-------|
| 1 | **修 PRD §2.5 / §11.4 ADR 編號**：等 Architect 統一後同步改 | 0.1 人天 |
| 2 | **修 PRD §9 Q-FW-3「降版」用詞**：從「待 Design 決定」改為「已決定 UI 用中性『版本切換』、技術文件保留 downgrade」| 0.1 人天 |
| 3 | **修 PRD §4 US-FW-2 拆分（或加註覆蓋進階使用者切版本情境）** | 0.2 人天 |
| 4 | **修 PRD §10.2 i18n keys 數量**：從 46 改為 52 | 0.05 人天 |
| 5 | **修 PRD §4 US-FW-2 AC-FW-2.3「dropdown」→「radio list 或同等」** | 0.05 人天 |
| 6 | **新增 PRD §9 Q-FW-8「DOWNGRADE 字串 i18n 化」** | 0.05 人天 |

**合計**：PM 後續補丁工作量 ~0.55 人天。

### 互審 follow-up 流程建議

1. **本輪先收尾**：Orchestrator 收三份互審報告（PM / Architect / Design）、評估分歧點
2. **Architect 修 ADR 編號 + 行號 cross-check**（2 個 Major）→ 通知 PM
3. **PM 補 PRD 對齊 4 個 Major 對應項**（ADR 編號 / Q-FW-3 / US-FW-2 / i18n keys 數量）→ 通知 Design
4. **Design 在 §1 加註對應 PRD user story 後再 merge**
5. 整體進度推進到 M9-1 啟動

**不阻擋的 follow-up**：所有 Minor（M-A1 ~ M-A6 + M-D1 ~ M-D5 + M-ADR1）可在 M9-1 啟動前 prep 階段一次處理、或直接留到 M9-13 三平台驗收後再回頭補。

---

## 變更紀錄

| 版本 | 日期 | 作者 | 變更 |
|------|------|------|------|
| v1 | 2026-05-24 | PM Agent | 初版互審報告；3 個 Major + 11 個 Minor + 4 個建議；整體通過 with Major 修正 |