jim800121chen 46514d77d7 docs(local-tool): M9 — Kneron Dongle FW 偵測 + 升降版（A+B、翻案 R5-Q9）

L 級新功能、PRD/Design/TDD/ADR 三方協作 + 互審 + M9-6 SDK 雙驗證、總計 ~9000 行文件。

範圍：
- A 階段（MVP、5 人天）：KL520 + KL720 自動升級 KDP1 → KDP2
- B 階段（10.5 人天）：手動降版面向一般使用者 + KL630 / KL730 擴展
- 合計 15.5 人天、安裝包 +7MB（保守 bundle 策略）

關鍵決策：
- 翻案 R5-Q9（progress.md 第二輪使用者決策「韌體燒錄 flash → B 砍掉」）
- 跨平台用 KneronPLUS Python C API、不用 DFUT.exe
- 多版本目錄結構選 C metadata（firmware/<chip>/{version}/ + CURRENT_VERSION）
- Kneron firmware redistribution 授權與 R5-B4 預置模型同性質、發佈前評估

文件產出：
- PRD v2.2（PRD-v2.md 495 行 + features/feature-firmware-management.md 599 行）
- Design v2.2（firmware-management.md 948 行 + control-panel.md §6a graceful shutdown）
- TDD v2.2（v2/firmware-management.md 823 行 + ADR-001 218 行）
- 8 份 research（含 M9-6 弱驗證 + 強驗證、~3200 行）
- 3 份三方互審報告（PM/Design/Architect cross-review）

M9-6 強驗證重大發現（影響 B 階段）：
- KL730 product_id 實際是 0x732（不是 0x0730）
- KL630/KL730 firmware 是 embedded Linux rootfs（不是 .bin、不同代設計）
- KneronPLUS Python 沒 update_kdp_firmware_from_files 公開 API、warrenchen 走 ctypes
- 不影響 A 階段、B 階段 M9-8 需 spike

下一步：派 backend M9-1 起跑（bridge.py handle_firmware_upgrade）

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-25 07:40:56 +08:00

26 KiB

Raw Blame History

Design 互審報告 — PM PRD + Architect TDD + ADR-001（v2.2 Firmware）

審閱者：Design Agent 審閱日期：2026-05-24 審閱對象：

PM：.autoflow/02-prd/features/feature-firmware-management.md（v2.2-draft, 523 行）

Architect TDD：.autoflow/04-architecture/v2/firmware-management.md（v2.2, 604 行）

Architect ADR：.autoflow/04-architecture/adr/ADR-001-firmware-management.md（v1.0, 210 行）對照基準：.autoflow/03-design/v2/firmware-management.md（Design v2.2, 920 行）

TL;DR

整體評估：🟢 三份產出與 Design 整體一致、可進 M9-12 Frontend 實作。共找出 13 個對齊點：

🔴 嚴重（需互審回合解決）：1 個 — Architect TDD 狀態機名稱與 Design 不一致（A-MISMATCH-1）
🟠 中等（需 PM / Architect 補回應）：4 個 — PM 缺 NPS / 任務完成率指標、PRD 沒明示「降版」用詞策略、Architect 沒解 graceful shutdown 拒絕、Architect 缺 token 對比實測
🟡 輕微（建議補但不阻塞）：5 個 — PM 沒列「使用者怎麼知道要降版」user story、PRD 沒提 Bundle 多下載 X 秒、Architect ADR Alternatives 缺一條 Design 視角、PM 對 R-FW-12 不夠具體、PRD §10 KL520 升級時間估算不一致
🟢 對齊良好：3 個 — 6 個互審待確認點中 4 個已解、API/UI DisplayName 對齊、WebSocket progress event schema 足夠

結論：建議先解 🔴 A-MISMATCH-1（狀態機對齊），其他 🟠 在實作前的 polish 階段補。不阻塞 M9-1 ~ M9-5 A 階段啟動（A 階段不涉及降版 UI、6 個對齊點都是 B2 才會踩到）。

一、對 PM PRD 的審閱

1.1 對齊良好（🟢）

🟢 P-OK-1：6 個 Architect 互審待確認點 PM 已涵蓋 3 個

PM PRD §14.2 列了 6 個給 Architect 的互審項（A-FW-1 ~ A-FW-6），其中：

