jim800121/visionA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
visionA/local-tool/.autoflow/04-architecture/TDD.md
jim800121chen c54f16fca0 Initial commit: visionA monorepo with local-tool subproject 
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>
2026-04-11 22:10:38 +08:00

6.5 KiB
Raw Permalink Blame History

TDD — visionA-local（技術設計文件索引）

技術設計文件（Technical Design Document）索引。各章節一句話摘要 + 子檔連結。 作者：Architect Agent ｜ 版本：1.0 ｜ 日期：2026-04-11

0. 文件地圖

章節 一句話摘要 子檔
§1 架構總覽 三層程序模型（Wails + Go server + Python sidecar）的完整技術說明 architecture-overview.md
§2 依賴內嵌 Python runtime（雙策略）、KneronPLUS、ffmpeg、yt-dlp、.nef 模型的內嵌細節 dependency-bundling.md
§3 打包 三平台的 installer 建置流程與檔案格式 packaging.md
§4 Build Pipeline Makefile、vendor 目錄、CI 策略 build-pipeline.md
§5 API 端點 保留 / 刪除 / 新增的 HTTP + WebSocket API 清單 api-endpoints.md
§6 程式碼沿用計畫 從 edge-ai-platform 哪些檔案複製 / 改寫 / 新寫 code-reuse-plan.md
§7 要刪除的程式碼 要砍掉的目錄、檔案、import 清單 removed-code.md
§8 生命週期 Single-instance、port 衝突處理、程序啟停（tray 已砍） tray-and-lifecycle.md
§9 多語系 中英雙語（前端 + Wails）實作策略 i18n.md
§10 風險與緩解 P0-P2 風險清單與處理計畫 risks-and-mitigations.md
§11 Plan B（R9 contingency） 若 Kneron 不允許 .nef re-distribution 的線上下載方案 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 §3.3

3. 主要資料流

見 architecture-overview.md §3（三個代表性情境：首次啟動、連 USB 裝置、關閉應用）

4. 安全性

面向 處理
網路 只 bind 127.0.0.1，不對外
Auth 無（單機單人使用）
輸入驗證 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 與 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 使用者 待確認