visionA/local-tool/.autoflow/02-prd/reviews/pm-review-of-tdd-and-design-v2.2-firmware.md

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 修正