A-FW-2（driver safety guards）→ Architect TDD §6.1 + §5.2 已對應寫具體 dispatch 與 _validate_downgrade_request
A-FW-5（模組路徑 server/internal/firmware/）→ Architect TDD §2.1 已對應
A-FW-6（R-FW-5 與 R5-B4 合併）→ Architect TDD §8.4 已對應

Design 視角確認：PM 給 Architect 的問題、Architect 都回答了。對齊 OK。

🟢 P-OK-2：「降版面向一般使用者」假設（§5）的支持證據完整

PM §5.1 列 4 個假設（H1-H4）+ §5.3 5 種降版情境，Design 視角檢核：

4 個假設都對齊 R5 Persona 定義（P1 FAE / P2 開發者）
5 種情境覆蓋 Design 設計的 UX 流程（Design §6 二次確認 modal、§7 失敗復原都針對這 5 種使用者預期）
UR-1 ~ UR-4 user research 待驗證項合理（Beta 階段 / post-launch 6 個月追蹤）

對齊 OK，Design 對 PM 的假設沒有體驗面異議。

PM AC-FW-2.5 列 4 條警告語：

「降版可能導致現有 model 無法運作」→ Design §6.1 風險列表第 1 點「部分新版 .nef 模型無法載入」
「降版過程不可中斷、否則裝置可能損壞」→ Design §6.1 風險列表第 3 點 + §6.3 進度 banner
「降版完成後可能需要重新插拔裝置」→ Design §6.4 toast「可能需要重新插拔」
「請確認版本相容性、降版至 KDP1 的舊版會限制可用功能」→ Design §6.2 KDP1 額外紅色 banner + 多 1 條風險

4 條警告語 100% 對應。Design 用詞略不同（「.nef 模型」vs 「現有 model」），但語意一致、Design 用詞更精準。

1.2 中等問題（🟠，需 PM 補）

🟠 P-MID-1：成功指標缺「使用者感知體驗指標」

問題：PM §7 列 2 種指標（北極星 5 分鐘首次推論達成率 + 次要指標如升級成功率 ≥ 95% / Brick < 0.1%），全部是技術 / 業務指標、沒有對應使用者體驗的指標。

Design 視角缺漏：

沒有 「降版任務完成率」（使用者點「版本切換」→ 真正完成切換的比例。可能很多人在二次確認 modal 階段就放棄）
沒有 「中途放棄率」（多少使用者打到一半「DOWNGRADE」就取消、暗示 UX 過度恐嚇）
沒有 「FW badge 點擊率」（Devices 頁 ⚙ icon / badge 點擊後是否真的進 Settings 韌體分頁，反映 Design IA 是否讓使用者找得到）
沒有 使用後 NPS / SUS 分數（特別是 B2 階段一般使用者降版流程的可用性）

建議：PM 在 §7.2 加 4-5 個體驗指標。範例：

| 指標 | 目標 |
|------|------|
| 升級任務完成率（modal 開啟 → 完成）| ≥ 85% |
| 二次確認 modal 中途放棄率 | 50-70%（合理區間、太低暗示 UX 不夠恐嚇、太高暗示嚇跑使用者）|
| Devices 頁 FW badge 點擊率 | ≥ 30%（只算紅 / 黃 badge）|
| B 階段 SUS 分數（5 人 usability test）| ≥ 65 |

阻塞性：不阻塞 A 階段、但 B 階段上線前應補（不然沒指標可衡量 UR-1 ~ UR-3）。

🟠 P-MID-2：PRD 沒明示「降版」用詞策略、可能與 UI 矛盾

問題：

PM §14.1 D-FW-2「『降版』這個詞在 UI 上是否使用」標為 Design 待定
PM 自己文件多處用「降版」（§4 US-FW-2 標題就是「一般使用者主動切版本」、但內文反覆用「降版」）
Design 已明確採「韌體 / 版本切換」中性詞、UI 不用「降版」（Design §2.1 + §3 範例 wireframe 全部用「版本切換」）

體驗面風險：如果 PM PRD 的 user story 文字用「降版」、未來測試人員 / 文件譯者可能誤以為 UI 應該叫「降版」、造成 UI 文案改錯方向。

建議：PM 在 §14.1 D-FW-2 加註「Design 採『韌體 / 版本切換』、PRD 後續更新時 user-facing 描述應同步」。或在 §4 user story 標題明示「進階使用者主動切版本（內部 / 技術文件用 downgrade、UI 用『版本切換』）」。

