visionA/local-tool/.autoflow/05-implementation/review/m9-4.5-shutdown-integration-review.md

Reviewer Report — M9-4.5 Server SIGTERM + Wails OnBeforeClose Integration

審查日期：2026-05-25 範圍：8 個檔案、21 個新單元測試 結論：⚠️ 不阻擋 M9-5（核心邏輯與測試品質達標）、1 個 Major 建議在進 M9-5 前釐清（spec 對齊）、3 個 Minor + 4 個 Suggestion 可進 backlog 升 security：❌ 不需要（無 auth / secret / 第三方整合、攻擊面僅 loopback） 第 2 輪 backend：⚠️ 建議 1 輪修 Major-1（event 名 + force-close path 對齊 spec / TDD），但若決策維持實作不變，可直接補 TDD 修正紀錄、無需重派 backend。

---

TL;DR

• Correctness：核心 SIGTERM 路徑與 OnBeforeClose 路徑邏輯都正確。fail-open 設計（query 失敗時放行 Wails）合理、有雙層保護兜底。
• TDD §8.6 對齊：實作整體精神對齊、但事件命名與 spec 不一致（TDD 寫 firmware:shutdown-rejected、實作用 server:shutdown-pending）。Design §6a.5 / §6a.11 寫的 force-close 應該 SIGKILL bypass graceful、實作走 graceful 7+1s——實作其實更安全、但是直接違反 spec、需有人拍板（建議改 spec、不改 code）。
• 測試品質：6 + 7 + 8 = 21 個 test、覆蓋面好、有 -race 並發測。1 個 fakeLifecycle / fakeCloseGuardDeps 設計都乾淨。
• Concurrency：mu 保護完整、forceCloseAccepted race-free、broadcast hub 是 buffered 100、不會卡 shutdown goroutine。
• Security：HTTP target 寫死 127.0.0.1 ✓；payload 含 startTs（time.Time）走到 WS broadcast、屬時間戳洩漏、但 broadcast 範圍是同主機 browser tab、影響極低。

問題總數：Critical 0 / Major 1 / Minor 3 / Suggestion 4

---

審查範圍（8 檔）

#	檔案	角色	行數
1	server/main.go	server SIGTERM goroutine wiring	+30 行（preamble + helper call）
2	server/internal/firmware/shutdown.go	AwaitActiveTasksOrTimeout helper + 3 interfaces	154 行（新）
3	server/internal/firmware/shutdown_test.go	6 unit tests	258 行（新）
4	visiona-local/main.go	OnBeforeClose hook 註冊	+1 option + 註解
5	visiona-local/app.go	App 加 firmwareCloseGuard field + NewApp 初始化	+6 行
6	visiona-local/query_firmware_active_tasks.go	HTTP helper、fail-open	111 行（新）
7	visiona-local/query_firmware_active_tasks_test.go	7 unit tests	250 行（新）
8	visiona-local/firmware_close_guard.go	CloseGuard + OnBeforeClose + ConfirmForceClose	244 行（新）
9	visiona-local/firmware_close_guard_test.go	8 unit tests	280 行（新）

規格對照：.autoflow/04-architecture/v2/firmware-management.md §8.6.1–§8.6.5；.autoflow/03-design/v2/control-panel.md §6a。

---

TDD §8.6 對齊評估

