visionA/local-tool/.autoflow/05-implementation/reviews/M1-10-review.md

M1-10 Review — 改寫 app.go + Python 雙策略空殼 + 生命週期邏輯

審查日期：2026-04-10 審查對象：/Users/jimchen/visionA/local-tool/visiona-local/（app.go 重寫、main.go、platform_*.go、embed.go 已刪） 任務描述：把原 installer 的肥胖 app.go 整份砍掉重寫，留下啟動殼層：single-instance、舊路徑遷移、port picking、Python 雙策略空殼、spawn server 子行程、graceful shutdown、前端 binding

結論：✅ 通過

全部檢查點過關。舊 installer（Relay / Gitea / Tray / Cluster / Firmware / auto-update / libusb / ffmpeg setup / installer wizard）完全清光；go build ./... 與 go vet ./... 都乾淨通過；三平台資料路徑與 tray-and-lifecycle.md §6 完全一致；Python 雙策略介面符合 dependency-bundling.md §1.5；生命週期邏輯（lock、migrate、port、start/stop、health）都照 TDD 落地。Backend 回報的五個 TODO 均屬 M1+/M2 範圍，不阻斷 M1-10 驗收。可以進入 M1-12（wails build + dmg）。

---

檢查清單

1. 平台資料路徑正確

平台	期望	實際（platform_*.go + appName）	狀態
macOS	~/Library/Application Support/visiona-local	filepath.Join(home, "Library", "Application Support", appName)（appName=visiona-local）	✅
Linux	$XDG_DATA_HOME/visiona-local → fallback ~/.local/share/visiona-local	XDG 檢查齊全，fallback 正確	✅
Windows	%APPDATA%\visiona-local	os.Getenv("APPDATA") + home fallback	✅

殘留舊名檢查：只在 oldDataDirCandidates() 中出現 .edge-ai-platform / visionA-local（駝峰）/ EdgeAIPlatform，全部為 migration source path，屬正確用法。active 路徑無殘留。✅

2. 被砍功能確實不在