阻塞性：不阻塞 A 階段、但 B 階段 PM 應明示。

🟠 P-MID-3：PRD §10 KL520 升級時間估算不一致

問題：

AC-FW-1.7：「KL520 升級預估 30 秒；KL720 預估 180 秒」
§7.2 次要指標：「FW 升降版平均時長：KL520 ≤ 60s / KL720 ≤ 200s」
AC-FW-1.7 30s vs §7.2 ≤ 60s 不一致

Design 視角影響：Design §5.5 進度 modal 顯示「預估剩餘 X 秒」、這個數字從哪裡來？如果以 AC 30s 為基準、實際拖到 50s 使用者會誤以為「failed」；如果以 60s 為基準、實際 30s 結束又會讓使用者懷疑「真的有寫到 flash 嗎？」

建議：PM 統一兩處數字、Design 建議用 §7.2 的上限（≤ 60s for KL520 / ≤ 200s for KL720）作為「預估剩餘」基準、給 UX 緩衝。

阻塞性：不阻塞 A 階段啟動、但 Frontend 實作 §5.5 進度 modal 前要釐清。

🟠 P-MID-4：PM §14.1 D-FW-4「FW badge 三色閾值」沒明示 PM 期待

問題：PM 列了 D-FW-4「Design 需定具體閾值」、把這個皮球丟回 Design。

Design §4.2 已定 3 色規則（current = 綠、older = 黃、legacy KDP1 = 紅）
但沒有定義「current 之前 1 版 vs 2 版以上算什麼顏色」——bundle 三個版本（v2.2.0 / v2.1.0 / kdp1）時、v2.1.0 是黃還是紅？
也沒定「壞掉的 firmware（loader mode、firmware 字串讀不到）」算什麼顏色

Design 當前邏輯（從 §4.2 推）：

綠 = bundled current 完全相同（如 v2.2.0）
黃 = bundle 內較舊但可升（如 v2.1.0）
紅 = KDP1 系列（不論版本）

→ 缺「壞掉 firmware」狀態的處理。

建議：PM 在 D-FW-4 補一句「Design 已定 3 色規則（綠 / 黃 / 紅）、Architect 需提供 driver 層 FirmwareIsLegacy / FirmwareCanUpgrade 判定邏輯給 Design」、或 Design 直接補一條「壞掉 firmware = 灰色 badge『狀態未知』」。

阻塞性：不阻塞 A 階段（A 只有 KL520/KL720 current + 升級、沒有 older 中間狀態）。

1.3 輕微建議（🟡）

🟡 P-LOW-1：缺「進階使用者怎麼知道要降版」user story

問題：PM §4 列 3 個 US-FW、但缺一個關鍵 user story：「使用者怎麼發現需要降版？」

情境：使用者升版後跑舊 model 出現「Error / 模型載入失敗」、怎麼從錯誤訊息推到「啊我應該降版」？
當前 PRD 沒明示 inference 失敗時是否暗示「可能是 FW 版本問題、考慮降版」

Design 視角：這個 user story 直接影響 Design 是否要在 Workspace inference 失敗的 error modal 加一條 hint「如果問題是 model 不相容、可以到 Settings → 韌體分頁切換版本」。當前 Design §7 失敗復原只處理 FW 操作本身的失敗、不處理「模型推論失敗指向 FW 問題」。

建議：PM 加 US-FW-2.5「使用者從推論錯誤推導到需要降版」、Design 後續補對應 hint UX。或標為「v2.3 未來迭代」。

阻塞性：不阻塞 v2.2、可延後到 v2.3。

🟡 P-LOW-2：Bundle 策略對使用者的等待感 PRD 沒提

問題：PM §6 列 +7MB 安裝包衝擊、但沒列「使用者下載 / 安裝時可能多感覺到的 X 秒等待」。

macOS 寬頻 ~50MB/s → +7MB = +0.14s（無感）
一般使用者 4G hotspot ~5MB/s → +7MB = +1.4s（無感）
慢速 wifi 1MB/s → +7MB = +7s（有感、但仍可接受）

Design 視角：這部分 Design 不需要做事（Bundle 大小是 PM/Architect 範圍）、但 PRD 缺體驗層的描述。