TDD §8.6 條目	實作位置	對齊狀態
§8.6.1 SIGTERM → 檢查 HasActiveTask	main.go:333-348 + shutdown.go:122	✅
§8.6.1 broadcast 給 WS client	shutdown.go:137	⚠️ event 名不對（見 Major-1）
§8.6.1 等到 180s timeout	shutdown.go:82 + 145	✅ MaxShutdownWait=180s
§8.6.1 timeout 後強制走 shutdown	main.go:347-348（不論 clean 都 shutdownFn）	✅
§8.6.1 KL720 worst case 200s（type.go UpgradeTimeoutFor）	types.go:115-119 vs MaxShutdownWait=180s	⚠️ 數字不一致（見 Minor-2）
§8.6.2 OnBeforeClose 攔截	firmware_close_guard.go:208	✅
§8.6.2 query /api/firmware/active-tasks	query_firmware_active_tasks.go:70	✅
§8.6.2 emit app:firmware-in-progress	firmware_close_guard.go:36	✅ event 名對齊 §8.6.2
§8.6.2 第 6 點 force-close → kill -9 不可擋	implementation graceful path	⚠️ Design §6a.5 寫 SIGKILL bypass、實作走 graceful（見 Major-1）
§8.6.3 server/internal/firmware/service.go 新增 HasActiveTask	已在 M9-3 完成	✅
§8.6.3 main.go signal handler 整合	main.go:331-349	✅
§8.6.4 180s timeout 內卡死 → 強制 shutdown	shutdown.go:147-152 + main.go:347	✅

---

🟠 Major（建議修、不阻擋 M9-5）

Major-1：spec 與實作對 force-close 路徑 + WS event 命名不一致

兩個 spec / impl 不對齊問題、屬同一決策面、合併一條：

(a) WS event name 對不上

• TDD §8.6.1 line 581：「透過 WebSocket firmware:shutdown-rejected event broadcast 給所有訂閱者」、限定 firmware: room
• TDD §8.6.4：「event 命名 firmware:shutdown-rejected 限定 firmware: room、其他 room 不收」
• 實作（shutdown.go:66-77）：用 system room、event type server:shutdown-pending

實作的選擇其實更合理（system room 已存在 server:shutdown-imminent 配對、前端有 useShutdownWatcher hook 訂閱、不需要叫前端再去訂閱所有 firmware:<device> room）、但這是顯式違反 spec、需要文件補正。

(b) Force-close path 不一致

• Design §6a.5 line 392：「點擊 → Wails close handler 跳過 server graceful shutdown 流程、直接 kill server process（傳 SIGKILL）+ 關閉視窗」
• Design §6a.11 line 467：「控制台需呼叫 server force-shutdown IPC method（bypass graceful shutdown）、server 收到後直接送 SIGKILL 給 Python sidecar、不等 firmware task 完成」
• 實作（firmware_close_guard.go:226-243 ConfirmForceClose）：設旗標 → wailsRuntime.Quit(ctx) → OnBeforeClose 放行 → OnShutdown → ctrl.Stop()（既有 7+1s graceful）

實作的選擇比 spec 更保守 / 更安全——server 端 SIGTERM 收到後 firmware.AwaitActiveTasksOrTimeout 還會再等 180s（除非真的卡死才強制）。但這違反「使用者明確 FORCE 確認後立刻 kill」的設計意圖、會造成 UX 不一致（使用者打完 FORCE 又等 180s、會困惑）。

建議

請使用者 / Architect 拍板（兩個都建議改 spec、不改 code）：

1. WS event：把 TDD §8.6.1 / §8.6.4 改成 server:shutdown-pending 在 system room（對齊既有 R5-2 server:shutdown-imminent 配對）、補一行說明這跟 firmware:<device> progress room 區隔
2. Force-close path：把 Design §6a.5 / §6a.11 改成「graceful shutdown（server 端 firmware-aware 180s timeout 保護）」、刪掉「SIGKILL bypass」字眼。Code 註解（firmware_close_guard.go:225-229）已說明理由、寫得清楚、改 spec 採用實作的設計即可

或者反過來改 code 對齊 spec、但 reviewer 不建議——實作的設計更安全。

---

🟡 Minor

Minor-1：MaxShutdownWait 180s vs UpgradeTimeoutFor(KL720) 230s 不對齊

• shutdown.go:82 MaxShutdownWait = 180s
• types.go:115-119 UpgradeTimeoutFor(KL720) = 200s、service.go:159 又加 +30s margin → service-level ctx 是 230s

→ Wails 觸發 SIGTERM 時、AwaitActiveTasksOrTimeout 只等 180s 就強制走、service 層的 task 可能還有 50s 才結束。實作的註解（shutdown.go:18-21）已意識到：「給 180 秒 hard upper bound 是『Wails 視窗端的使用者體驗上限』」、但這個取捨會讓「KL720 升級到第 180s 還沒完成 → server 強制 shutdown → 在第 199s 才會完成的 task 被中斷」。

