visionA/local-tool/.autoflow/04-architecture/v2/milestone-plan.md

v2/milestone-plan.md — M8 開發 milestone 拆分

所屬：TDD v2 §2.7 版本：v2.1（2026-04-14 吸收 PM 審閱 + R5-D + R5-E） 目的：給 Orchestrator 調度工程師 Agent 用。每個 milestone = 一個 Reviewer 審查單位。 總工時估算：~12.0 人天（v2.0 是 10 人天；R5-E 階段化啟動 +1 天 / PM Q4 7+1 秒 shutdown modal +0.2 天 / R5-D1 OS 通知 +0.3 天 / Minor 4 WebSocket 廣播 +0.3 天 / M8-10 驗收項目擴充 +0.2 天，合計 +2 人天。與 §3 合計 12.0 一致）

---

1. M8 全景

v2.1 的開發總共拆成 11 個 milestone，編號 M8-1 ~ M8-10 + M8-4b。依賴關係：

M8-1 (砍 yt-dlp) ──────┐
                       ├──▶ M8-4 (server lifecycle) ──▶ M8-4b (階段化啟動) ──▶ M8-5 (Wails UI 改寫) ──▶ M8-9 (boot-id + 重連)
M8-2 (砍 Mock) ────────┘                                                                                    ▲
                                                                                                            │
M8-3 (ffmpeg LGPL vendor) ─────────────────────────────────────────────────────────────────────────────────┼──▶ M8-10 (end-to-end)
                                                                                                            │
M8-6 (source-selector 調整) ────────────────────────────────────────────────────────────────────────────────┤
                                                                                                            │
M8-7 (Offline Overlay) ─────────────────────────────────────────────────────────────────────────────────────┤
                                                                                                            │
M8-8 (CORS) ────────────────────────────────────────────────────────────────────────────────────────────────┘

• M8-1 / M8-2 / M8-3 / M8-8 可以同時開工（互不依賴）
• M8-4 依賴 M8-1（因為 app.go 內的 mockMode field 會在 M8-2 砍掉；但 M8-4 主要碰 server_control.go / log_buffer.go 不衝突，實務可平行）
• M8-4b 依賴 M8-4（需要 ServerController 已存在才能插入 pipeline hook）
• M8-5 必須等 M8-4b 完成（bindings + event schema 定義完）
• M8-6 可以獨立進行
• M8-7 依賴 M8-4（需要 boot-id server 端 + WebSocket hub，會在 M8-4 一併做）
• M8-9 依賴 M8-4 + M8-4b + M8-7
• M8-10 必須全部完成後

---

2. Milestone 明細

M8-1：砍 yt-dlp 全套

預估：0.5 人天

負責 Agent：Backend Agent + Frontend Agent（同時進行，因為跨 Go + TS）

依賴：無

任務：

1. 依 v2/deletions.md §1 刪後端 Go（video_source.go / camera_handler.go / router.go / deps/checker.go / main.go 註解）
2. 依 v2/deletions.md §5 刪前端 TS（source-selector.tsx 的 URL tab / camera-store.ts 的 startFromUrl / i18n 4 個 key）
3. 依 v2/deletions.md §4.1 + §4.2 + §4.3 + §4.4 + §4.5 刪打包流程（Makefile / installer / bootstrap）
4. 刪除 /vendor/yt-dlp/ 目錄（若存在）

驗收條件：

• go build ./... PASS
• go test ./server/... PASS
• pnpm --dir frontend build PASS
• git grep -i 'yt-dlp\|ytdlp\|ResolveWithYTDLP\|StartFromURL\|classifyVideoURL\|pasteUrl\|urlPlaceholder' 無業務程式碼 match（僅 .autoflow/ 內的歷史文件可接受）
• make payload-macos 可成功（不再 cp yt-dlp）

Reviewer 檢查重點：

• camera_handler.go 砍掉後 import 清理乾淨
• i18n types.ts / zh-TW.ts / en.ts 三檔同步刪
• Makefile 三個平台的 vendor-ytdlp* target 都清

---

M8-2：砍 Mock 模式全套

預估：0.5 人天