建議：PM §6.3 加一句「使用者層面：寬頻 +0.14s 安裝時間（無感）、慢速網路最多 +7s（仍可接受）」。

阻塞性：不阻塞、純文件 polish。

🟡 P-LOW-3：R-FW-12「使用者看不懂版本」緩解措施不夠具體

問題：PM §8 R-FW-12「多版本管理 UX 複雜度、使用者看不懂 v2.2.0 vs v2.1.0 vs KDP1」、緩解寫「Design Agent 設計清晰版本說明文案」、太抽象。

Design 視角：Design 已具體做了：

§3.3 每個版本有 displayName 後綴（(current) / (older) / (legacy)）
§3.3 每個版本有獨立說明文字（「發布於 2024-08（與舊模型相容）」）
§9 i18n keys 已涵蓋

建議：PM 把緩解寫具體：「Design v2.2 §3.3 + §9 i18n 已對應、含 displayName 後綴 + 版本說明文字 + KDP1 額外警告」。讓 R-FW-12 不再是 open item。

阻塞性：不阻塞、純風險追蹤 polish。

二、對 Architect TDD 的審閱

2.1 對齊良好（🟢）

🟢 A-OK-1：DisplayName 格式對齊

Architect TDD §4.1 FirmwareVersion struct：

DisplayName string `json:"displayName"` // "v2.2.0 (current)" / "v2.1.0 (older)" / "KDP1 (legacy)"

Design §3.1 wireframe 顯示：「KDP2 v2.2.0 (current)」、§9.2 i18n key 對應：

settings.firmware.card.tag.current → (current)
settings.firmware.card.tag.legacy → (legacy)

對齊 100%。但 Design 用「KDP2 v2.2.0 (current)」、Architect 用「v2.2.0 (current)」（沒前綴 KDP2）。

→ 小釐清：Architect 的 FirmwareVersion.Version 是「v2.2.0」、Design 的 displayName 是「KDP2 v2.2.0 (current)」、兩個是「version field + displayName field 合併」嗎？建議 Architect 明示 displayName 包含 KDP 前綴：「displayName = "{kdpFamily} {version} ({status})"」。

🟢 A-OK-2：WebSocket progress event schema 足夠支撐 Design UI

Architect TDD §4.2 FirmwareProgress struct：

Percent: 0-100 → 對應 Design §5.2 進度條
Stage: 字串列舉 → 對應 Design §5.3 階段對應表
Direction: upgrade / downgrade → 對應 Design §6.3 「切換韌體」vs「升級韌體」標題切換
Message / Error: 對應 Design §7.2 友善訊息

Design 缺的：ETA（預估剩餘秒數）。Design §5.2 範例顯示「預估剩餘 X 秒」、但 Architect schema 沒有 EstimatedRemainingSeconds 欄位。

→ 建議：Architect 在 FirmwareProgress 加 optional EstimatedRemainingSeconds int 或 ElapsedMs int，Frontend 用 elapsed 自己算 ETA。

🟢 A-OK-3：多語系策略對齊

Architect TDD §3.3 錯誤碼表（FW_DEVICE_BUSY / FW_VERSION_NOT_FOUND 等 6 個）→ Design §9.8 失敗訊息 8 個對應 friendly message keys。

對齊 OK、但 Architect 6 個錯誤碼 vs Design 8 個失敗類型，數量不對等（見下方 A-MISMATCH-2）。

2.2 嚴重問題（🔴）

🔴 A-MISMATCH-1：狀態機名稱不一致

問題：

來源	狀態 / Stage 名稱
Design §8 狀態機	`idle` / `confirming` / `preparing` / `loading` / `flashing` / `verifying` / `success_toast` / `error_modal`
Architect TDD §4.3 stage 列舉	`connecting` / `loading_loader` / `loading_firmware` / `verifying` / `done` / `error`
Architect TDD §5.1 流程 progressCh stage	`connecting` / `loading_firmware` / `verifying` / `done`
PM PRD AC-FW-1.2	「連線中 / 載入引導程式 / 寫入韌體 / 重新偵測 / 完成」（中文）

衝突點：

Design 用 preparing / loading / flashing 三階段、Architect 用 connecting / loading_loader / loading_firmware 三階段、PM 用「連線中 / 載入引導程式 / 寫入韌體」三階段（中文）
全部都意指同樣的事、但名稱完全沒對齊

Design 視角影響：

