visionA/local-tool/.autoflow/05-implementation/reviews/M8-9-review.md

Reviewer 審查 M8-9 Boot-ID + tab 重連（2026-04-15）

摘要

• 結論：✅ 通過，無 Critical / Major 問題。
• 是否阻擋 M8-10：不阻擋，可直接進入 M8-10。
• 問題統計：Critical 0 / Major 0 / Minor 2 / Suggestion 1
• 親跑：tsc PASS、test 19/19 PASS、lint（改動檔零 error）、build 12 頁 PASS。

---

A. checkAndUpdateBootId action

比對 TDD §9.3 規格（system-store.ts:92-103）：

行為	實作	狀態
bootId === null → 記錄 + 回 'first'	L94-97 set({ bootId: newBootId }) → return 'first'	✅
bootId === newBootId → 回 'match'，不改 store	L98-100 純 return	✅
bootId !== newBootId → 回 'mismatch'，刻意不改 store	L101-102 註解明確說明用意（reload 後新 tab 重走 first）	✅
TypeScript BootIdCheckResult union 定義	L18-26 'first' | 'match' | 'mismatch' + JSDoc 完整	✅

語意正確，註解與 TDD「mismatch 時不更新 store」的理由一致。get() 而非閉包 snapshot，避免競態。

B. handleBootIdCheck helper

use-shutdown-watcher.ts:87-123：

• 封裝完整：呼叫 store action、處理 loop guard、觸發 reload 全部集中於此 helper。
• DRY：pollOnce（L146）與 retryServerHealth（L347）都走同一 helper，沒有重複邏輯。
• Response shape 正確：BootIdResponse type（L46-52）完整對應 TDD §9.2 { success, data: { bootId, startedAt } }。L140 / L342 對 json.success 與 json.data?.bootId 雙重驗證，若缺欄位改走 recordFailure，不會把 undefined 丟進比對路徑。
• 回傳語意：true = 繼續後續流程（first / match），false = 已觸發 reload（或 SSR / guard skip），呼叫端不再 markOnline。L90-92 的 early return 避免對「即將 reload」的 tab 做多餘的 markOnline。

C. Reload loop guard

use-shutdown-watcher.ts:87-123：

檢查項	實作	狀態
key = visiona-reload-loop-guard	L38 const RELOAD_LOOP_GUARD_KEY	✅
正常情境：reload → store reset → 走 first 路徑不誤觸發	L89 checkAndUpdateBootId 先於 guard 比對；first 直接 return true，guard 不會被讀到	✅
異常情境（server 每次回不同 bootId）：guard 命中同一 id → skip reload + setBootId + markOnline	L102-111	✅
sessionStorage 失敗（隱私模式）→ 仍 reload	L100-115 整段包 try { ... } catch {}，catch 為空但之後 fall through 到 L117-121 window.location.reload()	✅
guard key 寫入時機：reload 之前	L112 setItem → L121 reload()，順序正確	✅
typeof window === 'undefined' → SSR 保險直接 return false	L95-98	✅

Minor 1：catch 空 block（L113-115）沒有任何 log，若 sessionStorage 存取失敗（即便在隱私視窗）開發者將看不到訊號。建議加 console.warn('[boot-id] sessionStorage unavailable, reload guard disabled')，只是提醒用，不阻擋 reload。不影響行為，不阻擋合併。

D. 和 M8-7 的 integration

• pollOnce (L126-152)：保留原流程，新增路徑僅是在 res.ok + json.success + data.bootId 全部成立後插入 handleBootIdCheck；失敗分支完全沿用 M8-7 的 recordFailure，polling → overlay 行為不變。
• WebSocket server:shutdown-imminent（L225-249）、restart 10 s defer（L232-242）、visibility change probe（L279-292）、cleanup（L303-323）全部不動。
• Active retry 3 s / normal 10 s 切換邏輯（L186-201）不動，boot-id 比對只發生在「成功取得 response」那條路徑，不影響 retry 節奏。
• retryServerHealth（L328-358，M8-7 既有函式）被 patch 成走 handleBootIdCheck，對 overlay 的「手動 retry 按鈕」呼叫者透明。

既有測試（M8-7、model-store、lib/api）全數通過 → 零回歸。

E. Test 品質

Store tests（system-store.test.ts）— 4 個