負責 Agent：Backend Agent + Frontend Agent

依賴：無（理論上可與 M8-1 平行）

任務：

1. 依 v2/deletions.md §2 + §3 刪 Go（兩個檔整檔刪、device/manager.go / camera/manager.go / config.go / main.go / app.go 所有 mockMode 條件砍掉）
2. 依 v2/deletions.md §6 刪前端 Mock 切換 UI + 4 個 i18n key
3. 更新 noDevices 文字（empty state 友善化）

驗收條件：

• Go + 前端 build PASS
• git grep -i 'VISIONA_MOCK\|MockMode\|mockMode\|MockCamera\|MockDriver\|NewMockDriver\|runtimeModeMock' 無業務程式碼 match
• 實機啟動 server（沒插 Kneron 硬體）→ Devices 頁顯示友善 empty state「未偵測到 Kneron 裝置」

Reviewer 檢查重點：

• NewManager 簽名改動後所有呼叫點都更新
• 舊 --mock / --mock-camera / --mock-devices CLI flag 真的拿掉（server --help 不再列）
• 任何剩下的 test 檔案不再依賴 mockMode

---

M8-3：ffmpeg LGPL vendor 切換

預估：1.5 人天

負責 Agent：DevOps Agent（主）+ Backend Agent（支援 macOS build 環境）

依賴：無

任務：

1. Windows / Linux（0.5 人天）：依 v2/ffmpeg-lgpl.md §3 + §4 修改 Makefile 的 URL 與 vendor target，實測 make vendor-ffmpeg-windows / vendor-ffmpeg-linux 可成功
2. macOS build script（1 人天）：
   • 依 v2/ffmpeg-lgpl.md §2.3 新增 vendor-ffmpeg-macos-build Makefile target
   • 第一次跑：下載 ffmpeg n7.1 source、算 sha256 填進 Makefile、跑 configure + make、驗證 binary size < 25 MB、驗證 ffmpeg -version 不含 --enable-gpl / libx264 / libx265
   • 把 ffmpeg + ffprobe + COPYING.LGPLv3 + BUILD.md 進 git commit 到 vendor/ffmpeg/macos/
   • 修改 .gitignore 讓 vendor/ffmpeg/macos/ 成為 git tracked
   • 修改 vendor-ffmpeg target 改為「驗證 binary 存在且是 LGPL」
3. Payload 階段同步（§7）：三個平台的 payload-* target 改為 copy ffmpeg + ffprobe + COPYING.LGPLv3，不再 copy yt-dlp（M8-1 會處理刪）
4. Installer 同步（§8）：
   • installer/windows/visiona-local.iss 新增 ffprobe 和 LGPL license 行
   • installer/linux/build-appimage.sh 迭代 tool 改為 ffmpeg ffprobe

驗收條件：

• make vendor-ffmpeg PASS（macOS），binary size OK（見 v2/ffmpeg-lgpl.md §10 驗收表）
• vendor/ffmpeg/macos/ffmpeg -version | grep -- --enable-gpl 無輸出
• spctl --assess --verbose vendor/ffmpeg/macos/ffmpeg → accepted
• make vendor-ffmpeg-windows + vendor-ffmpeg-linux 可成功，檔案解出後 version 無 --enable-gpl
• make payload-macos 成功，payload/darwin/bin/ 內有 ffmpeg / ffprobe / ffmpeg-COPYING.LGPLv3
• 實測用 vendor/ffmpeg/macos/ffmpeg 解 5 種格式（mp4/avi/mov/mpeg/mpg）正常

Reviewer 檢查重點：

• vendor/ffmpeg/macos/BUILD.md 內容正確、可重現
• 開發者用單一 make vendor-ffmpeg-macos-build 指令真的能從零 build 出來（不依賴本機 cached state）
• .gitignore 的 ! rule 順序正確
• Makefile 的 configure flags 與 v2/ffmpeg-lgpl.md §2.3 完全一致

---

M8-4：Server lifecycle + log buffer + bindings + OS notify + Preferences

預估：2 人天（v2.0 是 1.5 天；+0.3 天 R5-D1 OS 通知、+0.2 天 PM Q4 7+1 秒 shutdown modal）

