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

Reviewer 審查 M8-5 兩個補丁（2026-04-15）

摘要

• 補丁 A（Stage 6 Manual CTA）：✅ 通過。manualMode 狀態機、enterManualMode 觸發、onManualModeChange pub-sub、stage 6 manual hint description、stage 5 skipped label、CTA pulse、dark / reduced-motion fallback 全部對齊 Design Spec v2.1 §4.1 §7。i18n 用既有 key 無新增。
• 補丁 B（ServerState + server:error payload）：✅ 通過。control-panel.js 匯出 6 個 lowercase 常數、data-state / dot class 不再 .toLowerCase()；app.js import STATE_ERROR、server:error 讀 payload.reason 並附註 Go source of truth 註解。
• 是否阻擋 M8-10：不阻擋。M8-5 原 Reviewer 的 2 Critical 已完全修復，M8-4b Reviewer 提醒的 stage 6 manual CTA UX 也補齊。全部 4 個改過的 JS node --check 乾淨；wails build -s -m -skipbindings 產出 build/bin/visiona-local.app（6.272s）。Minor 層級問題均為 Suggestion。

---

A. Stage 6 Manual CTA（補丁 A）

A1. manualMode 狀態機

檢查項	結果	備註
enterManualMode() 在 stage=5 status="skipped" 時觸發	✅	startup-panel.js:182-184「if (n === 5 && stages[5].status === 'skipped') enterManualMode()」
manualMode toggle 正確	✅	startup-panel.js:16 module-scope flag；enterManualMode L216 幂等（若已進入直接 return）→ L217 setTrue；hideStartupPanel L163-166 reset；stage 6 completed L187-193 reset
manualModeListeners pub-sub	✅	L18 Set；L19-22 onManualModeChange(fn) 回傳 unsubscribe；L23-27 emitManualMode try/catch 保護 listener 拋錯
hideStartupPanel reset 清 manualHint	✅	L160-162 重置 stages[1..6]（含 manualHint: false），L163-166 若 manualMode===true 則 toggle 並 emit false

A2. stage 6 manualHint description

檢查項	結果	備註
paintStageRow 偵測 stage===6 && manualHint	✅	startup-panel.js:88-89「else if (stage === 6 && st.manualHint) labelSecondary.textContent = t('startup.stage.6.manualHint')」
stage===5 && status==='skipped' → startup.stage.5.skipped.label	✅	L86-87
markStageTimeout manualMode + stage 6 時忽略 soft timeout	✅	L242「if (n === 6 && stages[6].manualHint) return」；與 Design §4.1「不套 20 秒 retry hint」一致
paintStageRow 的 slow hint 也避開 manual hint	✅	L107「if (st.slow && st.status === 'running' && !st.manualHint)」雙重保險

A3. i18n key 使用

檢查項	結果	備註
無新增 key	✅	全用既有 3 個：startup.stage.6.manualHint / startup.stage.5.skipped.label / startup.status.skipped
既有 key 存在雙語	✅	i18n.js:61,64,69（zh-TW）+ i18n.js:140,143,148（en），與 Design §7 表格對齊

A4. CTA pulse

檢查項	結果	備註
setPrimaryCTAPulse(true/false) add/remove class	✅	control-panel.js:105-113；取 #btn-open-browser 後 classList.add/remove('pulse-cta')
app.js 訂閱 onManualModeChange → 驅動 pulse	✅	app.js:32-33 import；app.js:42 import onManualModeChange；app.js:134-136 init step 11 onManualModeChange((enabled) => setPrimaryCTAPulse(enabled))
.pulse-cta CSS 正確	✅	style.css:205-216 @keyframes ctaPulse 1.8s ease-in-out infinite，box-shadow 0px→8px 漸散（符合 material-style 脈衝）
:not([disabled]) 選擇器	✅	style.css:205 .btn.pulse-cta:not([disabled]) — 按鈕 disabled 時不做動畫（避免 stage 5 skipped 但 server state 還沒到 running 的極短窗口裡 pulse disabled 按鈕）
dark mode 變體	✅	style.css:217-222 @media (prefers-color-scheme: dark) 覆寫 @keyframes ctaPulse 為較亮藍（rgba(59,130,246,0.65)）
prefers-reduced-motion fallback	✅	style.css:224-230 動畫關閉，改 outline: 2px solid var(--focus-ring)；L676-682 全域 override 會把 animation-duration 壓成 0.01ms，兩層不衝突，outline 仍會套用