Design §9.6 i18n keys 把 stage 用 connect / loader / upgrade / verify 四個 key（在 §5.3 階段對應表）
但 Design §8 狀態機又用 preparing / loading / flashing / verifying
連 Design 自己內部都不一致——Design §5.3 用 connect/loader/upgrade/verify、Design §8 用 preparing/loading/flashing/verifying

Design 自承錯誤：這是 Design 自己沒對齊內部章節 + 沒採 Architect TDD 的命名。

建議：以 Architect TDD §4.3 stage 列舉 為標準（後端是 source of truth），調整：

Design §8 狀態機：preparing → connecting、loading → loading_loader、flashing → loading_firmware
Design §5.3 階段表的 connect / loader / upgrade 對齊 Architect 的 connecting / loading_loader / loading_firmware
PM PRD AC-FW-1.2 不變（中文是 user-facing 文案、英文 stage code 是技術名稱）
Design §9.6 i18n key suffix 從 stage.connect 改為 stage.connecting 等

阻塞性：M9-3 後端 API 完成前必解。如果 Frontend 不知道後端會推什麼 stage 字串、subscribe WebSocket 時對應不上、進度 modal 顯示「unknown stage」。

🔴 A-MISMATCH-2：Architect 6 個錯誤碼 vs Design 8 個失敗類型不對等

問題：

Architect TDD §3.3 錯誤碼	Design §7.1 失敗類型
`FW_DEVICE_BUSY`	—
`FW_VERSION_NOT_FOUND`	—
`FW_INVALID_DIRECTION`	—
`FW_NO_CONFIRM_TOKEN`	—
`FW_UPGRADE_FAILED`	`upgrade` / `connect`
`FW_UPGRADE_BRICK_RISK`	`verify`
—	`scan` 找不到裝置
—	`loader` 寫入失敗
—	Timeout（>60s）
—	Disconnect during op

衝突點：

Architect 6 個是「API 層錯誤碼」（HTTP 4xx/5xx 對應）
Design 8 個是「使用者面失敗情境」（stage 細分）
兩者不在同一層、不衝突、但對應關係沒明示

Design 視角影響：

Design §7.2 失敗 modal 顯示「錯誤代碼：fw_upgrade_stage_loader_E102」、暗示有更細的代碼系統
但 Architect 只給 6 個 API 層代碼、沒給 stage-level 代碼
Frontend 拿到 FW_UPGRADE_FAILED 後不知道對應 Design 8 種失敗類型中哪一種

建議：Architect TDD §3.3 補一段「失敗類型對應 stage」表：

| 觸發 stage | API 錯誤碼 | 給 frontend 的細分 reason 欄位 |
|----------|----------|---------------------------|
| scan 失敗 | FW_UPGRADE_FAILED | reason: "scan_not_found" |
| connect 失敗 | FW_UPGRADE_FAILED | reason: "connect_failed" |
| loader 寫入失敗 | FW_UPGRADE_FAILED | reason: "loader_write_failed" |
| upgrade 中段失敗 | FW_UPGRADE_FAILED | reason: "upgrade_mid_failed" |
| verify 失敗 | FW_UPGRADE_BRICK_RISK | reason: "verify_mismatch" |
| timeout | FW_UPGRADE_FAILED | reason: "timeout" |
| disconnect | FW_UPGRADE_FAILED | reason: "disconnect_during_op" |

或在 FirmwareProgress.Error 字串內帶結構化資訊（Frontend 解析）。

阻塞性：M9-3 後端 API 完成前必解、不然 Frontend 拿不到細分 reason。

2.3 中等問題（🟠）

🟠 A-MID-1：Architect 沒解 graceful shutdown 拒絕

問題：Design §14.4 懸而未決第 6 點明示問：

降版進行中關閉 Wails 控制台 = 結束 server = 中斷降版 = 可能 brick
Frontend / Backend 是否需要偵測「降版進行中」並擋下關閉動作？

Architect TDD 沒對應：

§8.5 「Flash() method 與 restartBridge()」段提到「FW 升降版完成後設 needsReset=true」、但沒提降版進行中如何拒絕 server shutdown
§5.2 流程沒提 graceful shutdown 拒絕邏輯
§6.4 既有 handler 改動清單沒列「shutdown handler 加 FW 進行中檢查」

Design 視角影響：