雖然走到這條 50s 窗口的機率很低（KL720 平均升級時間 << 200s）、但對齊 spec 應該設 240s（200s timeout + 30s margin + 10s buffer）。

建議：MaxShutdownWait 提高到 220s 或 240s、註解說明來源。

Minor-2：Second SIGTERM 不處理（buffer=1）

main.go:331-349:

quit := make(chan os.Signal, 1)
signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
go func() {
    sig := <-quit       // 只收一次
    ...
    _ = firmware.AwaitActiveTasksOrTimeout(...)  // 阻塞到 180s
    shutdownFn()
    os.Exit(0)
}()

使用者在 firmware task 中按 Ctrl+C → goroutine 開始等 180s → 使用者再按 Ctrl+C 想強制中止 → 第二個 signal 進 channel buffer → 沒人讀、什麼事都沒發生。OS 端用 kill -9 可繞過、但「按兩次 Ctrl+C」是 Unix 慣例（git rebase、docker exec 都這樣設計）。

建議：可選擇：

• (a) 啟動第二個 goroutine 監聽第二個 signal、收到後 os.Exit(1) 強制走（會 brick、但是使用者明確意圖）
• (b) 不處理、文件說明限制（M9-5 之前可接受）

shutdown.go 開頭註解（line 18-24）已寫「不主動 cancel task」的取捨、屬同一決策面——可不修、但建議在註解補一行說明「使用者第二次 Ctrl+C 不處理」。

Minor-3：WS broadcast payload 含 startTs (time.Time)

shutdown.go:137-141 broadcast tasks 直接帶 []*ActiveTaskInfo、types.go:106 StartTs time.Time 會序列化成 ISO8601 字串送到所有 system room 訂閱者。

洩漏：server 本機時間（無 secret 等級資訊、但屬「不該對 client 暴露的細節」）。Frontend 已有 elapsedMs 可用、startTs 是冗餘的。

建議：broadcast payload 過濾掉 startTs 欄位、或者在 broadcast 前轉成 minimal struct（taskId / deviceId / chip / direction / stage / elapsedMs / etaSeconds 七欄、跟 query_firmware_active_tasks.go:39-48 FirmwareActiveTaskSummary 對稱）。

Wails 端的 appCloseGuardDeps.EmitFirmwareInProgress（firmware_close_guard.go:143-160）已自行構造 map[string]interface{} 過濾掉 startTs、做對了——server 端 broadcast 應該同樣處理。

---

💡 Suggestion（非阻擋、進 backlog）

S-1：shutdown.go 三個 interface 設計取捨

3 個 interface（ShutdownNotifier / FirmwareLifecycle / ShutdownLogger）拆得乾淨、好測。但有過度抽象的疑慮——FirmwareLifecycle 只有 helper 用、production 唯一實作者是 *Service、改名為 *Service direct 反而更清楚。建議保留現狀（測試友善 > 過度抽象 trade-off 在這個尺度可接受），但日後若再加類似 helper、可考慮共用一個 ServiceSnapshot interface。

S-2：firmware_close_guard.go ConfirmForceClose 與 wailsRuntime.Quit 的 race

func (a *App) ConfirmForceClose() error {
    ...
    a.firmwareCloseGuard.ConfirmForceClose()  // 設 flag
    ...
    if a.ctx != nil {
        go wailsRuntime.Quit(a.ctx)  // 觸發 OnBeforeClose
    }
}

ConfirmForceClose 設 flag 後立刻 spawn goroutine call Quit、Quit 觸發 OnBeforeClose、OnBeforeClose 讀 flag——這條 chain 沒有顯式同步、依賴 mu 在 evaluateClose 內部讀的時候才會 sync 到。在 Go memory model 下、g.ConfirmForceClose() return 後 mu.Unlock 觸發 happens-before、後續 OnBeforeClose goroutine 進 consumeForceCloseAccepted 也會 mu.Lock 同步——race-free。test 用 N=100 並發跑 -race clean 也驗證了。

