jim800121/visionA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
visionA/local-tool/.autoflow/02-prd/reviews/design-review-of-prd-v2.md
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

348 lines
30 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 視角）：
1. **視覺雜訊成本 vs 防誤解收益不對等**。常駐徽章會佔用每一個瀏覽器畫面的固定像素（通常 32–40 px），但它防止的「誤以為是網頁服務」情境只在「使用者截圖給外部」的**極小機率事件**發生。以 FAE Arthur 為主要使用者，他自己知道這是 local app，截圖給客戶時「自己加註解」比「產品永遠帶徽章」的 ROI 好太多。
2. **資訊已由其他管道傳遞**。瀏覽器網址列就是 `http://127.0.0.1:3721`，這是**最權威的「這是本機服務」證據**，而且是瀏覽器原生 UI，設計成本 0。再加徽章是重複告知。
3. **和設計語言衝突**。Web UI 的設計語言（shadcn + Tailwind + 淡色背景）追求**資訊層級乾淨**，常駐徽章會像浮水印一樣破壞這個語言。Ollama Web UI / LM Studio / SD WebUI 都沒有這種徽章，這是業界慣例。
4. **替代方案**：如果 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」按鈕**
**理由**：
1. **技術限制已確認**。瀏覽器安全規範：`window.close()` 只能關閉**由 `window.open()` 開的 tab**。visionA-local 的 tab 是使用者手動開的（`xdg-open` / `open` / `start` 透過 OS 層開瀏覽器 → 瀏覽器建立新 tab），不是 JS 開的 → `window.close()` **一律失效**（Chrome/Edge/Safari/Firefox 全部一致）。
2. **Design Spec v2 `v2/server-offline-overlay.md` 已經沒有這個按鈕**（見行 38–41 原型、行 80–81 元件表）。目前只有兩個按鈕：
- `重試連線`（Primary, lg）
- `了解更多 ↓`（Ghost, sm，展開 help text）
3. **使用者的兩條恢復路徑都不需要「關閉 tab」按鈕**：
- **路徑 A（雙擊重開 app）**：Design Spec v2 行 142 已設計「Overlay 顯示期間 polling `/api/health` 每 3 秒」，使用者只要重開 app → 自動恢復 → Overlay 自動消失，不需手動關 tab。
- **路徑 B（不想用了）**：使用者直接按瀏覽器的 `⌘W` / `Ctrl+W` / 點 tab 的 ✕，是瀏覽器原生操作，完全不需要 JS 協助。
4. **「了解更多」展開 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 **之前**補上，否則會再次發生文件間矛盾。
**建議流程**：
1. PM Agent 收到本 review → 產出 PRD v2.1，修正 Major 1–3 + Minor 1–4（預估 20 分鐘）
2. Design Agent 同時修正 Design Spec v2 `v2/settings-update.md`（Major 4，auto-open 位置更正）
3. Architect 拿 PRD v2.1 + 更新後的 Design Spec v2 寫 TDD v2
4. 三方再次互審後進 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. 第二輪通過 / 不通過 結論
✅ **通過**。
**理由**：
1. 第一輪 Major 4/4 + Minor 4/4 全部修好，無殘留。
2. R5-E1～E6 六項全部正確落地，分布合理（功能、AC、非功能、變更紀錄、懸念全部同步）。
3. 與 Design Spec v2.1 `startup-progress.md` 主要一致；唯一分歧（Error state 按鈕命名 Minor 5）屬於語意層差異，由 TDD v2 仲裁即可。
4. §11 懸念狀態合理，§11-7 可順手結案但非必要。
5. PRD v2.1 控制在 500 行，符合文件管理策略；模組化結構未被破壞。
**不需第三輪 PRD 修訂**。建議流程：
1. ✅ PRD v2.1 凍結，進入 M8 開發前 TDD v2 撰寫
2. 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 已授權）
3. Design Agent 同步：
- 確認 `v2/settings-update.md` 已修正 auto-open toggle 位置（Major 4 後續）
- 把 `startup-progress.md §4` 6 階段文案定版告知 PM，請 PM 在下次小修時把 §11-7 改 ✅
**對 M8 開發的訊號**：🟢 GO。
Reference in New Issue View Git Blame Copy Permalink