Design 規格已採「全螢幕 hover 攔截」（§6.3）防止 click 關 modal、但擋不住關 Wails 控制台視窗
如果 Architect 不在 server 層加保護、Design 的 UX 多層 safety net 在這個漏洞前破功

建議：Architect TDD 補一段 §8.6「降版進行中的 graceful shutdown 拒絕」：

server 偵測 FW task 進行中、收到 SIGTERM / Wails 視窗關閉 → 延遲 shutdown、等 FW task 完成或 60s timeout
同時推 WebSocket event 通知 frontend「使用者嘗試關閉、已擋下」
Frontend 在 Wails 控制台顯示「降版中、無法關閉」提示（Design §13.3 應補對應 UX）

阻塞性：B2 階段（M9-11/M9-12）前必解。A 階段升級不涉及（升級失敗風險小、可中斷）、但降版必須有此保護。

🟠 A-MID-2：Architect token 對比比率沒對應 Design §11.2 推導表

問題：Design §11.2 列了 6 個新 component token 與 Light/Dark 對比比率（4.7:1 / 5.2:1 / 4.8:1）。Design §11.2 末尾標「Architect 互審重點：請確認 Dark 模式下 legacy.fg 用黑色對紅底對比是否真的足夠」。

Architect TDD 沒回應：

TDD §11 測試策略沒提 token 對比驗證
TDD §13.2 Design 互審注意沒提此項
ADR-001 也沒提

Design 視角影響：

Design 的對比比率是「推算值」、需 Architect / Frontend 用 axe / Chrome DevTools contrast checker 工具實測
如果實測 Dark mode 紅底黑字 < 4.5:1、Design 必須調整 token（可能改 fg 為白色、但白配紅可能更糟）
不解 = 違反 Design A 層 De-A2 verification（WCAG AA 對比度達標）

建議：Architect TDD §11.1 加單元測試項：

| firmware/tokens.test | 6 個 fw-badge token 對比 ≥ 4.5:1（light + dark）| axe-core 程式化驗證 |

或 Architect 不主動驗、由 Design 在 M9-4 / M9-12 Frontend 實作時 Design QA 階段實測。

阻塞性：M9-12 Frontend 實作前必解。不解的話 Design verification 過不了。

🟠 A-MID-3：Architect 失敗復原 §5.3 表只列 4 種、Design §7.1 列 8 種

問題：

Architect TDD §5.3 失敗復原表：4 種（device disconnect / firmware load pre-flash / firmware load mid / verify 失敗）
Design §7.1 失敗類型對應：8 種（scan / connect / loader / upgrade / verify / Timeout / Disconnect / 部分成功）

衝突：Architect 表少了 scan 失敗、connect 失敗、loader 寫入失敗、timeout 4 種。

Design 視角影響：

Design 已寫對應 friendly message + 復原行動的 i18n（§9.8）
但如果 Architect 後端沒分這 4 種、Frontend 拿到的都是 generic「FW_UPGRADE_FAILED」、Design 顯示不出 8 種不同 modal

建議：與 A-MISMATCH-2 一起處理。Architect TDD §5.3 對齊 Design §7.1 8 種、或在 reason 欄位細分（見 A-MISMATCH-2 建議）。

阻塞性：M9-3 後端 API 完成前必解。

2.4 輕微建議（🟡）

🟡 A-LOW-1：Architect TDD §10 風險 R-FW-12 對齊不完整

問題：Architect TDD §10 列 R-FW-12「多版本管理 UX 複雜度」、緩解寫「預設只顯示『升級到最新』+『切換 FW 版本』、降版必須展開 + 詳細說明」。

Design 視角：

Design 已具體做（§3.3 accordion 收合、radio list 含說明）
Architect 寫「預設只顯示...」與 Design 不完全一致（Design 是「永遠顯示升級按鈕」、不是「預設只顯示」）

建議：Architect 引用 Design 對應章節：「緩解措施由 Design v2.2 §3.3 落地（accordion + radio list + 版本說明）」。

阻塞性：不阻塞、純文件對齊。

三、對 ADR-001 的審閱

3.1 對齊良好（🟢）

🟢 ADR-OK-1：Decision / Consequences 與 Design 整體理念一致

ADR Decision 5 條：

