jim800121chen
c54f16fca0
local-tool/: visionA-local desktop app
- M1: Wails shell + Go server + Next.js UI + Mock mode (macOS dmg ready)
- M2: i18n (zh-TW/en) + Settings 4-tab refactor
- M3: Embedded Python 3.12 runtime (python-build-standalone) + KneronPLUS wheels
- M4: Windows Inno Setup script (build on Windows runner)
- M5: Linux AppImage script + udev rule (build on Linux runner)
- M6: ffmpeg (GPL, pending legal review) + yt-dlp bundled
- Lifecycle: watchServer health check, fatal native dialog,
Wails IPC raise endpoint, stale process cleanup
.autoflow/: full PRD / Design Spec / Architecture / Testing docs
(4 rounds tri-party discussion + cross review)
.github/workflows/: macOS / Windows / Linux build CI
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
114 lines
6.5 KiB
Markdown
114 lines
6.5 KiB
Markdown
# TDD — visionA-local（技術設計文件索引）
|
||
|
||
> 技術設計文件（Technical Design Document）索引。各章節一句話摘要 + 子檔連結。
|
||
> 作者：Architect Agent ｜ 版本：1.0 ｜ 日期：2026-04-11
|
||
|
||
---
|
||
|
||
## 0. 文件地圖
|
||
|
||
| 章節 | 一句話摘要 | 子檔 |
|
||
|------|----------|------|
|
||
| §1 架構總覽 | 三層程序模型（Wails + Go server + Python sidecar）的完整技術說明 | [`architecture-overview.md`](./architecture-overview.md) |
|
||
| §2 依賴內嵌 | Python runtime（雙策略）、KneronPLUS、ffmpeg、yt-dlp、.nef 模型的內嵌細節 | [`dependency-bundling.md`](./dependency-bundling.md) |
|
||
| §3 打包 | 三平台的 installer 建置流程與檔案格式 | [`packaging.md`](./packaging.md) |
|
||
| §4 Build Pipeline | Makefile、vendor 目錄、CI 策略 | [`build-pipeline.md`](./build-pipeline.md) |
|
||
| §5 API 端點 | 保留 / 刪除 / 新增的 HTTP + WebSocket API 清單 | [`api-endpoints.md`](./api-endpoints.md) |
|
||
| §6 程式碼沿用計畫 | 從 edge-ai-platform 哪些檔案複製 / 改寫 / 新寫 | [`code-reuse-plan.md`](./code-reuse-plan.md) |
|
||
| §7 要刪除的程式碼 | 要砍掉的目錄、檔案、import 清單 | [`removed-code.md`](./removed-code.md) |
|
||
| §8 生命週期 | Single-instance、port 衝突處理、程序啟停（tray 已砍） | [`tray-and-lifecycle.md`](./tray-and-lifecycle.md) |
|
||
| §9 多語系 | 中英雙語（前端 + Wails）實作策略 | [`i18n.md`](./i18n.md) |
|
||
| §10 風險與緩解 | P0-P2 風險清單與處理計畫 | [`risks-and-mitigations.md`](./risks-and-mitigations.md) |
|
||
| §11 Plan B（R9 contingency） | 若 Kneron 不允許 .nef re-distribution 的線上下載方案 | [`plan-b-online-download.md`](./plan-b-online-download.md) |
|
||
|
||
---
|
||
|
||
## 1. 技術堆疊總表
|
||
|
||
| 層 | 技術 | 版本 | 來源 |
|
||
|----|------|------|------|
|
||
| GUI 殼 | Wails v2 | v2.9+ | 沿用 edge-ai-platform/installer |
|
||
| 後端 | Go + Gin | Go 1.22 / Gin 1.10 | 沿用 edge-ai-platform/server |
|
||
| 前端 | Next.js + React + TypeScript | Next 16 / React 19 | 沿用 edge-ai-platform/frontend |
|
||
| UI 套件 | shadcn + Radix + Tailwind | latest | 沿用 |
|
||
| 狀態管理 | Zustand | latest | 沿用 |
|
||
| 硬體 SDK | KneronPLUS | 2.0.0 (mac) / 3.1.2 (linux/win) | edge-ai-platform/installer/wheels |
|
||
| Python runtime | python-build-standalone | cpython-3.12.9 | astral-sh GitHub |
|
||
| Python 依賴 | numpy / opencv-python-headless / pyusb | 最新穩定 | PyPI（離線 wheel cache） |
|
||
| 影像處理 | ffmpeg（LGPL static） | 7.1 | evermeet.cx / BtbN / johnvansickle |
|
||
| YouTube 下載 | yt-dlp（standalone exe） | latest | yt-dlp GitHub |
|
||
| Logger | 自研 `pkg/logger`（含 WebSocket broadcaster） | - | 沿用 |
|
||
|
||
## 2. 主要資料結構（沿用 edge-ai-platform）
|
||
|
||
詳見各 package 的 Go struct 定義。以下只列索引：
|
||
|
||
- `model.Model` — 模型 metadata（見 `server/internal/model/`）
|
||
- `device.Device` — 裝置狀態（見 `server/internal/device/`）
|
||
- `camera.Pipeline` — 相機串流 pipeline（見 `server/internal/camera/`）
|
||
- `inference.Session` — 推論 session（見 `server/internal/inference/`）
|
||
- `config.Config` — **需改寫**，見 [`code-reuse-plan.md`](./code-reuse-plan.md) §3.3
|
||
|
||
## 3. 主要資料流
|
||
|
||
見 [`architecture-overview.md`](./architecture-overview.md) §3（三個代表性情境：首次啟動、連 USB 裝置、關閉應用）
|
||
|
||
## 4. 安全性
|
||
|
||
| 面向 | 處理 |
|
||
|------|-----|
|
||
| 網路 | 只 bind `127.0.0.1`，不對外 | 沿用原專案 |
|
||
| Auth | 無（單機單人使用）| 原本的 `/auth/token` 砍掉 |
|
||
| 輸入驗證 | Gin handler 的 struct binding + validator | 沿用 |
|
||
| 檔案上傳 | 副檔名白名單 + 大小限制 | 沿用 |
|
||
| USB 存取 | 依賴 OS driver 層（macOS IOUSB / Linux udev / Windows WinUSB） | 沿用 |
|
||
| 敏感資料 | 無（無帳密、無 token、無遙測）| 使用者決策 |
|
||
|
||
## 5. 效能目標（對齊 PRD + 第四輪決策）
|
||
|
||
> **重要：目標與上限分欄**。開發團隊應以「目標」欄為設計意圖，「上限」欄為不可超過的硬門檻。不要把上限欄當目標做，否則會吃掉緩衝空間。
|
||
|
||
| 指標 | 目標 | 上限 | 備註 |
|
||
|------|------|------|------|
|
||
| 冷啟時間（Wails 啟動 → Dashboard） | ≤ 3s | ≤ 5s | 首次包含 WebView 建立；回訪由 WebView cache 加速 |
|
||
| 首次推論時間（app 啟動 → Mock 第一幀） | ≤ 15s | ≤ 30s | R4-7：分為回訪 15s / 首次 30s 兩級 |
|
||
| 首次安裝時間（雙擊安裝檔 → Dashboard） | ≤ 3 分鐘 | ≤ 5 分鐘 | R4-4：Windows 首次安裝 WinUSB driver 額外 +30s |
|
||
| Mock 模式 idle CPU | ≤ 3% | ≤ 5% | 前提：Mock 模式完全不 spawn Python sidecar |
|
||
| Mock 模式 idle RAM | ≤ 450 MB | ≤ 600 MB | R4-4：含 Wails + Go server + WebView Next.js，不含 Python sidecar（Mock 不啟 Python） |
|
||
| 真實推論 FPS | 依 Kneron 裝置能力 | — | Go server 不應成為瓶頸 |
|
||
| MJPEG 串流延遲 | ≤ 150 ms（穩定後） | ≤ 250 ms（首次） | R4-2：首次建 pipeline 較高，穩定後降下；單位為 capture → UI overlay 的端到端 |
|
||
| 安裝檔大小（單平台） | ≤ 350 MB | ≤ 500 MB | 壓縮後 |
|
||
|
||
## 6. 可觀測性
|
||
|
||
- **Log**：統一透過 `pkg/logger`，寫到 stdout + 檔案 + WebSocket broadcaster。檔案位於各平台資料目錄的 `logs/` 子目錄：macOS `~/Library/Application Support/visiona-local/logs/`、Windows `%APPDATA%\visiona-local\logs\`、Linux `~/.local/share/visiona-local/logs/`
|
||
- **Metrics**：沿用 `/api/system/metrics`（CPU/RAM/裝置數）
|
||
- **Crash report**：**不做**（使用者決策 Q12），只留本地 log
|
||
- **Server log viewer**：前端 Settings 頁有 `server-log-viewer` 元件，沿用
|
||
|
||
## 7. 部署
|
||
|
||
N/A — 使用者直接下載 installer，本機執行。無 server-side deployment。
|
||
見 [`packaging.md`](./packaging.md) 與 [`build-pipeline.md`](./build-pipeline.md)。
|
||
|
||
## 8. 測試策略
|
||
|
||
| 層 | 工具 | 沿用 |
|
||
|----|------|-----|
|
||
| Go unit test | `go test` | 沿用 edge-ai-platform |
|
||
| Go integration（API） | `api_e2e_test.go` | 沿用但需刪除 cluster / relay 相關 case |
|
||
| 前端 unit | Vitest | 沿用 |
|
||
| 前端 e2e | Playwright（若原專案有） | 視情況沿用 |
|
||
| 安裝器 smoke test | 手動跑 installer（每平台一次） | 新增 |
|
||
| Python bridge test | 手動 + mock mode 驗證 | 沿用 |
|
||
|
||
**第一版不追求高覆蓋率**——內部工具 + MVP 階段。重點是 API 合約穩定與三平台 installer 能跑通。
|
||
|
||
## 9. 審閱紀錄
|
||
|
||
| 日期 | 審閱者 | 結論 |
|
||
|------|-------|------|
|
||
| 2026-04-11 | PM Agent | 待審 |
|
||
| 2026-04-11 | Design Agent | 待審 |
|
||
| 2026-04-11 | 使用者 | 待確認 |
|