jim800121chen 8cd5751ce3 feat(local-tool): M8 重構 — Wails 控制台 + 瀏覽器 Web UI（R5 決策）

依 R5 五輪決策把 visionA-local 從「Wails 內嵌 Next.js」重構為「Wails
本機伺服器控制台 + 瀏覽器 Web UI」模式（類比 Docker Desktop / Ollama）。

程式碼變動
  - M8-1 砍 yt-dlp 全套（後端 resolver / URL handler / 前端 URL tab /
    Makefile vendor / installer / bootstrap / CI workflow，-555 行）
  - M8-2 砍 Mock 模式全套（driver/mock、mock_camera、Settings runtimeMode、
    VISIONA_MOCK 環境變數，-528 行）
  - M8-3 ffmpeg 從 GPL 切換到 LGPL 混合方案：Windows/Linux 用 BtbN 現成
    LGPL binary，macOS 自 build minimal decoder-only 進 git
    （vendor/ffmpeg/macos/ffmpeg 5.7MB + ffprobe 5.6MB，比 GPL 版省 85% 空間）
  - M8-4 Wails Server Controller：state machine、log ring buffer 2000 行、
    preferences.json atomic write、boot-id、Gin SkipPaths、shutdown 7+1 秒、
    notify_*.go 三平台 OS 通知、watchServer 改 Error state 不 os.Exit
  - M8-4b 啟動階段管線 R5-E：6 階段進度 event、20s soft / 60s hard timeout、
    stage 5/6 skip 規則、sentinel file、RestartStartupSequence 5 步驟
  - M8-5 Wails 控制台 vanilla HTML/JS/CSS（9 檔 ~2012 行）取代 M7-B splash：
    state 視覺、log panel、startup progress panel、Stage 6 manual CTA
    pulse、shutdown modal、Settings、Dark Mode、i18n 中英雙語
  - M8-6 上傳影片副檔名擴充（mp4/avi/mov/mpeg/mpg）
  - M8-7 Web UI Server Offline Overlay（role=alertdialog + focus trap +
    wsEverConnected 容錯 + Page Visibility）
  - M8-8 CORS middleware（127.0.0.1/localhost only + suffix attack 防護）+
    ws/origin.go 獨立 WebSocket CheckOrigin 避 package cycle
  - MAJ-4 server:shutdown-imminent WebSocket broadcast 機制
    （/ws/system endpoint + notifyShutdownImminent helper）
  - M8-9 Boot-ID + 瀏覽器 tab 自動重連（sessionStorage loop guard）

品質
  - ~105+ 新 unit test + race detector (-count=2) 全綠
  - 10 個 milestone 全部通過 Reviewer 審查
  - 三方 v2 + v2.1 文件（PRD / Design Spec / TDD）+ 交叉互審紀錄
    收錄在 .autoflow/

交付前待處理（M8-10）
  - 重跑 make payload-macos 把舊 GPL 77MB binary 換成新 LGPL
  - 三平台 end-to-end build 驗證

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

2026-04-15 17:57:54 +08:00

30 KiB

Raw Blame History

Design 交叉審閱 PRD v2（2026-04-14）