A5. stage 6 completed 離開 manualMode

路徑驗證（親自追 Go → 前端）：

1. 使用者按 Open in Browser → OpenInBrowser binding → 瀏覽器載入 Web UI
2. 瀏覽器 WebSocket 連線 → Hub register channel → hub.go:112 writeStartupSentinel（sync.Once）
3. startup_pipeline.go:313-318 watcher 每秒檢查 sentinel 檔案 → CompleteStage(6)
4. startup_pipeline.go:230-251 emitProgress goroutine → Wails event startup:progress {stage:6, status:"completed"}
5. app.js:318-324 EventsOn('startup:progress') → updateStage(ev)
6. startup-panel.js:187-193 條件 n === 6 && (status === 'completed' || 'done') → manualMode=false + stages[6].manualHint=false + emitManualMode(false)
7. app.js:134-136 listener → setPrimaryCTAPulse(false) → classList.remove
8. 接著 startup_pipeline.go:223 markReady emit startup:ready → app.js:331 → hideStartupPanel()（二次保險）

✅ 路徑完整，pulse 在 stage 6 completed 瞬間即停，不等 panel unmount。

A6. Race 保護

情境 1：stage 5 skipped 先到，stage 6 running 後到

• L182-184 enterManualMode() → L219 stages[6].status === 'pending' 為 true → 主動設 running + startedAt
• 之後 Go 層送 stage 6 running，L175 stages[n].status = ev.status 覆蓋為 running（同值），不動 manualHint（L175 只改 status）
• paintStageRow(6) 仍看到 st.manualHint === true → 顯示 manual hint description ✅

情境 2：stage 6 running 先到，stage 5 skipped 後到

• 第一個 event：updateStage L175 stages[6].status = 'running'；L182 條件 n===5 && ... 不符合 → 不 enter manual mode
• 第二個 event：updateStage L175 stages[5].status = 'skipped'；L182 條件符合 → enterManualMode()；L219 stages[6].status === 'pending' 為 false（已是 running），不重設 startedAt，但 L223 stages[6].manualHint = true + L225 stages[6].slow = false + L226 paint → manual hint 顯示 ✅

兩種 race 都正確。

情境 3：stage 6 running 與 stage 5 skipped 極短時間內雙飛

• Go emitProgress 用 goroutine（startup_pipeline.go:230-251），理論上可能亂序；但 Wails EventsEmit 單一 JS runtime 接收為序列 queue，兩個 callback 接續執行，兩種順序均已驗證 ✅

A 小結

補丁 A 全部通過。manualMode 狀態機、pub-sub、stage 5/6 label 分流、CTA pulse、dark/reduced-motion 完整對齊 Design Spec v2.1 §4.1 §7，無 Critical / Major 問題。

---

B. Critical 修復（補丁 B）

B1. ServerState lowercase 統一

檢查項	結果	備註
control-panel.js 常數全 lowercase	✅	L7-12 定義 6 個常數（idle / starting / running / stopping / stopped / error），對齊 Go server_control.go:44-49
匯出給其他檔 import	✅	L7-12 每行都 export const；app.js:33 import { STATE_ERROR } from './control-panel.js'
內部比對用常數	✅	L20 STATE_IDLE；L26-34 switch case；L55 STATE_RUNNING；L82-86 primary controls
grep 無 PascalCase state 殘留	✅	僅 i18n.js:87,89,92,145 是顯示用 label value（'Idle' / 'Running' / 'Stopped'），非 state 比對，符合預期
control-panel.js 無 .toLowerCase()	✅	grep 零匹配

