diff --git a/docs/PRD-Integrated.md b/docs/PRD-Integrated.md index 45d2ccc..de291ec 100644 --- a/docs/PRD-Integrated.md +++ b/docs/PRD-Integrated.md @@ -1199,6 +1199,31 @@ Kneron Dongle Arduino 開發板 非 Kneron 晶片 | **無攝影機行為** | Camera tab 自動 disabled、預設切換至 Image tab、顯示「未偵測到攝影機」提示訊息 | | **有攝影機行為** | 維持原有攝影機推論功能不變 | +#### F16 — 跨平台安裝與分發 + +| 項目 | 規格 | +|------|------| +| **概述** | 提供一行指令安裝體驗,涵蓋 binary 下載、環境設定、硬體偵測,支援 macOS 與 Windows | +| **macOS/Linux 安裝** | `curl -fsSL https://gitea.innovedus.com/.../install.sh \| bash`,自動偵測 OS + 架構(darwin/linux + amd64/arm64) | +| **Windows 安裝** | `irm https://gitea.innovedus.com/.../install.ps1 \| iex`,自動下載 zip、解壓、加入 PATH | +| **安裝步驟** | 4 步驟自動化:(1) 下載 binary + 資料檔 (2) 安裝 USB 驅動(libusb)(3) 建立 Python venv + pyusb (4) 檢查環境 + 偵測硬體 | +| **安裝目錄** | macOS: `~/.edge-ai-platform/`、Windows: `%LOCALAPPDATA%\EdgeAIPlatform` | +| **解除安裝** | macOS: `rm -rf ~/.edge-ai-platform && sudo rm -f /usr/local/bin/edge-ai-server`、Windows: 刪除目錄 + 移除 PATH | +| **啟動依賴檢查** | Server 啟動時自動檢查 ffmpeg、yt-dlp、python3,缺少時顯示對應平台的安裝指引 | +| **GoReleaser 打包** | 跨平台 archive 自動產出(darwin amd64/arm64 tar.gz、windows amd64 zip),含 binary + data + scripts | +| **Kneron 硬體偵測** | 安裝完成時自動偵測 USB Kneron 裝置(KL520/KL720/KL730),使用 pyusb | + +#### F17 — 圖形化安裝與解除安裝程式(規劃中) + +| 項目 | 規格 | +|------|------| +| **概述** | 提供非技術人員可使用的桌面 GUI 安裝精靈,雙擊即可安裝或解除安裝 | +| **目標平台** | macOS (.dmg) + Windows (.exe installer) | +| **技術方案** | macOS: DMG + .app bundle 包裝、Windows: NSIS 安裝精靈 | +| **安裝精靈畫面** | 歡迎頁 → 安裝路徑選擇 → 可選元件(Python venv / Kneron driver)→ 安裝進度 → 完成 | +| **解除安裝** | macOS: .app 內含解除安裝選項、Windows: 控制台「新增或移除程式」標準流程 | +| **狀態** | 規劃中,待 CLI 安裝穩定後實作 | + --- ## B5. 功能路線圖(Post-MVP) @@ -1385,4 +1410,4 @@ Phase 3 — 進階功能(長期差異化) --- -*文件版本:v2.3 | 日期:2026-02-24 | 狀態:更新中* +*文件版本:v2.4 | 日期:2026-02-28 | 狀態:更新中* diff --git a/docs/TDD.md b/docs/TDD.md index 273caab..ea7c7c6 100644 --- a/docs/TDD.md +++ b/docs/TDD.md @@ -1585,6 +1585,65 @@ workspace 載入 → fetchCameras() → GET /api/camera/list **Hydration 安全:** 使用 `useHydrated()` hook 確保 `disabled` 屬性在 SSR 時為 `false`(與 `Tabs value="camera"` 一致),hydration 完成後才根據 cameras 列表設定 disabled 狀態。 +#### 8.5.12 跨平台安裝與分發(F16) + +| 安裝腳本 | 後端模組 | 配置檔 | +|---------|---------|--------| +| `scripts/install.sh`(macOS/Linux) | `internal/deps/checker.go` | `.goreleaser.yaml` | +| `scripts/install.ps1`(Windows) | `server/main.go`(baseDir) | `Makefile`(release targets) | +| `scripts/setup-kneron.sh`(獨立硬體設定) | — | — | +| `scripts/kneron_detect.py`(USB 偵測) | — | — | + +**安裝流程(macOS `install.sh`):** + +``` +curl | bash → detect_platform() → resolve_version() +→ Step 1/4: install_binary() — 下載 tar.gz + 解壓到 ~/.edge-ai-platform/ + symlink +→ Step 2/4: setup_libusb() — brew install libusb (macOS) / apt install (Linux) +→ Step 3/4: setup_python_venv() — python3 -m venv + pip install pyusb +→ Step 4/4: check_optional_deps() + detect_kneron_devices() +``` + +**安裝流程(Windows `install.ps1`):** + +``` +irm | iex → Invoke-RestMethod (resolve version) +→ Step 1/4: 下載 zip + Expand-Archive + 加入 PATH (User scope) +→ Step 2/4: 檢查 libusb-1.0.dll,提示 Zadig 安裝 +→ Step 3/4: python -m venv + pip install pyusb(同時嘗試 python3 / python) +→ Step 4/4: 檢查 ffmpeg/yt-dlp + kneron_detect.py +``` + +**Binary 路徑解析(`main.go` baseDir):** + +```go +func baseDir(devMode bool) string { + if devMode { return "." } // go run 用 CWD + exe, _ := os.Executable() + return filepath.Dir(exe) // production 用 binary 目錄 +} +// 3 處路徑:data/models.json, data/custom-models, scripts/kneron_bridge.py +``` + +**啟動依賴檢查(`internal/deps/checker.go`):** + +``` +Server 啟動 → deps.PrintStartupReport(logger) +→ 檢查 ffmpeg (exec.LookPath) → [OK] / [MISSING] +→ 檢查 yt-dlp → [OK] / [OPTIONAL] +→ 檢查 python3 → [OK] / [OPTIONAL] +``` + +**GoReleaser 打包產出:** + +| 平台 | 格式 | 檔名範例 | +|------|------|---------| +| macOS Intel | tar.gz | `edge-ai-platform_v0.1.0_darwin_amd64.tar.gz` | +| macOS Apple Silicon | tar.gz | `edge-ai-platform_v0.1.0_darwin_arm64.tar.gz` | +| Windows x64 | zip | `edge-ai-platform_v0.1.0_windows_amd64.zip` | + +每個 archive 含:`edge-ai-server` binary + `data/models.json` + `scripts/kneron_bridge.py` + `scripts/requirements.txt` + --- ## 9. 開發環境與工具鏈 @@ -1801,6 +1860,42 @@ clean: rm -rf dist/ frontend/out/ server/frontend/out/ ``` +### 11.5 安裝腳本 + +| 腳本 | 平台 | 安裝目錄 | 執行方式 | +|------|------|---------|---------| +| `scripts/install.sh` | macOS / Linux | `~/.edge-ai-platform/` | `curl -fsSL \| bash` | +| `scripts/install.ps1` | Windows | `%LOCALAPPDATA%\EdgeAIPlatform` | `irm \| iex` | +| `scripts/setup-kneron.sh` | macOS | 同上(venv 子目錄) | `bash scripts/setup-kneron.sh` | + +**安裝內容:** +1. Edge AI Server binary + data 檔案 +2. Python venv(`$INSTALL_DIR/venv`)+ pyusb +3. libusb 系統驅動(macOS: Homebrew / Linux: apt / Windows: Zadig 提示) +4. `/usr/local/bin/edge-ai-server` symlink(macOS)或 PATH 設定(Windows) + +**解除安裝:** +- macOS: `rm -rf ~/.edge-ai-platform && sudo rm -f /usr/local/bin/edge-ai-server` +- Windows: `Remove-Item -Recurse -Force "$env:LOCALAPPDATA\EdgeAIPlatform"` + 移除 PATH + +### 11.6 啟動依賴檢查 + +`internal/deps/checker.go` 在 Server 啟動時檢查外部工具: + +| 工具 | 等級 | 用途 | +|------|------|------| +| ffmpeg | Required(Camera 功能)| Camera 擷取、影片處理 | +| yt-dlp | Optional | YouTube URL 解析 | +| python3 | Optional | Kneron 硬體驅動(pyusb) | + +啟動輸出範例: +``` +[INFO] External dependency check: +[INFO] [OK] ffmpeg: ffmpeg version 7.1.1 +[INFO] [OPTIONAL] yt-dlp: not found — macOS: brew install yt-dlp | Windows: winget install yt-dlp +[INFO] [OPTIONAL] python3: Python 3.12.3 +``` + --- ## 12. 安全性考量 @@ -2082,4 +2177,4 @@ go.uber.org/zap // 結構化日誌 --- -*文件版本:v1.2 | 日期:2026-02-24 | 狀態:更新中* +*文件版本:v1.3 | 日期:2026-02-28 | 狀態:更新中*