1. first call 情境 → 驗 return + bootId 被設（L24-28）✅
2. 相同 bootId → 驗 'match' + store 不動（L30-35）✅
3. 不同 bootId → 驗 'mismatch' + store 保留舊值（L37-43）✅
4. Reset 後再呼叫 → 重新 'first'，模擬 reload 後情境（L45-52）✅

TDD §12 要求的三路徑 + 邊界全數覆蓋。beforeEach（L14-22）確實 reset 所有欄位，隔離性 OK。

Hook tests（use-shutdown-watcher.test.ts）— 5 個

1. 首次 fetch → setBootId + markOnline，無 reload（L65-74）✅
2. 相同 id fetch → markOnline，無 reload（L76-85）✅
3. 異 id fetch → window.location.reload 被呼叫 + guard 寫入 + store 不更新（L87-99）✅
4. Loop guard 命中 → 不 reload + store 對齊新 id + markOnline（L101-113）✅
5. Fetch 失敗 → recordFailure + 無 reload（L115-124）✅

mockFetchBootId helper 乾淨，vi.stubGlobal('fetch', ...) 正確。Object.defineProperty(window, 'location', ...) 是 jsdom 下替換 location.reload 的標準做法（jsdom 的 window.location 不可直接賦值）。afterEach L61-63 vi.restoreAllMocks() 搭配 beforeEach 清除 sessionStorage + 重置 store，測試間無耦合。

Suggestion：SSR 情境（typeof window === 'undefined'）走 false path（L95-98），目前 hook test 不覆蓋。因為 jsdom 下必定有 window，要另寫 node env test。優先級低，M8-9 可接受不補。

Minor 2：task brief 提到「sessionStorage 失敗（私密視窗）：catch 後仍 reload」的邊界 case，但 hook test 5 個中沒有直接模擬 sessionStorage.setItem throw 的情境。實作正確（L100-115 catch fall through 到 reload），但無 regression guard。建議補一個 test：sessionStorage.setItem 用 vi.spyOn(Storage.prototype, 'setItem').mockImplementation(() => { throw new Error(); }) → 驗 reloadSpy 仍被呼叫。非阻擋性，可列入 M8-10 之後的測試補強清單。

F. Build / Test / Lint 結果

指令	結果
pnpm tsc --noEmit	✅ 零錯誤（無任何輸出）
pnpm test	✅ 4 test files / 19 tests 全綠（含本次新增 4+5）
pnpm lint（全 repo）	⚠️ 16 問題全部為 pre-existing（use-server-health.ts、use-websocket.ts 等檔），M8-9 改動的 4 個檔零 error / 零 warning
pnpm build	✅ Compiled successfully 5.5s / 12 頁 SSG 全數 prerender 完成

既有 repo lint 問題不在本次審查範疇，不阻擋 M8-9。

G. SSR 相容

• 'use client' directive 在 L1 正確標記。
• window、sessionStorage、window.location.reload 全部在 useEffect（L155）或 handleBootIdCheck 函式內使用，且 L95-98 有 typeof window === 'undefined' guard（雙重保險，因為 hook 只會在 client 執行但 retryServerHealth 可能被 server component 誤呼）。
• retryServerHealth 走同一 handleBootIdCheck，SSR guard 也保護它。
• Next.js pnpm build 的 SSG prerender 12 頁全部成功，證實 build 階段不會觸發 window is not defined。

H. 完整 flow 驗證（讀 code 推論）

場景 1：Restart Server

1. Wails notifyShutdownImminent(reason=restart) → WS broadcast。
2. Browser tab 收到（use-shutdown-watcher.ts:225-249）→ restartDeferTimer 啟動 10 s defer（L234-241），不立刻 forceOffline。
3. 每 10 s（normal）/ 3 s（active-retry）poll /api/system/boot-id。Restart 期間 server 約 3 s 起步，fetch 連續 ECONNREFUSED → recordFailure 累計 → consecutiveFailures ≥ 2 → subscribe callback（L186-201）自動切 active-retry。
4. Server re-spawn → 新 boot-id。
5. 下一次 pollOnce → res.ok + json.success + data.bootId → handleBootIdCheck：store 裡舊 bootId ≠ 新 bootId → mismatch → guard 寫入 → window.location.reload()。
6. 新 tab 載入 → Zustand store reset bootId = null → 首次 poll → 'first' → setBootId + markOnline → 正常運作。

路徑正確 ✅

場景 2：Quit