B2. data-state 屬性 + dot class

檢查項	結果	備註
不再 .toLowerCase()	✅	L21 root.setAttribute('data-state', s)（既然 s 已是 lowercase）；L22 dot.className = 'status-dot state-' + s
CSS 選擇器匹配	✅	快速檢查 style.css 的 .status-dot.state-* 與 [data-state="*"] 應全 lowercase；原 M8-5 Review 已驗過 dot 顯示正常（因當時有 .toLowerCase() hack），現在直接用 lowercase 字串，匹配相同且更乾淨

B3. server:error payload.reason

檢查項	結果	備註
改為 payload.reason	✅	app.js:301-304「if (payload && payload.reason) showErrorBanner(payload.reason)」
註解說明 Go source of truth	✅	L302「Go 端 server_control.go L184/L361 emit payload key 為 "reason"（不是 "error"）」
親自核對 Go 端	✅	server_control.go:184-186 確認 emit map[string]any{"reason": err.Error()}；未查 L361 但題目有註明

B4. Stage 5 skipped 情境驗證（補丁 A + B 交集 — 最關鍵懸念）

M8-5 原 Reviewer 最重要的懸而未決：Open in Browser 按鈕在 stage 5 skipped 時是否 enabled？

親自追 Go 程式碼：

1. 冷啟動 → app.go:235 a.ctrl.Start()
2. server_control.go:200 c.setState(ServerStateRunning, "") — Start 成功後立刻進入 running
3. Start 返回 → app.go:242 a.runStartupStage5()
4. app.go:253-255 AutoOpenBrowser=false → a.startupPipeline.SkipStage(5)

關鍵結論：當前端收到 startup:progress stage=5 status=skipped 時，ctrl.state 早已是 running（在 Step 2 已 setState）。

前端路徑：

• Wails server:state-change event 早一步送過 state='running' payload
• app.js:300 handleServerStatus → updatePrimaryControls → L82 openBtn.disabled = s !== STATE_RUNNING = 'running' !== 'running' = false
• Open in Browser 按鈕 enabled ✅
• 同時 startup:progress stage=5 skipped 觸發 enterManualMode → pulse 啟動
• 使用者看到彈出 panel + pulse 的 Open in Browser 按鈕可點 → 體驗順暢

.pulse-cta:not([disabled]) 選擇器也守住了邊界：即便極短時間窗口內 state 尚未到 running，disabled 按鈕也不會誤 pulse（視覺正確）。

補丁 B 修復 Critical 1 之後，stage 5 skipped → stage 6 manual CTA 的完整流程成立。 B4 通過。

---

C. 親跑驗證

== app.js ==           node --check OK
== control-panel.js == node --check OK
== startup-panel.js == node --check OK
== i18n.js ==          node --check OK
== style.css ==        (CSS, 跳過 node --check)

wails build -s -m -skipbindings
→ Compiling application: Done.
→ Packaging application: Done.
→ Self-signing application: Done.
→ Built build/bin/visiona-local.app (6.272s)

wails build 成功產出 .app，證明 go:embed all:frontend 正確吃進 4 個修改後的前端檔。

PascalCase state 殘留 grep：

visiona-local/frontend/i18n.js:87:  'control.status.idle': 'Idle',
visiona-local/frontend/i18n.js:89:  'control.status.running': 'Running',
visiona-local/frontend/i18n.js:92:  'control.status.stopped': 'Stopped',
visiona-local/frontend/i18n.js:145: 'startup.status.running': 'Running',

僅 4 處，全是 i18n label 顯示文字（非 state 比對），符合題目允許範圍。

.toLowerCase() 殘留 grep：control-panel.js 零匹配。

