docs: add F16 installation/distribution and F17 GUI installer specs
PRD v2.4: Added F16 (cross-platform install scripts, GoReleaser packaging, startup dependency check, Kneron hardware detection) and F17 (planned GUI installer wizard for non-technical users). TDD v1.3: Added 8.5.12 (F16 technical mapping with install flow diagrams), 11.5 (installation scripts documentation), 11.6 (startup dependency checker). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
parent
b28aec2589
commit
8c75a6508a
@ -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 | 狀態：更新中*
|
||||
|
||||
97
docs/TDD.md
97
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 <url> \| bash` |
|
||||
| `scripts/install.ps1` | Windows | `%LOCALAPPDATA%\EdgeAIPlatform` | `irm <url> \| 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 | 狀態：更新中*
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user