審閱者：Design Agent 審閱對象：/Users/jimchen/visionA/local-tool/.autoflow/02-prd/PRD-v2.md（484 行）對照基準：Design Spec v2（03-design/design-spec-v2.md + 03-design/v2/*.md，共 1452 行子檔）+ R5 決策表 + R5-D 補充決策本審閱使用繁體中文台灣用語

摘要（3 行）

總結論：需小改（整體體驗面完整度 85%，4 個 Major + 4 個 Minor）
發現問題數：Major 4、Minor 4
是否阻擋進開發：⚠️ 部分阻擋。R5-D1/D2/D3 三題是使用者已做的決策，PRD v2 沒完整吸收 → PRD 必須先修正 Major 1–3 才能進 M 級開發；其餘問題可在補充 FAQ / UX writing 階段處理

A. 使用者體驗完整性檢查

檢查項	檢查結果
US-1 首次啟動：有無明確寫「每次啟動都會自動開瀏覽器」（R5-D3）？Linux 預設 OFF 的差異處理有沒有寫？	❌ Major 1。PRD v2 §0 摘要、§4 N2、§5 US-1 全部沿用「首次啟動自動開瀏覽器」字面。R5-D3 已明確「每次啟動都自動開」，PRD 必須把「首次」改為「啟動時自動開瀏覽器（每次啟動都生效）」。§6.3 / §4 也完全沒提 Linux 預設 OFF 的差異（R5-D2）
US-2 日常啟動：同上	⚠️ Minor 1。US-2 AC-2.1 寫「≤ 5 秒」但沒明確寫「日常啟動時瀏覽器 auto-open 預設仍會發生」。AC-2.3 有提「若使用者關過 auto-open 則只開 Wails」，這一條是正確的，但和 §0 的「首次啟動自動開」字面有矛盾
US-5 關閉 app：有無明確寫「關閉 Wails 視窗會觸發 Offline Overlay」？文案是否清楚？	✅ 通過。US-7 AC-7.5 + AC-7.6 有寫
US-6 上傳影片：副檔名是否正確寫 mp4/avi/mov/mpeg/mpg？	✅ 通過。AC-6.2 正確
US-7 server 離線情境（新）：Offline Overlay 是否正確描述？有沒有漏寫 Design Spec v2 的硬阻斷特性？	⚠️ Minor 2。§4 N3 寫「半透明覆蓋層」和「覆蓋層下方的 UI 凍結不可操作」。「半透明」這個措辭會誤導 Architect/Frontend — Design Spec v2 server-offline-overlay.md §ARIA 明確規定「卡片背景必須是純色（不是半透明），才能達到 4.5:1 對比」。PRD 的「半透明」只指 backdrop，不指訊息卡片本體。建議改為「全螢幕半透明 backdrop + 置中純色卡片」。不可關閉特性也沒在 PRD 任何一條驗收標準出現（硬阻斷 + focus trap + `role="alertdialog"` 全部缺失）
§4 新功能「每次啟動自動開瀏覽器」（R5-D3）	❌ Major 1（同上）
§4 新功能「Linux 預設 OFF 切換」（R5-D2）	❌ Major 2。完全缺失。§4 N2、§6.3、§6.4、§8 任何一節都沒提這個跨平台差異。這會導致 Architect 不知道要在 config loader 做平台判斷
§4 新功能「Server 崩潰時除控制台 banner 外仍發 OS 通知」（R5-D1）	❌ Major 3。PRD v2 AC-3.7 只說「插 USB 時不發原生 OS 通知」，但 R5-D1 是另一個情境（server 崩潰）— 使用者明確決定「保留 OS 通知」。PRD v2 §4 / §5 US-7 完全沒寫，Architect 如果只看 PRD 會以為「crash 時不用發通知」
§6 瀏覽器相容性（Safari 攝影機警告、Edge/Chrome 推薦）是否明確？	✅ 通過。§6.3 寫法清楚，且 §US-5 AC-5.6 解釋了為什麼不走 `getUserMedia`（所以 Safari 沒有攝影機權限問題）
§6 i18n 中英雙語是否沒被砍？	✅ 通過。§4.1 明確保留
§6 Dark Mode 跟隨系統是否保留？	✅ 通過。§4.1 明確保留

A 區結論：PRD v2 吸收 R5 主決策沒問題，但 R5-D 補充決策三題全部沒吸收（這是使用者後來加的三個決定）。這三題是 PRD v2 Major 等級的缺漏。

B. Design Spec v2 子檔對應檢查

Design Spec v2 子檔	PRD v2 對應章節	檢查結果
`v2/control-panel.md`	§4 新功能 N1 Wails 控制台 + US-1 AC-1.3 / US-7 AC-7.3	✅ 覆蓋。但 PRD 沒有明確提到 Footer 的「持久警示文字」設計（Design Spec v2 §4.6 control-panel.md 行 178）。PRD 的 AC-7.6 只提 tooltip + confirm dialog，遺漏 Footer 持久警示。見 Minor 3
`v2/server-offline-overlay.md`	§5 US-7 + §4 N3	⚠️ 覆蓋不完整。見 Minor 2（硬阻斷 / 不可關閉 / focus trap 沒寫進 AC）
`v2/source-selector-update.md`	§5 US-6 + §4 砍除 #1/#3/#4 + §4 保留「批次影像上傳」	✅ 覆蓋
`v2/first-run-update.md`	§5 US-1 + §4 砍除 #8 First-Run 模式選擇步驟	⚠️ 遺漏。PRD 沒提「First-Run wizard 從 3 步縮為 2 步」（Design Spec v2 first-run-update.md 說明「砍模式選擇，只剩歡迎 / 偵測」）。開發階段 Frontend Agent 可能不知道要砍那一步。見 Minor 4
`v2/settings-update.md`	§4 保留 Settings + §4 N2「自動開瀏覽器」toggle	⚠️ 位置矛盾。Design Spec v2 settings-update.md §1.1 表格把 auto-open toggle 放在「Web UI 裡的 Settings 一般 tab」（sidebar navigation 到 Settings 頁），但 PRD v2 §4 N2 和 §4.4 功能對照表把 Settings「自動開瀏覽器」放在 Wails 控制台。兩個文件對這個 toggle 住哪裡意見分歧。見 Major 4

B 區結論：5 個子檔大致都有被 PRD 提到，但 Settings auto-open toggle 住哪裡 這個定位問題是 Design Spec v2 和 PRD v2 之間的實質分歧，這是 Major 等級的不一致。

C. 體驗紅線 / 缺漏

C.1 北極星指標的時間預算

PRD v2 §1.4 新北極星「≤ 5 分鐘從雙擊到瀏覽器第一幀推論」是正確更新，符合 Design Spec v2 的無摩擦設計（每次自動開瀏覽器）。✅

C.2 砍 Mock 後的 P3 fallback 體驗

Design Spec v2 v2/first-run-update.md 行 319–320 + §Error state 有「偵測不到硬體 → 可略過進 Dashboard 空白狀態 + 引導文字」的設計。PRD v2 AC-1.4 確實有寫「沒插硬體顯示空白 + 提示文字」，✅ 通過。但是 PRD 沒寫「使用者能不能按 Skip / 繼續」 — 意味 First-Run wizard 的 Step 2 「硬體偵測」是不是強制卡關？建議在 AC-1.4 補一句：「First-Run Step 2 在無硬體情況下可按 稍後再設定 略過，進 Dashboard 空白狀態。」見 Minor 3

C.3 Server Crash 的錯誤處理體驗

Design Spec v2 v2/control-panel.md §5「Server Error 面板」有完整設計：Error banner + 三個動作按鈕（Restart Server / View log / Report）。PRD v2 US-7 AC-7.3 只說「顯示 Error 狀態 + log panel 顯示錯誤」，完全沒提 Restart Server / View log / Report 三個動作按鈕。Architect 可能不知道要實作這三個動作。見 Minor 4（同時也是上面 Major 3 的配套）

C.4 關閉 Wails 視窗的 race condition

Design Spec v2 v2/control-panel.md 行 178「Footer 右側持久提示：⚠ Closing this window will stop the server. 12px muted」是一個重要的無需彈窗的被動警示設計。PRD v2 AC-7.6 只寫 tooltip / confirm dialog，沒提 Footer 持久提示。兩者設計理念不一樣：PRD 是「按下 Close 才顯示」，Design Spec v2 是「始終可見」。前者體驗差，因為使用者按 Close 後可能直接盲目點「確定」（Design Spec v2 行 182 已警告過這件事）。見 Minor 3（必須把 Footer 持久提示寫進 AC-7.6）

C.5 Offline Overlay 的硬阻斷特性

如上面 Minor 2 所述，PRD v2 §4 N3 沒告訴 Architect：

Overlay 是 role="alertdialog" + aria-modal="true" + focus trap
不可被使用者手動關閉（只能靠重試成功 / reload）
卡片背景必須純色（不是 backdrop 的半透明）

這三條是 WCAG A11y 關鍵設計決策，PRD v2 必須在 §4 N3 或 AC-7.1/7.2 補齊。

D. 對 PM 懸念 §11-5 的回答（常駐徽章）

PM 問題：Web UI 要不要加一個「Server 是從 visionA-local 跑的」常駐徽章？

Design Agent 決定：❌ 不加（支持 PM 的傾向）

理由（FAANG Senior Product Designer 視角）：

視覺雜訊成本 vs 防誤解收益不對等。常駐徽章會佔用每一個瀏覽器畫面的固定像素（通常 32–40 px），但它防止的「誤以為是網頁服務」情境只在「使用者截圖給外部」的極小機率事件發生。以 FAE Arthur 為主要使用者，他自己知道這是 local app，截圖給客戶時「自己加註解」比「產品永遠帶徽章」的 ROI 好太多。
資訊已由其他管道傳遞。瀏覽器網址列就是 http://127.0.0.1:3721，這是最權威的「這是本機服務」證據，而且是瀏覽器原生 UI，設計成本 0。再加徽章是重複告知。
和設計語言衝突。Web UI 的設計語言（shadcn + Tailwind + 淡色背景）追求資訊層級乾淨，常駐徽章會像浮水印一樣破壞這個語言。Ollama Web UI / LM Studio / SD WebUI 都沒有這種徽章，這是業界慣例。
替代方案：如果 PM 仍擔心「使用者不知道這是本機服務」，Design Spec v2 v2/first-run-update.md 的 Step 1（歡迎頁）可以加一句「你正在使用 visionA-local 的本機 Web 控制台」一次性文案，既不佔用永久視覺空間，又能在關鍵時刻傳達訊息。

建議 PM 在 PRD v2 §11-5 寫：「不加常駐徽章（Design 決定）。改由 First-Run Step 1 的歡迎文字一次性告知。」

E. 對 Architect Q6 的回答（Overlay 關閉 tab 按鈕）

Architect 問題：window.close() 在瀏覽器主動開的 tab 不能用（UX 取捨）

Design Agent 決定：✅ Offline Overlay 不設「關閉 tab」按鈕

理由：

技術限制已確認。瀏覽器安全規範：window.close() 只能關閉由 window.open() 開的 tab。visionA-local 的 tab 是使用者手動開的（xdg-open / open / start 透過 OS 層開瀏覽器 → 瀏覽器建立新 tab），不是 JS 開的 → window.close() 一律失效（Chrome/Edge/Safari/Firefox 全部一致）。
Design Spec v2 v2/server-offline-overlay.md 已經沒有這個按鈕（見行 38–41 原型、行 80–81 元件表）。目前只有兩個按鈕：
- 重試連線（Primary, lg）
- 了解更多 ↓（Ghost, sm，展開 help text）
使用者的兩條恢復路徑都不需要「關閉 tab」按鈕：
- 路徑 A（雙擊重開 app）：Design Spec v2 行 142 已設計「Overlay 顯示期間 polling /api/health 每 3 秒」，使用者只要重開 app → 自動恢復 → Overlay 自動消失，不需手動關 tab。
- 路徑 B（不想用了）：使用者直接按瀏覽器的 ⌘W / Ctrl+W / 點 tab 的 ✕，是瀏覽器原生操作，完全不需要 JS 協助。
「了解更多」展開 help text 已足夠。如果使用者真的困惑「為什麼按鈕關不了 tab」，help text 裡補一句「要結束使用 visionA-local，請直接關閉瀏覽器分頁 (⌘W / Ctrl+W)」就好。

建議 Architect 在 TDD v2 Q6 寫：「Offline Overlay 不提供關閉 tab 按鈕（Design 決定）。恢復路徑 A（重開 app → auto recovery）與路徑 B（使用者自行 ⌘W）已足夠，不需 JS 介入。」

額外建議：Design Spec v2 v2/server-offline-overlay.md 行 154–157 的「了解更多」英文 / 中文 copy 應補一句「要離開本頁，請直接關閉瀏覽器分頁」。這是 Design 自己要補的 UX writing 後續項。

F. 臆測 / 誤解 / 超範圍清單

#	類別	位置	內容	處理建議
F1	誤解 R5-D3	§0 摘要點 5、§4 N2、§5 US-1 敘述 / AC-1.3、§10 變更追蹤	沿用「首次啟動自動開瀏覽器」字面，沒反映使用者 R5-D3「每次啟動都自動開」的決定	全文 replace：「首次啟動自動開瀏覽器」→「啟動時自動開瀏覽器（每次啟動）」
F2	遺漏 R5-D2	§4 N2、§6.3 瀏覽器相容性	沒寫 Linux 預設 OFF、macOS/Windows 預設 ON 的差異	§4 N2 補一句：「平台預設：macOS / Windows ON；Linux OFF（因 `xdg-open` 在極簡 WM 下行為不穩定，R5-D2）」
F3	遺漏 R5-D1	§5 US-7 AC-7.3、§4 新增功能	Server crash 時使用者決定「保留 OS 通知」，PRD 沒寫	§5 US-7 補 AC-7.7：「Server 崩潰時，除控制台 Error banner 外，同步發一次 OS 原生通知（macOS Notification Center / Windows Toast / Linux `libnotify`，R5-D1）」
F4	和 Design Spec v2 分歧	§4 N2 / §4.4 對照表	PRD 把 auto-open toggle 放在 Wails 控制台，Design Spec v2 放在 Web UI Settings > 一般 tab	見 Major 4 的仲裁方案
F5	沒臆測新增功能	—	PRD v2 沒有超出 R5 範圍的功能（已確認）	✅ 通過
F6	Offline Overlay 描述失真	§4 N3	寫「半透明覆蓋層」可能誤導為整個 overlay 都半透明	補強為「半透明 backdrop（`rgba(0,0,0,0.4-0.5)`）+ 置中純色卡片（光模式 `color.surface`）」

G. 問題清單

Major（阻擋開發，必須改）

Major 1：PRD v2 沒吸收 R5-D3「每次啟動都自動開瀏覽器」

位置：§0 §4 N2 §5 US-1 §10
影響：若不改，Architect 會把「只在 firstRunCompleted === false 時 auto-open」寫進 TDD，導致第二次啟動不自動開瀏覽器，違反使用者決定
修正：PRD 全文去掉「首次」二字，改為「啟動時自動開瀏覽器（預設每次啟動生效）」

Major 2：PRD v2 沒寫 R5-D2 Linux 平台預設差異

位置：§4 N2 / §6.3 / §6.5
影響：若不改，Architect 會寫「三平台統一預設 ON」，Linux 使用者第一次啟動會看到瀏覽器沒開、不知道發生什麼
修正：§4 N2 補平台預設表；§6.3 瀏覽器相容性加一行「Linux：auto-open toggle 預設 OFF，見 §4 N2」

Major 3：PRD v2 沒寫 R5-D1 Server 崩潰仍發 OS 通知

位置：§5 US-7
影響：Architect 會以為「crash 時只顯示控制台 banner」，違反使用者決定
修正：US-7 新增 AC-7.7 / AC-7.8：「崩潰事件同步發一次 OS 原生通知；只在前景切換回控制台時不重複發（去重策略由 Architect 在 TDD v2 決定）」

Major 4：Settings auto-open toggle 住哪裡 — PRD 和 Design Spec v2 分歧

位置：PRD v2 §4 N2 / §4.4 vs Design Spec v2 v2/settings-update.md §1.1
背景：PRD 說住 Wails 控制台；Design Spec v2 說住 Web UI Settings > 一般 tab
Design Agent 仲裁：應該放 Wails 控制台（PRD 是對的）。理由：
1. auto-open 是 Wails 啟動時的行為，讀取 config 的時機點在 Wails main.go 啟動階段，那時 Web UI 還沒 load；config 必須被 Wails 進程讀到
2. 使用者心智模型：「我要改 Wails 的行為 → 去 Wails 控制台改」比「我要改 Wails 的行為 → 去瀏覽器改」更直覺
3. Design Spec v2 v2/settings-update.md 本節需要修正。這是 Design Agent 自己的文件錯位，我會在下一輪更新
修正：PRD v2 §4 N2 不用改（原本就對）；Design Spec v2 v2/settings-update.md 下一輪迭代時改為「auto-open toggle 住 Wails 控制台的 Settings menu，不住 Web UI」

Minor（可在後續補，不阻擋開發）

Minor 1：US-2 AC 沒寫清楚日常啟動時 auto-open 預設仍會發生

位置：§5 US-2 AC-2.1
修正：在 AC-2.1 補一句「日常啟動時，若 Wails 控制台 Settings autoOpenBrowser === true，仍會自動開瀏覽器」

Minor 2：Offline Overlay 的 A11y 硬阻斷特性沒寫進 PRD

位置：§4 N3 / §5 US-7 AC-7.1
修正：§4 N3 補「Overlay role="alertdialog" + aria-modal="true" + focus trap + 不可手動關閉（只能 retry 成功 / 重 load）」；AC-7.1 補「Overlay 無 ✕ 按鈕」

Minor 3：US-7 沒寫 Wails 控制台 Footer 持久警示 + Error state 三個動作按鈕

位置：§5 US-7 AC-7.3 / AC-7.6
修正：
- AC-7.3 補：「Error state 面板含 Restart Server / View log / Report issue 三個動作按鈕（見 Design Spec v2 v2/control-panel.md §5）」
- AC-7.6 把「tooltip / confirm dialog」升級為「Footer 持久警示 + tooltip / confirm dialog 雙保險」

Minor 4：US-1 沒寫 First-Run wizard 從 3 步縮為 2 步

位置：§5 US-1 敘述 / AC-1.4
修正：AC-1.4 補「First-Run wizard 只剩 Step 1 歡迎 + Step 2 硬體偵測，砍 Mock 模式選擇步驟（R5-5a）；Step 2 在無硬體時可按 稍後再設定 略過進 Dashboard 空白狀態」

H. 通過 / 不通過結論

不通過（需要先處理 Major 1–3 才能進下一步）。

Major 1/2/3 是使用者已做的決定被 PRD 漏寫，必須由 PM Agent 修訂 PRD v2 一次小版本（v2.1），補齊三個 R5-D 決策。Major 4 Design 自己承諾下一輪修正 Design Spec v2（把 auto-open toggle 從 Web UI Settings 移到 Wails 控制台 Settings menu），PRD v2 本身不用改。

Minor 1–4 可由 PM 在同一次 v2.1 修訂時順便補齊，或記入「未解決問題」清單在開發前補齊，不阻擋 M 級架構動工，但必須在 Architect 寫 TDD v2 之前補上，否則會再次發生文件間矛盾。

建議流程：

PM Agent 收到本 review → 產出 PRD v2.1，修正 Major 1–3 + Minor 1–4（預估 20 分鐘）
Design Agent 同時修正 Design Spec v2 v2/settings-update.md（Major 4，auto-open 位置更正）
Architect 拿 PRD v2.1 + 更新後的 Design Spec v2 寫 TDD v2
三方再次互審後進 M 級開發

附錄：引用對照

R5-D1：progress.md「R5-Design 補充」第 1 題 — 保留 OS 通知
R5-D2：progress.md「R5-Design 補充」第 2 題 — Linux 預設 OFF
R5-D3：progress.md「R5-Design 補充」第 3 題 — 每次啟動都自動開
Design Spec v2 v2/control-panel.md 行 77 / 178 — Footer 持久警示
Design Spec v2 v2/control-panel.md §5 — Error state 面板三個按鈕
Design Spec v2 v2/server-offline-overlay.md 行 38–41 / 80–81 / 203 / 216–217 — Overlay 元件 + 硬阻斷 + focus trap
Design Spec v2 v2/first-run-update.md 行 24 / 51–52 — auto-open 預設 ON、兩步 wizard
Design Spec v2 v2/settings-update.md §1.1 — auto-open toggle 位置（本文認定需修正）
PRD v2 §0 / §4 N2 / §5 US-1 / §5 US-7 — 以上被指出的段落

Design 第二輪審閱 PRD v2.1（2026-04-14）

審閱者：Design Agent 審閱對象：/Users/jimchen/visionA/local-tool/.autoflow/02-prd/PRD-v2.md（v2.1，500 行）對照基準：第一輪審閱（本檔 §A–§H）+ R5-D / R5-E 決策 + Design Spec v2.1 03-design/v2/startup-progress.md（417 行，6 階段已定版）範圍：只審 v2.1 補丁差異，不重審 v2.0 未動章節本審閱使用繁體中文台灣用語

摘要（3 行）

總結論：✅ 通過（不需第三輪 PRD 修訂；可直接進 M8 開發前 TDD v2 撰寫）
第一輪 4 Major / 4 Minor 修復情況：Major 全部修好（4/4）、Minor 全部修好（4/4）。R5-E1～E6 全數正確落地進 US-1 AC-1.3 系列。
是否阻擋 M8：❌ 不阻擋。第二輪只發現 1 個 Minor 文字殘留 + 1 個 Minor Linux skipped 狀態未在 PRD 提及（可由 TDD / Design Spec 側吸收，不需 PRD 再修）。

A. 第一輪 Major 修復檢查

第一輪 Major	v2.1 修復位置	判定
Major 1 R5-D3「每次啟動自動開」	§0 §22 摘要點 5 改寫為「每次啟動都自動開」；§0.1 補丁表 M1 明列 replace；§2.1 P1 描述、§4 N2、§5 US-1 AC-1.6、§5 US-2 AC-2.1、§10 變更追蹤行 456 全部一致	✅ 修好
Major 2 R5-D2 Linux 預設 OFF	§0 摘要點 5 + §4 N2 + §5 US-1 AC-1.6 + §5 US-2 AC-2.3 + §6.3 + §10 變更追蹤行 456 全部明確列出「macOS/Windows ON；Linux OFF」+ 引用 R5-D2 + 引用 `xdg-open` 行為不穩理由	✅ 修好
Major 3 R5-D1 Server 崩潰 OS 通知	§5 US-7 新增 AC-7.7（行 275）明寫「除控制台 Error banner 外，同步發一次 OS 原生通知」+ 平台對應（Notification Center / Toast / `libnotify`）+ 去重策略授權 Architect 在 TDD v2 決定；§4 N7（行 167）也新增「Server 崩潰 OS 原生通知」功能條目	✅ 修好（同時於 US 與功能清單兩處落地，比第一輪要求更完整）
Major 4 auto-open toggle 位置	§4 N2（行 162）明標「auto-open toggle 住 Wails 控制台的 Settings menu （已與 Design 取得共識）」；§4.4 對照表行 179 同步；§11-6 標 ✅ 已解決	✅ 修好

A 區結論：第一輪 4 個 Major 全部修好，無殘留。

B. 第一輪 Minor 修復檢查

第一輪 Minor	v2.1 修復位置	判定
Minor 1 US-2 沒寫日常 auto-open	§5 US-2 AC-2.1（行 214）改寫：「日常啟動時，若 Wails 控制台 Settings `autoOpenBrowser === true`，仍會自動開瀏覽器（和首次啟動行為一致，R5-D3 / Design review Minor 1）」	✅ 修好
Minor 2 Offline Overlay 硬阻斷特性	§4 N3（行 163）補：「A11y 硬阻斷特性：`role="alertdialog"` + `aria-modal="true"` + focus trap + 不可由使用者手動關閉（無 ✕ 按鈕）」；§5 US-7 AC-7.1（行 269）也補「Overlay 無 ✕ 按鈕、不可手動關閉」+ 引用 Design review Minor 2；§4 N3 同時補強為「全螢幕半透明 backdrop（`rgba(0,0,0,0.4-0.5)`）+ 置中純色卡片」（解除 F6 措辭誤導）	✅ 修好
Minor 3 Footer 持久警示 + Error state 三按鈕	§4 N1（行 161）補完整段：「Footer 持久警示：右下角固定顯示 `⚠ 關閉此視窗會停止 Local Server`（12 px muted）」+「Error state 面板：log panel 上方浮動 banner 含 `Restart Server` / `View log` / `Report issue` 三個動作按鈕」；§5 US-7 AC-7.3（行 271）+ AC-7.6（行 274）同步	✅ 修好
Minor 4 First-Run wizard 3 步→2 步	§5 US-1 AC-1.4（行 202）補：「First-Run wizard 從 v1.2 的 3 步縮為 2 步（砍模式選擇，R5-5a）：Step 1 歡迎 → Step 2 硬體偵測。Step 2 在無硬體情況下可按 `稍後再設定` 略過」；§10 變更追蹤行 459 同步登記	✅ 修好

B 區結論：第一輪 4 個 Minor 全部修好，無殘留。

C. R5-E 落地檢查（v2.1 最大新增）

R5-E	PRD v2.1 落點	判定
R5-E1 AC-1.3 改 60 秒	§5 US-1 AC-1.3（行 197）改寫：「全程 ≤ 60 秒（R5-E1，原 10 秒硬指標取消）... 採 Nielsen Norman perceived performance 原則」；§11-2 標「✅ 已解決（由 R5-E 取代）」	✅ 正確落地
R5-E2 階段化進度（6 階段）	§5 US-1 AC-1.3a（行 198）：「啟動全程顯示階段化進度（6 階段，見 §4 N8），每階段有編號 + 動作描述 + 視覺回饋（spinner 或進度條）+ 中英雙語文案」；§4 N8（行 168）同步新增完整功能條目	✅ 正確落地
R5-E3 20 秒 retry hint	§5 US-1 AC-1.3b（行 199）：「任一啟動階段卡超過 20 秒，UI 必須顯示『正在重試』或『這步比預期久』類提示，不可停留在白畫面或無變化狀態」	✅ 正確落地
R5-E4 60 秒 Error state	§5 US-1 AC-1.3c（行 200）：「總啟動時間超過 60 秒仍未進入『就緒』狀態，Wails 控制台進入 Error state，顯示『Restart Server』『View log』『Report issue』三個動作按鈕（對應 §4 N1 / N6，與 watchServer 3 次失敗後行為一致）」	✅ 正確落地（按鈕命名與 Design Spec v2.1 §3.7 完全一致）
R5-E5 階段文案 Design 決定	§4 N8 行 168 末句：「階段文案由 Design Agent 最終決定（R5-E5）」；§5 AC-1.3a 同樣引用；§11-7 標「⏳ 懸置（R5-E5 使用者授權 Design Agent 決定）」— 但 Design Spec v2.1 已經定版（見 §D）	✅ 正確落地（PRD 不列文字本身，授權 Design 主導）
R5-E6 WebSocket 就緒	§5 US-1 AC-1.3d（行 201）：「『瀏覽器就緒』的定義 = Web UI 建立 WebSocket 連線到 server（hub 收到第一個 client），不是瀏覽器視窗出現時。不做新 endpoint、不做固定延遲（R5-E6）」；§4 N8 + §6.3「WebSocket 就緒偵測」一節（行 321）同步	✅ 正確落地

C 區結論：R5-E1～E6 六項全部正確、完整落地進 PRD v2.1，且分布合理（功能條目 §4 N8 / 驗收標準 §5 AC-1.3 系列 / 非功能 §6.3 / 變更紀錄 §10 / 懸念 §11 都有同步），不會發生 Architect 漏看的情況。

D. PRD 與 Design Spec v2.1 一致性

對照 Design Spec v2.1 03-design/v2/startup-progress.md：

對照點	Design Spec v2.1	PRD v2.1	判定
階段數量	6 階段（§4 表格）	§4 N8 + AC-1.3a 都明寫「6 階段」	✅ 一致
階段順序與名稱	1 初始化控制台 / 2 檢查 Python / 3 啟動 server / 4 偵測裝置 / 5 開瀏覽器 / 6 等待 Web UI 連線	§4 N8 順序：「初始化控制台 → 檢查 Python → 啟動 server → 偵測裝置 → 開瀏覽器 → 瀏覽器就緒」	✅ 一致（PRD 第 6 階段稱「瀏覽器就緒」，Design Spec 稱「等待 Web UI 連線」，語意對齊不衝突；Design 為 ground truth）
Error state 三按鈕命名	`重試 / Retry`、`檢視 log / View Log`、`回報問題 / Report Issue`	AC-1.3c：「Restart Server / View log / Report issue」；AC-7.3：「`Restart Server` / `View log` / `Report issue`」	⚠️ Minor 5（新）：PRD 把第一顆按鈕寫成「Restart Server」（控制台原本既有的按鈕命名），Design Spec v2.1 §3.7 行 219 寫「重試 / Retry」（重置進度面板，重新跑階段 1）。兩者語意不同：Restart Server 是重啟 server 子程序、Retry 是重置啟動流程跑階段 1。建議 PRD 在 AC-1.3c 與 AC-7.3 統一為「Retry / 重試」（與 Design Spec v2.1 一致），或請 Architect 在 TDD v2 決定兩個是否合併為同一動作。不阻擋開發，但 TDD 必須仲裁。
60 秒總預算	§3.7 + §1（R5-E4）	AC-1.3 / AC-1.3c	✅ 一致
20 秒卡住 hint	§3.6 + §2.2 wireframe	AC-1.3b	✅ 一致
WebSocket = ready 訊號	§4 階段 6 完成條件	AC-1.3d + §4 N8	✅ 一致
Linux 階段 5 跳過 / 階段 6 manual hint	Design Spec v2.1 §4.1「階段 5 Linux/Settings OFF 情境：`pending → skipped`」+「階段 6 Settings OFF 情境：description 改為 `請點擊控制台的「在瀏覽器開啟」按鈕`」	PRD v2.1 §4 N2 / §6.3 / §5 AC-1.6 / AC-2.3 都有寫 Linux 預設 OFF 與「使用者可手動按 Open in Browser」，但沒明寫階段化進度面板在 Linux 下「階段 5 跳過 + 階段 6 改 manual hint」這個細節	⚠️ Minor 6（新）：缺 Linux 路徑下的階段面板行為描述。但這純屬實作層細節，Design Spec v2.1 已是 ground truth，Frontend 看 Design Spec 即可。不阻擋、不需 PRD 修訂。
Reduced motion / WCAG 4.5:1	Design Spec v2.1 §6	PRD v2.1 §6.4 / §4 N3 已寫卡片純色 4.5:1，未提 startup panel 的 reduced-motion，但這已超出 PRD 顆粒度	✅ 可接受（細節由 Design Spec 與 TDD 承擔）

D 區結論：核心一致，唯一需要警示的是 Minor 5（按鈕命名分歧），TDD v2 必須仲裁。

E. §11 懸念狀態核對

#	v2.1 標示	第二輪判定
11-1 preferences 落點	✅ 已解決	✅ 確認
11-2 AC-1.3 10 秒可達	✅ 已解決（由 R5-E 取代）	✅ 確認
11-3 idle RAM 450 MB	✅ 已解決	✅ 確認
11-4 N-R4 CI/E2E 分層	⏳ 懸置 → Testing	✅ 維持懸置（屬於 Testing 範疇，不阻擋 PRD）
11-5 常駐徽章	✅ 已解決：不加	✅ 確認
11-6 auto-open toggle 位置	✅ 已解決：Wails 控制台	✅ 確認
11-7 R5-E 階段文案定稿	⏳ 懸置	🟡 可改為 ✅ 已解決 — Design Spec v2.1 §4 已定版 6 階段中英雙語文案（zh-TW + en），且使用者已授權 Design 決定（R5-E5）。建議 PRD 下次小修時把 §11-7 改為 ✅ 並指向 `03-design/v2/startup-progress.md §4 / §7`。不阻擋

E 區結論：懸念狀態合理，§11-7 可以順手結案但非必要。

F. 第二輪新發現問題

Major（阻擋）

無。

Minor（不阻擋，建議交 TDD / Design Spec 階段順手處理）

#	標題	位置	修正建議	接手者
Minor 5	Error state 第一顆按鈕命名分歧（Restart Server vs Retry）	PRD §5 AC-1.3c / AC-7.3 vs Design Spec v2.1 §3.7	TDD v2 仲裁兩個動作是否合併。建議：Startup Error 階段用「Retry（重置進度，重跑階段 1）」、Running 階段 watchServer 失敗用「Restart Server（kill + 重 spawn server 子程序）」，是兩個獨立動作	Architect（TDD v2）
Minor 6	PRD 未描述 Linux/auto-open OFF 情境下啟動進度面板的階段 5 skipped + 階段 6 manual hint 行為	PRD §4 N8 / AC-1.3a	不需修 PRD；Frontend 依 Design Spec v2.1 §4.1 實作即可	Frontend（M8 開發）
Minor 7（極輕微）	§變更紀錄行 499 v2.0 那一列仍寫「首次自動開瀏覽器」	PRD 行 499	純歷史紀錄、非生效規格，不需修	—

G. 第二輪通過 / 不通過結論

✅ 通過。

理由：

第一輪 Major 4/4 + Minor 4/4 全部修好，無殘留。
R5-E1～E6 六項全部正確落地，分布合理（功能、AC、非功能、變更紀錄、懸念全部同步）。
與 Design Spec v2.1 startup-progress.md 主要一致；唯一分歧（Error state 按鈕命名 Minor 5）屬於語意層差異，由 TDD v2 仲裁即可。
§11 懸念狀態合理，§11-7 可順手結案但非必要。
PRD v2.1 控制在 500 行，符合文件管理策略；模組化結構未被破壞。

不需第三輪 PRD 修訂。建議流程：

✅ PRD v2.1 凍結，進入 M8 開發前 TDD v2 撰寫
Architect 撰寫 TDD v2 時：
- 仲裁 Minor 5 Error state 按鈕命名（Retry vs Restart Server）
- 接手 Minor 6 細節（Frontend 依 Design Spec v2.1 §4.1 實作 Linux 路徑）
- 接手 R5-D1 OS 通知去重策略（PRD 已授權）
Design Agent 同步：
- 確認 v2/settings-update.md 已修正 auto-open toggle 位置（Major 4 後續）
- 把 startup-progress.md §4 6 階段文案定版告知 PM，請 PM 在下次小修時把 §11-7 改 ✅

對 M8 開發的訊號：🟢 GO。

30 KiB Raw Blame History Unescape Escape

Design 交叉審閱 PRD v2（2026-04-14）

摘要（3 行）

A. 使用者體驗完整性檢查

B. Design Spec v2 子檔對應檢查

C. 體驗紅線 / 缺漏

C.1 北極星指標的時間預算

C.2 砍 Mock 後的 P3 fallback 體驗

C.3 Server Crash 的錯誤處理體驗

C.4 關閉 Wails 視窗的 race condition

C.5 Offline Overlay 的硬阻斷特性

D. 對 PM 懸念 §11-5 的回答（常駐徽章）

E. 對 Architect Q6 的回答（Overlay 關閉 tab 按鈕）

F. 臆測 / 誤解 / 超範圍清單

G. 問題清單

Major（阻擋開發，必須改）

Minor（可在後續補，不阻擋開發）

H. 通過 / 不通過 結論

附錄：引用對照

Design 第二輪審閱 PRD v2.1（2026-04-14）

摘要（3 行）

A. 第一輪 Major 修復檢查

B. 第一輪 Minor 修復檢查

C. R5-E 落地檢查（v2.1 最大新增）

D. PRD 與 Design Spec v2.1 一致性

E. §11 懸念狀態核對

F. 第二輪新發現問題

Major（阻擋）

Minor（不阻擋，建議交 TDD / Design Spec 階段順手處理）

G. 第二輪通過 / 不通過 結論

30 KiB

Raw Blame History

H. 通過 / 不通過結論

G. 第二輪通過 / 不通過結論