Suggestion：可考慮在 ConfirmForceClose 內部直接同步呼叫 wailsRuntime.Quit（不用 goroutine）、減少非必要 goroutine、但目前實作為避免 binding caller 阻塞、屬合理取捨。註解（line 239-241）說明清楚、保留現狀 OK。

S-3：query_firmware_active_tasks.go 1s timeout 是否會 false negative

註解（line 11-12）「1 秒 timeout：server 沒起來 / 卡死 / network error 全視為『無 active task』」。極端情境：server 在升級 KL720 firmware（Python sidecar 大量 IPC、Go server 整體負載暫時拉高）、/api/firmware/active-tasks handler 處理時間 > 1s → fail-open → 放行 close → server SIGTERM handler 接手（雙層保護）。

雙層保護下、Wails 這層 false negative 不會直接造成 brick。但會造成 UX 不一致：使用者看不到攔截 modal、以為「沒任務、可以正常關」、結果 server SIGTERM handler 又延遲 180s（顯示 server:shutdown-pending broadcast）。

Suggestion：1s 在 development env 夠（empty ListActiveTasks handler 應該 < 10ms）、production load 上若有問題再加 retry-once 或拉到 3s。不阻擋 M9-5。

S-4：fakeLifecycle.WaitForActiveTasks 不 sleep maxWait

shutdown_test.go:57-64 的 fakeLifecycle.WaitForActiveTasks 不真的等 maxWait 時間、直接 return waitResult。Test 3 的 MaxShutdownWait = 10ms defer 重置是為了測 real Service 的 Wait 路徑（test 6）、但 fakeLifecycle 自己其實沒用到 10ms——可在 fakeLifecycle 加個 waitDelay time.Duration 欄位讓 test 控制是否 sleep、會更模擬真實情境。不阻擋。

---

SIGTERM 流程逐步驗證（server 端）

步驟	觸發	預期行為	實作位置	驗證
1	OS 送 SIGTERM	quit channel 收到 sig	main.go:331-332	✅
2	goroutine 收 sig	log "Received signal..."	main.go:334-335	✅
3	呼 AwaitActiveTasksOrTimeout	進 helper	main.go:339-344	✅
4	helper 查 HasActiveTask	用 *Service 真實 impl	shutdown.go:122	✅
4a	沒 task → return true	log "no active firmware task"	shutdown.go:124-128	✅ Test 1
4b	有 task → 取 ActiveTaskInfo	snapshot copy	shutdown.go:131 + service.go:283	✅
5	broadcast pending	system room + 完整 task list	shutdown.go:136-141	⚠️ event name 不對 spec（Major-1）
6	RequestShutdown	set shutdownReq flag、新 task 拒絕	shutdown.go:143 + service.go:288-292	✅
7	WaitForActiveTasks(180s)	用 taskWg.Wait + select timeout	shutdown.go:145 + service.go:297-309	✅ Test 2/3
7a	task 結束 → return true	clean log	shutdown.go:146-148	✅ Test 2
7b	timeout → return false	warn log	shutdown.go:149-152	✅ Test 3
8	caller shutdownFn	inferenceSvc.StopAll + httpServer.Shutdown	main.go:347 → 276-287	✅
9	os.Exit(0)	process 結束	main.go:348	✅

timeout 路徑：第 7b → 第 8 → 第 9、不會卡死。✅

race 路徑：

• task 在 broadcast 與 WaitForActiveTasks 中間結束 → WaitForActiveTasks 立刻 return true（taskWg 計數歸零、close(done) 進 select） → 沒問題
• 新 task 在 broadcast 後但在 RequestShutdown 前進來 → 會建立成功（短暫 race window、屬可接受、SIGTERM 流程已在進行中、不會有實際使用者意圖）

---

Wails OnBeforeClose 流程逐步驗證