負責 Agent：Backend Agent（Go / Wails）

依賴：M8-1（避免 mockMode 欄位被砍後衝突）。實務上可與 M8-2 平行。

任務：

1. 新增檔案（v2/control-panel.md §7 + §4）：
   • visiona-local/log_buffer.go（~120 行 ring buffer）
   • visiona-local/server_control.go（~280 行 ServerController + state machine + startServerV2 + logPump + 7+1 秒 shutdown modal timer，見 server-lifecycle.md §8.2）
   • visiona-local/preferences.go（~80 行）— R5-D2：必須實作 DefaultPreferences() 依 runtime.GOOS 分平台預設（macOS/Windows AutoOpenBrowser=true、Linux false）+ atomic write-rename（server-lifecycle.md §11.3）
   • visiona-local/notify.go（~100 行）— R5-D1：三平台 OS 通知，macOS osascript display notification / Linux notify-send / Windows PowerShell BurntToast + msg * fallback，詳見 server-lifecycle.md §10
2. 修改 visiona-local/app.go：
   • 新增 ctrl / logBuf / prefs 欄位（不要 autoOpenedThisSession — R5-D3 已砍掉 per-session-once 概念）
   • 砍 GetBootstrapStatus / setBootstrapStatus / bootstrapStatus 欄位
   • 改 watchServer() 失敗後行為（不 os.Exit，改設 Error state + goroutine 呼叫 sendCrashNotification — R5-D1）
   • 新增 12 個 Wails bindings（v2/control-panel.md §4.2）
3. 修改 visiona-local/main.go：
   • 加 OnBeforeClose handler
   • shutdownGracePeriod 5 s → 7 s（PM Q4 定案，不是 10 s）
4. 修改 server/main.go + system_handler.go + router.go：
   • 新增 boot-id 生成（使用 crypto/rand 16 bytes → hex，Architect Q3 決定，不引 google/uuid）
   • 新增 GET /api/system/boot-id endpoint
   • Minor 4：server 新增 WebSocket hub 廣播 server:shutdown-imminent 的能力（新增 /ws/system endpoint 或擴充現有 /ws/server-logs）；Wails 的 ctrl.Stop() 在開始 SIGTERM 前透過 HTTP 或 server 內部 API 觸發此廣播
   • 對齊 shutdown timeout：server/main.go:166 的 shutdownFn timeout 10 s → 6 s（Wails 7 s 減 1 s，確保 server 先完成 cleanup）

驗收條件：

• cd visiona-local && go build . PASS
• cd server && go build ./... PASS
• 12 個 bindings 在 visiona-local/frontend/wailsjs/go/main/App.d.ts 正確生成
• 手動測試：新 bindings 可從 Wails dev 模式的 devtools console 呼叫
• 手動測試：Start → server 啟動 → 看 log 噴進 LogBuffer → 用 GetRecentLogs(20) 取回
• 手動測試：Stop → 1 秒內顯示「停止中…」modal（若 server 未秒 exit）+ 7 秒內 SIGKILL（若卡死）
• 手動測試：Restart → state: Running → Stopping → Stopped → Starting → Running
• 手動測試：殺 server process → watchServer 3 次失敗後 state → Error + 收到 OS 原生通知（三平台都要）
• R5-D2 驗收：全新使用者第一次在 macOS/Windows 開 app → preferences.json 不存在 → DefaultPreferences() 回傳 AutoOpenBrowser=true；Linux 上回傳 false
• curl http://127.0.0.1:<port>/api/system/boot-id 回傳 JSON 含 bootId（hex 32 字元）
• WebSocket server:shutdown-imminent 廣播：用 websocat 連 /ws/system，按 Stop 後秒收到廣播

Reviewer 檢查重點：