A + B 一次做完 → Design 規格已涵蓋 A + B
翻案 R5-Q9 範圍切割 → Design §1.2 範圍邊界對齊
KneronPLUS Python C API → Design 不需要知道（後端細節）
多版本目錄結構選項 C → Design §4.2 對齊（顯示版本不涉及目錄結構、但 Design 假設 bundled 版本有 metadata）
保守 +7MB Bundle → Design 不影響

對齊 OK。

🟢 ADR-OK-2：Consequences 負面影響第 3 條對齊 Design 多層 safety net

ADR Consequences 列「法律 / 簽章授權待釐清」、Design 不涉及。列「Brick 風險未完全消除」、Design 已透過 §6 + §7 + §12 三層應對：

§6.1 二次確認 modal + DOWNGRADE 字串
§6.3 全螢幕 hover 攔截 + 不可關 modal
§7 失敗復原 8 種 friendly message
§12 R-FW Design 對策（明示對應 brick 風險路徑）

對齊 OK。

3.2 輕微建議（🟡）

🟡 ADR-LOW-1：Alternatives Considered 缺一條 Design 視角

問題：ADR 列 5 個 Alternatives，但沒有「替代方案：先做 dev mode 降版、不面向一般使用者」（其實 §3 「只做內部 dev mode 降版」算半個、但 ADR 是從工時 / 痛點視角討論、沒從 UX 風險視角討論）。

Design 視角應補：「替代方案 6：只做 dev mode（藏在 Settings → 進階 → 開發者選項）」的 UX trade-off：

優點：誤觸風險降到 0
缺點：使用者明確要求面向一般使用者（H3 假設「藏在 dev mode 反而會讓真正需要降版的人找不到」）
否決原因：使用者 2026-05-24 拍板「面向一般使用者」+ Design 多層 safety net 評估足以擋誤觸

建議：Architect 在 ADR Alternatives §6 補上面這條 UX 視角的替代方案分析。

阻塞性：不阻塞、純 ADR 完整度。

四、總結與給 Orchestrator 的建議

4.1 對齊狀態總覽

類別	數量	狀態
🟢 對齊良好	6	不需處理
🟡 輕微建議	5	建議補、但不阻塞任何 milestone
🟠 中等問題	4	B 階段（M9-11 ~ M9-12）前必解
🔴 嚴重問題	2	M9-3 後端 API 完成前必解

4.2 必解項目（按優先級）

優先級 P0（M9-3 後端 API 完成前必解）

A-MISMATCH-1：狀態機名稱不一致
- 行動：以 Architect TDD §4.3 為準、Design 同步調整 §8 + §5.3 + §9.6 i18n key
- 工時：Design < 0.5h
- 誰來改：Design Agent（Design 內部對齊）+ Architect 確認最終名稱
A-MISMATCH-2：錯誤碼 vs 失敗類型不對等
- 行動：Architect TDD §3.3 補「失敗類型對應 stage」表 + FirmwareProgress.Reason 欄位
- 工時：Architect < 0.5h
- 誰來改：Architect Agent

優先級 P1（B2 階段 M9-11/12 前必解）

A-MID-1：graceful shutdown 拒絕邏輯
- 行動：Architect TDD 補 §8.6 + Design 補 Wails 控制台「降版中無法關閉」UX
- 工時：Architect 1h + Design 1h
- 誰來改：Architect Agent（主）+ Design Agent（控制台 UX）
A-MID-2：token 對比實測
- 行動：M9-12 Frontend 實作時 Design QA 階段實測、不過則調整 token
- 工時：< 0.5h（用 axe 工具）
- 誰來改：Frontend / Design（M9-12）
A-MID-3：失敗復原表 4 vs 8 對齊
- 行動：與 A-MISMATCH-2 一起處理
- 誰來改：Architect Agent
P-MID-1：成功指標補體驗指標
- 行動：PM 在 §7.2 補 4-5 個體驗指標
- 工時：PM 0.5h
- 誰來改：PM Agent（B 階段上線前）

優先級 P2（可延後 / polish）

P-MID-2（降版用詞）/ P-MID-3（升級時間估算）/ P-MID-4（badge 閾值）：PM 補
P-LOW-1 ~ P-LOW-3：PM polish
A-LOW-1：Architect TDD R-FW-12 緩解對齊
ADR-LOW-1：ADR Alternatives 補 Design 視角

4.3 不阻塞 M9-1 ~ M9-5 A 階段啟動

