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:
jim800121chen 2026-03-08 01:10:17 +08:00
parent ff7dfb3562
commit 1eab9b7ceb

View File

@ -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 serverWindows 不含 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. 安全性考量