• LogBuffer thread-safety（mutex 正確）
• ServerController 的 txMu / mu 互斥
• logPump 在 server 死掉 / pipe EOF / 高頻 stdout 下都不 leak goroutine
• parseLogLevel 不會 panic on 空字串或非 ASCII
• boot-id 生成使用 crypto/rand + encoding/hex（不引 google/uuid）
• Preferences JSON atomic write（tmp + rename，見 §11.3）
• DefaultPreferences() 依 runtime.GOOS 正確切換（Linux 分支有測試）
• sendCrashNotification 三平台檔案（darwin/linux/windows build tag）齊全且不阻塞
• shutdown modal 的 1 秒 timer 與 7 秒 grace timer 正確（goroutine 泄漏檢查）
• server 端 WebSocket hub 廣播邏輯與 Wails 端呼叫的契約（傳遞 reason 欄位）

---

M8-4b：階段化啟動管線（R5-E）

預估：1 人天（v2.0 未拆出，v2.1 新增）

負責 Agent：Backend Agent（Go / Wails）+ Frontend Agent（vanilla JS startup panel）

依賴：M8-4（需要 ServerController + bindings）

任務：依 v2/startup-pipeline.md（若該檔不存在則落在 control-panel.md §3.1 + server-lifecycle.md §2.1）

1. 新增 visiona-local/startup_pipeline.go（~180 行）：
   • StartupPipeline struct（含 currentStage / stageStartedAt / startedAt / softTimeout / hardTimeout）
   • NewStartupPipeline(ctx) / Start(stage int) / Complete(stage int) / Fail(stage int, err) / Ready() 方法
   • watcher(ctx) goroutine：每秒檢查 soft timeout (20 s) + hard timeout (60 s)，emit startup:stage-timeout / startup:error event
   • 4 個 event schema：startup:progress / startup:stage-timeout / startup:error / startup:ready（見 v2/startup-pipeline.md §1）
2. 修改 visiona-local/app.go 的 startup(ctx)：
   • 在 OnStartup 最前面初始化 pipeline 並 Start(1)
   • 每個既有階段的對應處呼叫 pipeline.Complete(N) + pipeline.Start(N+1)
   • 6 個階段對應：1=Wails init、2=Python runtime、3=server binary spawn + health check、4=first /api/devices 查詢、5=OpenInBrowser call、6=WebSocket 首個 client connect
   • 最後 pipeline.Ready() → emit startup:ready
3. 修改 server 端：
   • pkg/ws（或對應的 WebSocket hub）新增 OnClientConnected callback，讓 Wails 能收到「第一個 client 連上」的通知（透過 WebSocket 或 HTTP poll）
   • Wails 的 startup_pipeline.go 訂閱此通知完成階段 6
4. 失敗處理：任一階段失敗 → pipeline.Fail(stage, err) → ctrl.setState(Error, ...) + sendCrashNotification + emit startup:error
5. 非阻塞：所有 EventsEmit 呼叫都走 buffered channel 或 fire-and-forget goroutine，不阻塞啟動流程
6. 前端（Wails 控制台）：
   • visiona-local/frontend/components/startup-panel.js（~100 行）
   • 訂閱 4 個 event 更新 DOM
   • 收到 startup:ready 淡出（300 ms ease）
   • i18n key 從 i18n/zh-TW.json / en-US.json 讀（文案由 Design Spec v2.1 敲定）

驗收條件：

• cd visiona-local && go build . PASS
• 正常冷啟動（樂觀情境）：4 s 內看到「啟動進度面板」6 階段逐一 completed，最後淡出顯示主控台
• 慢啟動情境：mock 階段 2 jam 25 秒 → 看到「階段 2 正在重試 …」副文字
• 失敗情境：mock 階段 3 fail → 看到進度面板變紅、切 Error state、收到 OS 通知、發 startup:error event
• 總時 > 60 秒情境：mock 每個階段都等 12 秒 → 60 秒後進 Error state（watcher 總時檢查有效）
• 日常啟動（非首次）：~3 s 內就緒，符合 PM AC-2.1

Reviewer 檢查重點：

• watcher goroutine 在 pipeline.Ready() / Fail() 後正確停止，不 leak
• EventsEmit 非阻塞（若 Wails IPC 慢也不拖啟動）
• 6 階段的 labelKey 與 design-spec v2.1 一致
• 失敗後 Error state 透過 ctrl.setState 觸發，不繞過 state machine
• startup-panel.js 的淡出動畫不會卡住主控台 UI