A 階段（升級 only）不涉及 B2 降版、狀態機名稱對齊（A-MISMATCH-1）解決後即可進
A 階段不涉及 graceful shutdown 拒絕、failed type 8 分類也只在 B 階段需要（M9-11/12）
建議 Orchestrator 派 Architect 解 A-MISMATCH-1 + A-MISMATCH-2 之後、即可啟動 M9-1 backend

4.4 Design 本輪不改

依任務 prompt「不改 design、本輪只審」，Design 不主動更新 firmware-management.md。待 Orchestrator 整合三方互審報告後、若決議 Design 需配合調整（如 A-MISMATCH-1 把狀態機名稱換成 connecting/loading_loader/loading_firmware/verifying），Orchestrator 另派 Design Agent 改檔。

4.5 Design 自承的內部矛盾

Design §5.3 階段對應表 vs §8 狀態機名稱不一致（Design 自己問題、不是 PM/Architect 引起）
處理 A-MISMATCH-1 時一併修

變更紀錄

日期	版本	變更	作者
2026-05-24	v1.0	Design 互審 PM PRD + Architect TDD + ADR-001 完成、找出 13 個對齊點（2 P0 / 4 P1 / 7 P2）	Design Agent

26 KiB Raw Blame History Unescape Escape

Design 互審報告 — PM PRD + Architect TDD + ADR-001（v2.2 Firmware）

TL;DR

一、對 PM PRD 的審閱

1.1 對齊良好（🟢）

🟢 P-OK-1：6 個 Architect 互審待確認點 PM 已涵蓋 3 個

🟢 P-OK-2：「降版面向一般使用者」假設（§5）的支持證據完整

🟢 P-OK-3：AC-FW-2.5 二次確認 modal 警告語 4 條與 Design §6.1 對齊

1.2 中等問題（🟠，需 PM 補）

🟠 P-MID-1：成功指標缺「使用者感知體驗指標」

🟠 P-MID-2：PRD 沒明示「降版」用詞策略、可能與 UI 矛盾

🟠 P-MID-3：PRD §10 KL520 升級時間估算不一致

🟠 P-MID-4：PM §14.1 D-FW-4「FW badge 三色閾值」沒明示 PM 期待

1.3 輕微建議（🟡）

🟡 P-LOW-1：缺「進階使用者怎麼知道要降版」user story

🟡 P-LOW-2：Bundle 策略對使用者的等待感 PRD 沒提

🟡 P-LOW-3：R-FW-12「使用者看不懂版本」緩解措施不夠具體

二、對 Architect TDD 的審閱

2.1 對齊良好（🟢）

🟢 A-OK-1：DisplayName 格式對齊

🟢 A-OK-2：WebSocket progress event schema 足夠支撐 Design UI

🟢 A-OK-3：多語系策略對齊

2.2 嚴重問題（🔴）

🔴 A-MISMATCH-1：狀態機名稱不一致

🔴 A-MISMATCH-2：Architect 6 個錯誤碼 vs Design 8 個失敗類型不對等

2.3 中等問題（🟠）

🟠 A-MID-1：Architect 沒解 graceful shutdown 拒絕

🟠 A-MID-2：Architect token 對比比率沒對應 Design §11.2 推導表

🟠 A-MID-3：Architect 失敗復原 §5.3 表只列 4 種、Design §7.1 列 8 種

2.4 輕微建議（🟡）

🟡 A-LOW-1：Architect TDD §10 風險 R-FW-12 對齊不完整

三、對 ADR-001 的審閱

3.1 對齊良好（🟢）

🟢 ADR-OK-1：Decision / Consequences 與 Design 整體理念一致

🟢 ADR-OK-2：Consequences 負面影響第 3 條對齊 Design 多層 safety net

3.2 輕微建議（🟡）

🟡 ADR-LOW-1：Alternatives Considered 缺一條 Design 視角

四、總結與給 Orchestrator 的建議

4.1 對齊狀態總覽

4.2 必解項目（按優先級）

優先級 P0（M9-3 後端 API 完成前必解）

優先級 P1（B2 階段 M9-11/12 前必解）

優先級 P2（可延後 / polish）

4.3 不阻塞 M9-1 ~ M9-5 A 階段啟動

4.4 Design 本輪不改

4.5 Design 自承的內部矛盾

變更紀錄

26 KiB

Raw Blame History