步驟	觸發	預期	實作位置	驗證
1	Wails close 動作	OnBeforeClose 被呼叫	main.go:38	✅
2	OnBeforeClose → evaluateClose	經 wrapping App.OnBeforeClose	firmware_close_guard.go:208-214	✅
3	檢查 forceCloseAccepted	已 confirm → return false 放行	firmware_close_guard.go:116-119	✅ Test 1
4	檢查 ServerPort	<=0 → return false	firmware_close_guard.go:121-126	✅ Test 2
5	queryFirmwareActiveTasks	HTTP GET 帶 1s timeout	query_firmware_active_tasks.go:70-111	✅ Test 3-7
5a	error → fail-open return false	log + 不擋	firmware_close_guard.go:130-134	✅ Test 3 (close_guard)
5b	hasActive=false → return false	log + 放行	firmware_close_guard.go:136-139	✅ Test 4
5c	hasActive=true → emit + return true	通知前端 modal	firmware_close_guard.go:141-161	✅ Test 5
6	前端「FORCE」確認 → ConfirmForceClose binding	設 flag + go wailsRuntime.Quit	firmware_close_guard.go:232-243	✅ Test 6
7	Quit 觸發、OnBeforeClose 又被叫	step 3 短路 return false 放行	firmware_close_guard.go:116-119	✅ Test 1 後續
8	shutdown(ctx)	走既有 ctrl.Stop graceful	app.go:341-381	✅（既有 R5-2、本次未動）

雙層保護驗證：Wails OnBeforeClose query 失敗（fail-open）放行 → ctrl.Stop → server 收 SIGTERM → server 端 AwaitActiveTasksOrTimeout 再擋 180s。✅ 雙層設計合理、容錯好。

---

21 個新測試品質

shutdown_test.go（6 tests）

Test	情境	品質
NoActiveTask	沒 task 立刻 return true	✅ 驗 hasActiveCalls / requestShutdown / waitForActive / notifier 都對
ActiveTaskFinishesCleanly	有 task、Wait return true	✅ 驗 broadcast room + payload schema（type / tasks key）
ActiveTaskTimeout	有 task、Wait timeout	✅ MaxShutdownWait reset / Warn 觸發
NilService	nil service 防呆	✅
NilNotifierAndLogger	nil 不 panic	✅ recover guard
RealServiceNoActive	真接 Service 整合	✅ 驗 wire-up 不踩 nil

漏掉的情境（非阻擋）：

• 連續兩次呼叫 AwaitActiveTasksOrTimeout（second SIGTERM 場景）
• ctx 被 cancel 的行為（目前 helper 收 ctx 但沒用、預留給未來）

query_firmware_active_tasks_test.go（7 tests）

Test	情境	品質
PortZero / PortNegative	port <= 0 防呆	✅
HasActiveWithTasks	server 正常回 + 完整解析	✅ 驗 7 個 task 欄位
HasActiveFalseNullTasks	tasks null → 轉空 slice	✅ 重要邊界（避 caller nil panic）
ServerError500	500 → fail-open	✅
Timeout	server 慢 → 100ms timeout 觸發	✅ + done 兜底防卡死
MalformedJSON	損毀 JSON → fail-open	✅
SuccessFalse	success=false 視為 error	✅

很完整。1 個微小盲點：沒測「response.data 完全缺欄位」（如 hasActive 缺）、但 zero-value 是 false 也安全。

firmware_close_guard_test.go（8 tests）

Test	情境	品質
ForceAccepted	flag 短路 + 旗標清掉	✅
ServerNotRunning	port=0 不擋	✅
QueryError_FailOpen	error → 放行	✅
NoActiveTask	hasActive=false → 放行	✅
HasActive_PreventAndEmit	完整驗 emit payload schema	✅ taskId / deviceName / chip / stage / etaSeconds 都驗
ConfirmForceClose_SetsAndConsumes	flag toggle	✅
NilDeps	防呆	✅
ConcurrentAccess	N=100 -race	✅ 無 race assertion

很棒的測試品質：N=100 並發 + atomic counter、是少見的踏實寫法。

---

安全軸