---

M8-5：Wails 控制台 vanilla UI 改寫

預估：2 人天

負責 Agent：Frontend Agent（vanilla JS）

依賴：M8-4（需要 bindings + events）

任務：

1. 改寫 visiona-local/frontend/index.html 成控制台 layout（v2/control-panel.md §3）
2. 改寫 visiona-local/frontend/app.js 成控制台主程式（§5）
3. 改寫 visiona-local/frontend/style.css 新增 status card / log panel / action bar / preferences 樣式，並加 light/dark mode CSS variables
4. 新增 components：
   • components/status-card.js
   • components/log-panel.js（含 virtual scroll lite + batch render）
   • components/action-bar.js（含 disable 矩陣）
   • components/preferences.js
5. 新增 i18n：
   • i18n/en-US.json / zh-TW.json
   • i18n/loader.js
6. 新增 icons：icons/*.svg × 6

驗收條件：

• Wails dev 模式下開 app：
  • ✅ 看到控制台 UI（status / log / actions / preferences），不是 splash / blank / Next.js
  • ✅ Start 按鈕能啟動 server，狀態卡片變 Running 綠色 badge
  • ✅ Log panel 即時顯示 server stdout（看到 Gin log）
  • ✅ Stop 按鈕能停 server，badge 變灰
  • ✅ Restart 按鈕能重啟（狀態過程正確）
  • ✅ Open in Browser 開瀏覽器到正確 URL
  • ✅ Reveal Logs 開啟 <dataDir>/logs/ 資料夾
  • ✅ Clear Logs 清畫面但不動磁碟檔
  • ✅ Preferences 切 openBrowserOnStart 持久化到 preferences.json
  • ✅ Dark mode 跟隨系統（macOS 切換 Dark Mode 後控制台自動變色）
  • ✅ Log panel 按 Pause 後自動捲動停止，解除後恢復
• make wails-macos 能 build 出 .app，打開後看到控制台 UI（M7-B 教訓）

Reviewer 檢查重點：

• vanilla JS 沒引入任何 npm 依賴（package.json 不存在於 visiona-local/frontend/）
• Log panel 在高頻（1000 行/秒）下不會 freeze UI（batch render 有效）
• i18n loader SSR-safe（不適用，但 Wails 沒 SSR 概念）
• icons/ 下的 SVG 符合 inline 使用的簡潔規則（viewBox + single path）
• Action bar 在每個 state 下 button enable/disable 正確（disable 矩陣全部驗證）

---

M8-6：Web UI source-selector + 副檔名擴充

預估：0.5 人天

負責 Agent：Frontend Agent

依賴：無（與其他 milestone 平行）

任務：

1. frontend/src/components/camera/source-selector.tsx 依 v2/deletions.md §5.1 移除 URL tab + mode toggle
2. 把 accept=".mp4,.avi,.mov" 改為 accept=".mp4,.avi,.mov,.mpeg,.mpg"
3. i18n 新增 videoFormats key 或改既有 mp4AviMov
4. 後端同步：server/internal/api/handlers/camera_handler.go:251 把 extension whitelist 從 .mp4 / .avi / .mov 擴充為 5 個：

   -if ext != ".mp4" && ext != ".avi" && ext != ".mov" {
   -    c.JSON(400, gin.H{"success": false, "error": gin.H{"code": "BAD_REQUEST", "message": "only MP4/AVI/MOV files are supported"}})
   +if ext != ".mp4" && ext != ".avi" && ext != ".mov" && ext != ".mpeg" && ext != ".mpg" {
   +    c.JSON(400, gin.H{"success": false, "error": gin.H{"code": "BAD_REQUEST", "message": "only MP4/AVI/MOV/MPEG/MPG files are supported"}})
    }
   

驗收條件：

• 前端 build PASS
• 手動測試：5 種副檔名都能上傳且正常開始推論
• UI 不再有「Paste URL」按鈕

Reviewer 檢查重點：

• handler 裡的 extension 比對是 strings.ToLower 後再比，大小寫不敏感
• 錯誤訊息中英文同步

---

M8-7：Web UI Server Offline Overlay

預估：1 人天

負責 Agent：Frontend Agent

依賴：M8-4（需要 server 端 boot-id endpoint）

任務：依 v2/web-ui-offline-overlay.md §4 的 7 個檔案清單：

1. 新增 frontend/src/stores/system-store.ts
2. 新增 frontend/src/hooks/use-boot-id-watcher.ts
3. 新增 frontend/src/components/server-offline-overlay.tsx
4. 新增 frontend/src/components/boot-id-watcher-mount.tsx
5. 修改 frontend/src/app/layout.tsx（掛 overlay + watcher）
6. 修改 frontend/src/lib/i18n/{types,zh-TW,en}.ts（新增 serverOffline 區塊）

驗收條件：

• pnpm --dir frontend build PASS（含 SSR 相容性驗證）
• 手動測試：
  • 正常啟動沒 overlay
  • 關 Wails 視窗後 15 s 內瀏覽器 tab 顯示 overlay
  • 重新開 Wails app → Web UI 的「重試」按鈕有效（overlay 消失）
  • 控制台按 Restart → boot-id 變 → 自動 window.location.reload()
  • 切到別的 tab 5 分鐘再切回 → polling 立即 probe 不用等

Reviewer 檢查重點：

• Zustand store 的 failures state 遞增正確
• use-boot-id-watcher.ts 的 cleanup（useEffect return）正確 cancel
• AbortSignal.timeout(3000) 在舊瀏覽器相容性（若需支援 Chrome < 103 則 fallback）
• Overlay 元件 a11y（role="alertdialog" + aria-labelledby）
• i18n 新增 key 三個檔同步（types / zh-TW / en）

---

M8-8：CORS + origin check middleware

預估：0.5 人天

負責 Agent：Backend Agent

依賴：無

任務：依 v2/cors-security.md §4 + §5：

1. 覆寫 server/internal/api/middleware.go（白名單版）
2. 新增 server/internal/api/ws/origin.go
3. 修改所有 WS handler 的 upgrader CheckOrigin
4. 新增 server/internal/api/middleware_test.go 單元測試（TestIsAllowedOrigin）
5. 在 router.go 掛 requireSameOriginOrNoOrigin middleware 到 /api/*

驗收條件：

• go test ./server/internal/api/... -run TestIsAllowedOrigin PASS
• v2/cors-security.md §9 所有 curl 驗收條件通過
• WS websocat 測試：白名單 origin 可連、非白名單擋
• 既有 Next.js Web UI 的 fetch 仍正常運作（same-origin + white list）

Reviewer 檢查重點：

• isAllowedOrigin 對 edge case 處理正確（空字串 / null / https / 不合規 URL）
• 不 accidentally 把 X-Relay-Token header 保留（relay 早已砍）
• WS upgrade 在非白名單 origin 下回 403，不是靜默失敗
• Middleware 套用順序（middleware.go 的 CORSMiddleware 要在 requireSameOriginOrNoOrigin 之前）

---

M8-9：Boot-ID 端到端整合 + Restart 重連

預估：1 人天

負責 Agent：Backend Agent + Frontend Agent

依賴：M8-4 + M8-7

任務：

1. 整合驗證：M8-4 的 server 端 boot-id API + M8-7 的前端 polling 串起來
2. Restart 情境驗證：
   • 開 app → Open in Browser
   • 在 Wails 控制台按 Restart
   • 瀏覽器 tab 在 3-5 s 內自動 reload
   • Reload 後 server 是新的 port 也能正常連（因為 Next.js 是 static export，URL path 不變）
3. 自動開瀏覽器（R5-4 + R5-D2 + R5-D3）：
   • R5-D2（分平台預設）：macOS/Windows 預設 AutoOpenBrowser=true；Linux 預設 false
   • R5-D3（每次都開）：只要 AutoOpenBrowser=true，每次 Start/Restart 成功都呼叫 OpenInBrowser("") — 取消原 v2.0 的 per-session-once 設計
   • 使用者在 Preferences 切換 → 立即持久化到 preferences.json（atomic write）
4. Restart 期間 port 行為（F-2 強制保留）：
   • Restart 不允許 port fallback（startWithPort(oldPort, forceMatch=true)）
   • 舊 port 被佔用 → 進 Error state + 發 OS 通知
   • 正常 Restart → 新 server 用原 port → 瀏覽器 tab 偵測 boot-id 變 → reload → URL 原 port 仍有效 → 自動連上
   • 不會發生 v2.0 所述「port 變動後瀏覽器連不上」的情境

驗收條件：

• 關機情境（Wails 關 → server 停 → 瀏覽器 tab）：WebSocket shutdown-imminent 秒內顯示 overlay（不是 15 s 了，Minor 4）
• Restart 情境（Wails 按 Restart）：3-5 s 內瀏覽器自動 reload，URL 原 port 仍有效（F-2），UI 正常
• 首次開 app（macOS/Windows）：瀏覽器自動跳出新 tab
• 首次開 app（Linux）：瀏覽器不自動開（R5-D2 預設 false）
• Preferences 關閉後再開 app：瀏覽器不自動開
• 多次按 Restart：若 AutoOpenBrowser=true，每次 Restart 都會呼叫 OpenInBrowser（R5-D3）。OS 瀏覽器通常聚焦既有 tab 而不是開新 tab，使用者可接受
• R5-E 啟動進度面板：Starting 期間顯示 6 階段進度，完成後淡出

Reviewer 檢查重點：

• app.go 中不存在 autoOpenedThisSession 欄位（v2.0 已砍）
• Restart 呼叫 OpenInBrowser 的行為有在 M8-9 手動測試紀錄中驗證
• DefaultPreferences() 三平台分支在單元測試或手動測試中涵蓋
• Restart 的 port 強制保留邏輯正確（錯的 mock 情境下會進 Error state 而非 fallback）
• boot-id 在 server 重啟後真的變（不會意外 memoize 舊值）
• polling 的 consecutiveFailures 在 Restart 期間不會錯誤累積到 3（Restart 約 3 s，只有 0-1 次失敗）

---

M8-10：端到端 build + smoke test

預估：1 人天

負責 Agent：DevOps Agent + Testing Agent（QA）

依賴：M8-1 到 M8-9 全部完成

任務：

1. macOS：make clean-all && make dmg → dist/visiona-local.dmg
   • 安裝到全新 mac（或 VM）
   • 8 核心驗收（v2.1 擴充）：
     • ✅ 打開 app 先看到啟動進度面板（6 階段，R5-E），完成後淡出顯示控制台 UI（不是 splash / wizard / 白畫面）
     • ✅ 點 Open in Browser 後瀏覽器載入 Next.js Web UI
     • ✅ Web UI 沒有 URL tab（source-selector 清乾淨）
     • ✅ Web UI 沒有 Mock 模式切換（Settings > Hardware 乾淨）
     • ✅ 點 Stop 後瀏覽器秒內看到 Offline Overlay（WebSocket 廣播，不是 15 s 才顯示）
     • ✅ 手動殺 server process → 收到 macOS 原生通知 + 控制台 Error banner（R5-D1）
     • ✅ R5-D2：首次開 app 時 preferences.json 不存在，macOS 預設自動開瀏覽器（Linux 相對要反過來驗證）
     • ✅ 按 Restart 兩次，每次都會觸發 OpenInBrowser（R5-D3，砍掉 per-session-once）
2. Windows：在 Windows 機器上 make clean-all && make exe
   • 同樣 5 核心驗收
   • 注意：R5-7 同意 M7 Windows 先不管，但這次 M8-10 要順帶驗證（做完再驗）
3. Linux：在 Ubuntu 上 make clean-all && make appimage
   • 同樣 5 核心驗收
4. LGPL 稽核：三個平台的 installer 安裝後，<install>/bin/ 下都有 ffmpeg + ffprobe + ffmpeg-COPYING.LGPLv3
5. Installer size 對照：
   • macOS .dmg：預期 ~80-100 MB（v1 是 220 MB，砍 yt-dlp 35 MB + 砍 GPL ffmpeg 77 MB 換成 LGPL ~20 MB = 約 128 MB 降到 ~100 MB）
   • Windows .exe：預期 ~280-320 MB（v1 是 ~380 MB）
   • Linux .AppImage：預期 ~240-280 MB（v1 是 ~317 MB）
6. 回歸測試：
   • Kneron KL520 / KL720 實機跑推論（若有硬體）
   • 5 種副檔名上傳影片
   • 批次影像上傳
   • Camera（webcam）串流

驗收條件：

• 三平台 installer 全部能裝、能啟動、能進入控制台、能 Open Browser、能跑推論
• LGPL 合規稽核：grep -r 'enable-gpl' vendor/ffmpeg/ 無輸出
• 5 核心驗收 checklist 全綠
• Installer size 在預期範圍內

Reviewer 檢查重點：

• 驗收 checklist 每一項都有實測截圖 / log
• 回歸測試涵蓋 PRD v2 所列的核心 user story

---

3. 風險與緩衝

• M8-3 macOS 自 build ffmpeg 可能踩坑（configure flag 組合、pkg-config 環境、codesign）：預估 1.5 人天但可能實際花 2 人天。buffer 放在 M8-10 的 1 人天裡
• M8-4b R5-E 6 階段 event emit 的非阻塞保證：Wails v2 IPC 若慢，可能把啟動流程本身拖慢。需在 M8-4b 後做 mock 測試（每個階段插 dummy 延遲）確認 watcher goroutine 與 event emit 不互相阻塞
• M8-4 OS 通知三平台實測（R5-D1）：macOS 首次呼叫會彈出通知授權對話框；Windows 沒裝 BurntToast 會 fallback msg *（某些版本可能 block）；Linux 需要 libnotify-bin 已安裝。這三者都需要實機驗證，預估 0.3 天
• M8-5 控制台 UI 的 dark mode 可能需要反覆調整：若實測後使用者不喜歡預設配色，留給 Design Agent 一輪調整（不在本次範圍內）
• M8-4 高頻 log 壓測（R-v2-3）：若 Wails v2 EventsEmit 真的 flaky，要切 micro-batch 升級成 throttling + coalescing，可能再多 0.5 人天

總工時重估

Milestone	v2.0	v2.1	差異原因
M8-1	0.5	0.5	—
M8-2	0.5	0.5	—
M8-3	1.5	1.5	—
M8-4	1.5	2.0	+0.3 R5-D1 OS 通知、+0.2 Q4 7+1 秒 shutdown modal
M8-4b	—	1.0	新增，R5-E 階段化啟動
M8-5	2.0	2.0	—
M8-6	0.5	0.5	—
M8-7	1.0	1.3	+0.3 Minor 4 WebSocket shutdown-imminent 訂閱
M8-8	0.5	0.5	—
M8-9	1.0	1.0	—
M8-10	1.0	1.2	+0.2 核心驗收項目從 5 個擴為 8 個
合計	10.0	12.0	+2 人天

加上 buffer（M8-3 可能踩坑 + M8-4 高頻 log 壓測可能重構）~1 人天 → 建議 Orchestrator 對使用者回報 ~13 人天。

---

4. 交棒給 Orchestrator 的清單

Milestone	誰	觸發條件
M8-1	Backend + Frontend（並行）	使用者確認 TDD v2.1
M8-2	Backend + Frontend（並行）	同 M8-1
M8-3	DevOps + Backend（macOS host 可用）	同上，不依賴 M8-1/2
M8-4	Backend	M8-1 + M8-2 砍完
M8-4b	Backend + Frontend（vanilla JS）	M8-4 完成（需要 ServerController + WebSocket hub）
M8-5	Frontend	M8-4b bindings + event schema 可用
M8-6	Frontend	可與 M8-1/2/5 平行
M8-7	Frontend	M8-4 boot-id endpoint + WebSocket /ws/system 就緒
M8-8	Backend	可獨立進行
M8-9	Backend + Frontend	M8-4 + M8-4b + M8-7 完成
M8-10	DevOps + Testing	全部完成

提醒：每個 milestone 完成後，Orchestrator 啟動 Reviewer 審查，審查通過才進下一個 milestone（per 根目錄 CLAUDE.md 「強制 Review 規則」）。