diff --git a/docs/TDD.md b/docs/TDD.md index 7b04f9b..fb03db2 100644 --- a/docs/TDD.md +++ b/docs/TDD.md @@ -2158,6 +2158,33 @@ builds: # Windows: NSIS 包裝成 Setup.exe ``` +**替代架構方案:Go HTTP + 嵌入式 Web UI(備選)** + +若未來需要在 macOS 上 cross-compile Windows/Linux installer(避免依賴 CI 或目標平台機器),可考慮將 Wails v2 改為 Go HTTP server + 嵌入式 Web UI 架構: + +| 項目 | Wails v2(現行) | Go HTTP(備選) | +|------|-----------------|----------------| +| GUI 引擎 | 系統 WebView2(原生視窗) | 系統瀏覽器(自動開啟 `http://127.0.0.1:PORT`) | +| Cross-compile | 不支援(需目標平台 build) | 支援(`GOOS=windows CGO_ENABLED=0 go build`) | +| 原生對話框 | 支援(BrowseDirectory) | 不支援(改用文字輸入) | +| 進度推送 | Wails Events | SSE (Server-Sent Events) | +| 前端改動 | — | ~60 行(Wails binding → `fetch()` + `EventSource`) | +| 後端改動 | — | ~80 行(加 HTTP handlers + SSE channel) | +| 外部依賴 | Wails v2 + WebView2 | 零(純 Go 標準庫 `net/http` + `embed`) | +| 產出格式 | macOS: `.app` / Windows: `.exe` | 全平台: CLI binary(開瀏覽器) | + +遷移時的 API 對照表: + +| Wails 呼叫 | HTTP API | +|------------|----------| +| `window.go.main.Installer.GetSystemInfo()` | `GET /api/system-info` | +| `window.go.main.Installer.StartInstall(cfg)` | `POST /api/install` | +| `window.go.main.Installer.DetectHardware()` | `GET /api/detect-hardware` | +| `window.runtime.EventsOn('install:progress', cb)` | `new EventSource('/api/events')` | +| `wailsRuntime.EventsEmit(ctx, event, data)` | SSE channel push | + +此方案的主要優勢是可在單一平台(如 macOS)同時 `go build` 產出三個平台的 installer binary,不需要 CI 或目標平台機器。主要 trade-off 是失去原生視窗體驗和目錄選擇器對話框。 + #### 8.5.15 多裝置叢集推論(F19 — Cluster Inference) | 前端元件 | 後端模組 | 說明 | @@ -3178,6 +3205,62 @@ scripts/ [INFO] [OPTIONAL] python3: Python 3.12.3 ``` +### 11.7 Windows Installer Build 指南 + +**前置需求(在 Windows 上安裝一次即可):** + +1. **Go 1.23+**:https://go.dev/dl/ +2. **Node.js 20+**:https://nodejs.org/ +3. **pnpm**:`npm install -g pnpm` +4. **Wails CLI**:`go install github.com/wailsapp/wails/v2/cmd/wails@latest` +5. **WebView2 Runtime**(Windows 10/11 通常已內建) + +**Build 步驟(PowerShell):** + +```powershell +# 1. Clone repo +git clone https://gitea.innovedus.com/warrenchen/web_academy_prototype.git +cd web_academy_prototype\edge-ai-platform + +# 2. Build frontend +cd frontend +pnpm install --frozen-lockfile +pnpm build +xcopy /E /I /Y out ..\server\web\out +cd .. + +# 3. Build server(Windows 不含 tray) +cd server +$env:CGO_ENABLED="0" +go build -tags notray -ldflags="-s -w" -o ..\dist\edge-ai-server.exe main.go +cd .. + +# 4. Stage installer payload +Remove-Item -Recurse -Force installer\payload -ErrorAction SilentlyContinue +New-Item -ItemType Directory -Force -Path installer\payload\data\nef\kl520 +New-Item -ItemType Directory -Force -Path installer\payload\data\nef\kl720 +New-Item -ItemType Directory -Force -Path installer\payload\scripts\firmware\KL520 +New-Item -ItemType Directory -Force -Path installer\payload\scripts\firmware\KL720 +Copy-Item dist\edge-ai-server.exe installer\payload\ +Copy-Item server\data\models.json installer\payload\data\ +Copy-Item server\data\nef\kl520\*.nef installer\payload\data\nef\kl520\ +Copy-Item server\data\nef\kl720\*.nef installer\payload\data\nef\kl720\ +Copy-Item server\scripts\kneron_bridge.py installer\payload\scripts\ +Copy-Item server\scripts\requirements.txt installer\payload\scripts\ +Copy-Item server\scripts\update_kl720_firmware.py installer\payload\scripts\ +Copy-Item scripts\kneron_detect.py installer\payload\scripts\ +Copy-Item server\scripts\firmware\KL520\*.bin installer\payload\scripts\firmware\KL520\ +Copy-Item server\scripts\firmware\KL720\*.bin installer\payload\scripts\firmware\KL720\ + +# 5. Build Windows installer +cd installer +wails build -clean + +# 產出:installer\build\bin\EdgeAI-Installer.exe +``` + +**也可使用 GitHub Actions CI 自動 build**(參考 `.github/workflows/build-installer.yaml`)。 + --- ## 12. 安全性考量