項目	狀態
HTTP target 寫死 127.0.0.1（loopback only）	✅ query_firmware_active_tasks.go:81
沒 token / secret 流動	✅
WS broadcast 不含 PII / secret	✅（含 startTs 屬時間戳、見 Minor-3）
Force-close 動作有二次確認	✅ Design §6a.5 + 實作 ConfirmForceClose binding（前端嚴格 === 比對「FORCE」）
firmware_close_guard.mu 保護 forceCloseAccepted	✅
-race clean 證明	✅ Test 8

無需升 Security Auditor。

---

Concurrency 評估

server 端 SIGTERM goroutine（main.go:333-349）

• 單 goroutine、不會雙觸發（除非有人 spawn 多個 signal.Notify、這份 main.go 沒有）✅
• 跟 firmwareSvc.taskWg 互動：WaitForActiveTasks 內部用 taskWg.Wait 加 select、taskWg.Add 在 UpgradeFirmware 內 ✅
• 跟 shutdownReq flag 互動：RWMutex 保護、UpgradeFirmware 讀、RequestShutdown 寫 ✅

Wails 端 ConfirmForceClose 並發

• firmwareCloseGuard.mu 保護 forceCloseAccepted ✅
• go wailsRuntime.Quit(ctx) 是 binding goroutine fire-and-forget、不影響 Wails main thread ✅
• OnBeforeClose 被 Wails main thread 呼叫、consumeForceCloseAccepted mu.Lock 同步 ✅

Hub broadcast 不卡 shutdown

• h.broadcast channel buffer = 100（hub.go:56）✅ 不會卡 SIGTERM goroutine
• hub.Run goroutine 在 server lifetime 一直跑、不會在 shutdown 開始前先死、broadcast 至少能進 channel ✅

無 race / 無 deadlock 風險。

---

是否阻擋 M9-5

❌ 不阻擋。

理由：

• 核心 SIGTERM 流程正確、測試覆蓋好、有雙層保護兜底
• 1 個 Major（spec 不對齊）屬文件層面、不是功能 bug
• 3 個 Minor / 4 個 Suggestion 都不影響「韌體進行中關閉視窗」的核心保護

M9-5 可以開始。建議在 M9-5 開始之前、由 Architect 補 TDD §8.6.1 / §8.6.4 + Design §6a.5 / §6a.11 對齊實作（5 分鐘工作量）、避免後續 frontend 接 event 時拿錯 event name。

---

是否升 security agent

❌ 不需要。

不觸發 §3.4 升級條件：無 auth / session / 密碼變更、無新對外 API（active-tasks 已在 M9-3 上線、本任務不新增）、無第三方整合、無 PII / 金融資料、沒看不懂的安全決策。攻擊面僅 loopback HTTP + 同主機 WebSocket、屬本機 IPC 層級。

---

是否需 backend 第 2 輪

⚠️ 建議 1 輪、但範圍很小。

選項：

• A. 改 spec、不改 code（推薦）：請 Architect / Design agent 更新 TDD §8.6.1 / §8.6.4 + Design §6a.5 / §6a.11、改文件不改 code。0.2 人天。
• B. 改 code 對齊 spec：把 ShutdownEventTypePending 改 firmware:shutdown-rejected、broadcast 從 system room 改 firmware: room；ConfirmForceClose 改成直接 SIGKILL server process。0.5 人天、但會讓設計變糟。
• C. 不修、留 backlog：將 Major-1 標入 progress.md「待人工介入」清單。

reviewer 建議 A。

Minor-1 / Minor-3 可一併處理（提高 MaxShutdownWait 到 220s、broadcast payload 過濾 startTs）、約 0.1 人天。

---

優點（給 backend agent 正面回饋）

