docs: add Go HTTP alternative architecture and Windows build guide to TDD
- Section 8.5.14: added alternative architecture comparison table (Wails v2 vs Go HTTP + embedded Web UI) for future cross-compile reference - Section 11.7: added step-by-step Windows installer build guide with PowerShell commands Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
parent
ff7dfb3562
commit
1eab9b7ceb
83
docs/TDD.md
83
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. 安全性考量
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user