grep 掃過整個 visiona-local/*.go：

被砍項目	出現位置	狀態
Relay	—	✅ 無
Gitea	—	✅ 無
Tray	只出現在檔頭註解提到「tray 已被整份刪除」	✅ 無實作
Cluster	—	✅ 無
Firmware	—	✅ 無
auto-update	只出現在檔頭「已刪除」註解	✅ 無實作
libusb	—	✅ 無
ffmpeg setup	—	✅ 無
installer wizard	只出現在檔頭「已刪除」註解	✅ 無實作
embed.go	檔案已刪	✅
Installer 型別	—	✅ 無

main.go 的 Bind: []interface{}{app} 只綁 App（NewApp()），不是舊的 Installer。✅

3. Python 雙策略介面

對照 dependency-bundling.md §1.5 決策樹：

檢查項	實作	狀態
PythonMode const	auto / bundled / system 三值齊全	✅
ensurePythonRuntime(auto) → 先 system fallback bundled	case PythonModeAuto 先 findSystemPython() 再 ensureBundledPython()	✅（符合 R4 決策：M1 先 system）
findSystemPython() 檢查 ≥ 3.10	isPython310OrNewer() 解析 Python 3.X.Y 並比對	✅
候選名單	python3.12 / 3.11 / 3.10 / python3 / python	✅
避開 Windows Store stub	strings.Contains(strings.ToLower(p), "windowsapps") → skip	✅
ensureBundledPython() 為 placeholder	直接回 "bundled python runtime not yet implemented (M2 feature)" 並附 TODO(M2) 註解指向 §1.3	✅

小建議（不阻擋）：findSystemPython() 沒有把 venv 建立 / wheel 安裝包進去，這是刻意的——M1 範圍只要「找到 interpreter 並把路徑傳給 server」，venv/wheels 留到 M2 由 bundled flow 一起處理。符合 M1 縮限範圍。

4. 生命週期邏輯

對照 tray-and-lifecycle.md：

檢查項	§	實作	狀態
acquireSingleInstance lock + PID check	§2.2	`O_CREATE	O_EXCL+ read PID +processAlive` + stale lock 清理
processAlive 跨平台	§2.4	Unix: proc.Signal(0)；Windows: tasklist /FI "PID eq ..."	✅
喚起既有 instance	§2.3	tryRaiseExistingInstance 讀 .ipc-port 並打 /api/system/health（M1+ 才改成 /ipc/raise，已有 TODO 註解）	✅（M1 可接受）
migrateOldDataDirs 在 lock 之前	§4.5	startup() 順序：MkdirAll → migrate → acquireSingleInstance	✅
遷移失敗不擋啟動	§4.5	continue + stderr 警告	✅
新路徑已存在不覆蓋	§4.5	檢查空目錄才 os.Remove + Rename	✅（比 TDD 稍寬鬆但更實用：允許剛 MkdirAll 的空資料夾被替換）
.migrated-from breadcrumb	§4.5	寫入 old\n + RFC3339 time	✅
pickPort(3721)	§3.2	從 defaultPreferredPort=3721 起跳，掃 20 個	✅
isOurStaleServer 偵測	§3.2	尚未實作，已註 TODO(M1+)	⚠️ 非阻斷（Backend 回報 known TODO）
startServer 流程	§4.1	ensurePython → pickPort → locateBinary → spawn → writeIPCPort → waitHealthy	✅
stopServer / ServerProcess.stop() SIGTERM → grace → SIGKILL	§4.1	shutdownGracePeriod=5s，超時後 Kill + <-done；Windows 分支直接 Kill	✅（TDD 寫 3s，實作 5s 更寬鬆，可接受）
waitHealthy(port, timeout)	§4.1	/api/system/health 輪詢，healthCheckTimeout=15s，300ms 間隔	✅（TDD 寫 10s，實作 15s 更寬鬆）
watchServer 每 10 秒輪詢	§4.2	尚未實作，Backend 回報 M1+	⚠️ 非阻斷
writeIPCPort	§2.3	寫到 dataDir/visiona-local.ipc-port	✅

timeout 差異說明：TDD 寫 3s grace / 10s health，實作用 5s / 15s。實作放寬不是縮緊，對正確性無影響；若 reviewer 嚴格要對齊 TDD 可留待 M1+ 統一調，不阻斷 M1-10。

5. go build ./... 重現

$ cd /Users/jimchen/visionA/local-tool/visiona-local && go build ./...
（無輸出）
$ go vet ./...
（無輸出）

✅ 乾淨通過，無 warning、無 unused import。

6. Wails binding 清單

main.go:

Bind: []interface{}{app}

app 為 *App（NewApp() 回傳）。可被前端呼叫的 exported methods：

• GetServerStatus() ServerStatus
• GetServerURL() string
• OpenBrowser(url string) error

未綁舊 Installer、未綁任何 installer wizard method。✅

main.go Title："visionA Local"（不是 Edge AI Platform Installer）。✅

7. 已知 TODO 清單（Backend 回報）

TODO	位置	M 版本	阻斷 M1-10？
ensureBundledPython	app.go:417	M2	❌ 不阻斷（M1 先 system）
/ipc/raise endpoint	app.go:550 TODO 註解	M1+	❌ 不阻斷
watchServer healthcheck 迴圈	—	M1+	❌ 不阻斷
isOurStaleServer + 自動 kill	app.go:452 TODO 註解	M1+	❌ 不阻斷
Fatal 原生對話框（目前只寫 stderr + event emit）	reportFatal	M1+	❌ 不阻斷

五個 TODO 全部都有明確註解或計畫位置，符合「M1 為最小可跑殼層」的定位。

---

發現的次要問題（不阻擋 M1-10）

1. startServer 的 error 分支對 mockMode 判斷位置怪異（app.go:205-208）：

   pyBin, pyMode, err := a.ensurePythonRuntime(a.pythonMode)
   if err != nil && !a.mockMode {
       return fmt.Errorf(...)
   }
   

   當 mockMode=true 且 python 失敗時，pyBin 會是空字串、pyMode 可能是 PythonModeAuto，後續 a.pythonBin = pyBin 會存空字串。邏輯上能跑（因為 mock 不需要 python），但會讓 GetServerStatus 回報空的 pythonBin，前端顯示可能怪。建議 M1+ 在 mock 分支明確記一個 sentinel value（如 "<mock>"）。

2. log 檔開啟錯誤被吞（app.go:243-246）：OpenFile 回傳 error 被丟棄，只有 nil check。如果 logsDir 磁碟滿或權限異常，會靜默退到 io.Discard。建議 M1+ 把 error 寫進 lastError。

3. locateServerBinary 的 candidates 順序在開發模式下，cwd/dist/ 在「與 exe 同目錄」之後。實務上 wails dev 會把 exe 放在 build/bin/，與 server binary 的實際位置（dist/）不同目錄，所以 candidate 3-4 會被用到。順序合理，但建議在 M1-12 build packaging 時驗證打包後 candidate 1 能命中。

4. migrateOldDataDirs 的 stderr 警告在 GUI app 情境下使用者看不到。搭配 #Fatal 原生對話框（M1+ TODO）一起改。

以上全部都是建議，不影響 M1-10 驗收。

---

結論與下一步

M1-10 通過 ✅，可以進入 M1-12（wails build + dmg packaging）。

下一階段的重點：

• M1-12 用 wails build 產生 macOS .app
• 驗證 locateServerBinary candidate 1（與 Wails exe 同目錄）能正確命中打包後的 visiona-local-server
• 產生 .dmg 並確認資料路徑在實機能正確建出

Backend 列出的 M1+ TODO（/ipc/raise、watchServer、isOurStaleServer、Fatal dialog）建議收在一個 M1-13 追蹤 issue，跟 M1-12 平行進行或接在其後。