1. interface 拆分乾淨：ShutdownNotifier / FirmwareLifecycle / ShutdownLogger 三 interface 都是 minimum surface、測試友善、production wire-up 簡單。雖然有 S-1 略過度抽象的疑慮、但拆得很好。
2. 雙層保護設計合理：Wails query fail-open → server SIGTERM handler 雙層擋、註解（query_firmware_active_tasks.go:17-20）清楚說明取捨理由。這比硬擋 Wails 體驗好太多。
3. 註解品質極高：shutdown.go 開頭 24 行設計取捨 + 為什麼 180s 不是 200s、firmware_close_guard.go 行 1-24 解釋為什麼用 Wails event 而不是 native dialog、ConfirmForceClose binding goroutine 解釋（line 219-229）——全部都是「下一個工程師讀到不會踩坑」級的註解。
4. N=100 -race 並發測試：firmware_close_guard_test.go:251-280 用 atomic counter 跑 N=100、認真寫 race-free 驗證、不是隨便糊個 test 交差。難得。
5. fail-open 設計守則一致：query / OnBeforeClose / AwaitActiveTasksOrTimeout 全部 nil-safe、所有路徑都假設「最壞情況不該 panic、不該卡死 Wails」、防禦性編碼到位。
6. Test 6（RealServiceNoActive）整合驗 wire-up：不只用 fake、還跑一個真接 Service 驗 helper 整條走通——這種「最後一公里」的驗證很多 reviewer 會嫌麻煩跳過、backend 沒跳。

---

Needs Investigation

無。所有 5 軸 + 測試軸都有明確判斷文字、沒有 Reviewer 看不懂或不確定的地方。

---

Verification 自評

A 層（每個 review 必做）

• ✅ R-A1：5 軸 + 測試軸全跑過、每軸 ≥ 20 字實質判斷
  • Correctness：見「SIGTERM 流程逐步驗證」+「OnBeforeClose 流程逐步驗證」兩節 ≈ 800 字
  • Readability：見「優點」§3 註解品質評估
  • Architecture：見 S-1 三 interface 取捨評估
  • Security：見「安全軸」表 + Minor-3 startTs 評估
  • Performance：見「Concurrency 評估」hub buffer 100 + S-3 1s timeout 評估
  • 測試：見「21 個新測試品質」三表
• ✅ R-A2：TDD §8.6 對照表填滿 12 條、每條都有實作位置 + 對齊狀態
• ✅ R-A3：Major-1 附 spec line number（TDD §8.6.1 line 581、§8.6.4、Design §6a.5 line 392、§6a.11 line 467）+ 實作位置 + 具體建議；Minor-1/2/3 同
• ✅ R-A4：「優點」段 6 條、不是空著
• ✅ R-A5：「Needs investigation」段明示「無」
• ✅ R-A6：通用 6 條
  • No silent failures：✅ 已查、所有 error path 都有 log + 適當處理
  • No dead code：✅ ctx 預留參數有明確註解（shutdown.go:112）、不算 dead code
  • No hardcoded secrets：✅
  • No unsafe HTML/SQL：✅ 無此情況（純 Go 後端 + HTTP loopback）
  • Doc 同步：⚠️ Major-1 — TDD / Design 文件未同步實作改動
  • Working tree clean（被審 commit）：✅（依使用者派任務、認定 backend 已 commit）

B 層（milestone 必驗）

本次審 8 檔（單一 milestone task、跨 server + Wails）、屬 milestone 範圍、跑 B 層：

• ✅ R-B1：跨檔案一致性（server FirmwareActiveTaskSummary 欄位 vs Wails 對應 struct）已比對、欄位對齊
• ✅ R-B2：8 檔全覆蓋、無漏審
• ✅ R-B3：最大新檔 280 行（firmware_close_guard_test.go）< 500 行閾值、無大改動
• N/A R-B4：本次純程式碼審查、不涉文件三方互審

C 層（PR/合併前最終 review）

不適用——本次是 task 完成審查、非 PR 最終 review。M9-5 完成後彙整時可跑。

---

結論彙報：

• 報告路徑：.autoflow/05-implementation/review/m9-4.5-shutdown-integration-review.md
• Critical: 0 / Major: 1 / Minor: 3 / Suggestion: 4
• 阻擋 M9-5：❌ 不阻擋
• 升 security：❌ 不需要
• 第 2 輪 backend：⚠️ 建議 1 輪、範圍小（建議走 A 選項：改 spec 不改 code）