# 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 | 使用者 | 待確認 |