1. Wails notifyShutdownImminent(reason=quit) → WS broadcast。
2. Browser tab 收到 → mapReason('quit') → 'quit' → L245 forceOffline('quit') 立即執行（沒有 10 s defer，defer 只在 reason === 'restart' 分支，L232）。
3. Polling 持續失敗（server 整組關掉）→ overlay 顯示「請重開 app」。
4. 每次 poll fail → recordFailure，不進入 handleBootIdCheck（整個 L146 block 要 res.ok + success + data.bootId 才會進）。
5. Server 沒回來，reloadSpy 永不會被呼叫。

路徑正確，不會誤觸發 reload ✅

場景 3：網路 glitch

1. 單次 health check fail → recordFailure，consecutiveFailures = 1，尚未 ≥ 2 門檻 → 不 forceOffline、不 切模式。
2. 第二次失敗 → consecutiveFailures = 2 → subscribe callback 補上 forceOffline('healthcheck-failed')（L191-197）→ 切 active retry。
3. Active retry 3 s 後 → server 還在 → 拿到同一 boot-id → handleBootIdCheck 回 'match'（因為 store.bootId 沒被任何人改）→ L147 的 if (!shouldContinue) false → 往下到 L148 markOnline()（會同時 reset consecutiveFailures=0 + forcedOffline=false + offlineReason=null）→ subscribe callback 偵測到 shouldActiveRetry=false，下一次 polling tick 自動切回 normal 10 s。
4. reloadSpy 不會被呼叫。

路徑正確，不會誤 reload ✅

額外確認：Restart 路徑下，如果 boot-id 變化先於 restartDeferTimer 10 s 到期 → handleBootIdCheck 會直接 reload，restartDeferTimer 還在 running。useEffect cleanup（L312-315）會 clear timer；但 reload 觸發後頁面立刻卸載，timer 會被 jsdom / 瀏覽器自然清掉，無副作用。若 reload 被 SSR / guard skip（極端情境），restartDeferTimer 仍會 10 s 後執行，此時 forceOffline('restart') 的 guard 檢查 !s.serverOnline || consecutiveFailures >= FAILURE_THRESHOLD（L237）會判定為 false（guard skip 路徑裡 markOnline 已被呼叫）→ 不會誤顯示 overlay。健壯。

I. 問題清單

Critical

無。

Major

無。

Minor

#	檔案	行	問題	建議
1	frontend/src/hooks/use-shutdown-watcher.ts	113-115	sessionStorage try/catch 吞 error 無 log，異常發生時無法從 console 察覺	catch 內加 console.warn('[boot-id] sessionStorage unavailable, reload guard disabled')，不改 control flow
2	frontend/src/tests/hooks/use-shutdown-watcher.test.ts	—	無 test 覆蓋「sessionStorage.setItem throw → 仍 reload」邊界	用 vi.spyOn(Storage.prototype, 'setItem').mockImplementation(() => { throw new Error(); }) 補 1 個 test，驗 reloadSpy 仍呼叫 1 次

Suggestion

#	檔案	行	建議
1	frontend/src/hooks/use-shutdown-watcher.ts	95-98	SSR guard 分支（typeof window === 'undefined'）無對應 test；jsdom 下難模擬。可延後到專門的 SSR 測試環境補

J. 結論

M8-9 Boot-ID + tab 自動重連實作完整、流程正確、測試充分。

• Store action checkAndUpdateBootId 三路徑語意與 TDD §9.3 一致，mismatch 刻意不改 store 的設計與 reload-後-新-tab 重走 first 路徑完美配合。
• Helper handleBootIdCheck DRY 封裝 guard + reload，pollOnce / retryServerHealth 共用同一路徑。
• Reload loop guard（sessionStorage）在正常 / 異常 / 隱私視窗三種情境下都有正確 fall back，不會卡 loop。
• M8-7 既有邏輯（polling 模式切換、WebSocket、visibility、restart defer）全數不變，19 個 tests 全綠零回歸。
• 三個關鍵場景（Restart / Quit / glitch）讀 code 推論路徑全部正確，特別是 Quit 不會誤觸發 reload（handleBootIdCheck 進入條件嚴格）、glitch 同 bootId 會乾淨 recover。
• tsc / build / 改動檔 lint 全數 PASS；pre-existing lint 問題不在本次範疇。

結論：✅ 通過，不阻擋 M8-10。2 個 Minor 與 1 個 Suggestion 可視為技術債，建議列入 M8-10 之後的測試補強清單處理，非必修。