---

D. 問題清單

Critical（阻擋 M8-10）

（無）

Major

（無）

Minor

#	檔案:行	問題描述	建議
m-1	style.css:209-222 dark variant 覆寫 @keyframes ctaPulse	把整個 keyframes 重新定義，而非用 CSS variable。若未來想調 pulse 顏色需改兩處。	可改用 --pulse-color CSS var + dark :root override，但目前做法對齊既有 pattern（status-dot color variant 也是同法），不強制修。
m-2	startup-panel.js:182-184 前端主動 enter manual mode	依 Design §4.1 流程，Go 端理論上會先送 stage 5 skipped 再送 stage 6 running，但前端這裡先行 paint 並設 stages[6].running，若 Go 層之後沒送 stage 6 running（例如 pipeline 異常），manualHint 狀態永遠停在「前端自造」的 running。目前 M8-4b 是必定送的，故不會發生；屬防禦性建議。	可在 emitManualMode(true) 後加一個 watchdog（30 秒沒收到 stage 6 running 則 console.warn），但非必要。
m-3	既有 Minor 沿用 — log-panel.js footer lines 英文硬編	M8-5 原 review 的 m-1，本輪補丁 A/B 未涵蓋，仍然存在	保留為 M8-10 前收斂的項目

Suggestion

#	檔案	建議
s-1	startup-panel.js:16-27 pub-sub	若未來 manualMode 觀察者增多，可考慮用 EventTarget 替代 Set，標準 API 且可 dispatchEvent。目前單一訂閱者，Set 已足夠。
s-2	control-panel.js:7-12 常數	可再多 export 一個 SERVER_STATES frozen object 方便 iterate（如 Object.values(SERVER_STATES) 做 sanity check），非必要。
s-3	style.css:205 selector	.btn.pulse-cta:not([disabled])) 選擇器優雅，但如果未來 Open in Browser 按鈕換 class 名稱（非 .btn），pulse 會失效。可改成單純 .pulse-cta:not([disabled])。

---

E. 結論

審查結果：✅ 通過（第 1 輪）

• 補丁 A（Stage 6 Manual CTA）：對齊 Design Spec v2.1 §4.1 §7，manualMode 狀態機完整、pub-sub 安全、i18n 用既有 key 雙語齊全、CTA pulse 加 dark / reduced-motion fallback。M8-4b Reviewer 提醒的「AutoOpenBrowser=false 時 panel 永遠不淡出」UX 已補齊。
• 補丁 B（ServerState + server:error payload）：M8-5 原 Critical 1 / 2 完全修復。control-panel.js 全 lowercase 對齊 Go server_control.go:44-49；app.js 讀 payload.reason 對齊 server_control.go:184。
• 跨補丁交集 B4：親自追 Go → 前端路徑驗證 stage 5 skipped 時 ctrl.state 已是 running，Open in Browser 按鈕 enabled，pulse 引導使用者點擊，流程順暢。
• 親跑：4 個 JS node --check 全過；wails build -s -m -skipbindings 成功產出 build/bin/visiona-local.app（6.272s）。

不阻擋 M8-10。建議 Orchestrator 將本輪補丁 A/B 視為 M8-5 的最終交付。M8-5 原 review 的 Minor m-1~m-8 仍在 backlog（不阻擋），可由 M8-10 整理階段一併收斂。

給 Frontend Agent 的正面回饋：

• manualMode pub-sub 用 Set + try/catch 保護 listener，簡潔且防禦性佳
• enterManualMode / hideStartupPanel 兩處 reset 對稱，狀態機閉環
• .pulse-cta:not([disabled]) 選擇器與 Go state 時序巧妙搭配（避免 pulse 空按鈕）
• CSS dark mode 與 prefers-reduced-motion 兩層無障礙 fallback 齊全
• B 補丁用 module-level 常數取代字面量 PascalCase，未來再也不會發生大小寫 drift