# visionA-local — Design Doc（索引）

> 本檔案為設計文件總索引，各章節摘要 + 子檔連結。
> 專案：visionA-local（edge-ai-platform 的本地桌面版）
> Bundle ID：`com.innovedus.visiona-local`
> 作者：Architect Agent ｜ 版本：1.0 ｜ 日期：2026-04-11

---

## 0. 文件地圖

| 面向 | 檔案 |
|------|------|
| 架構總覽與程序模型 | [`architecture-overview.md`](./architecture-overview.md) |
| 依賴內嵌策略（Python / Kneron / ffmpeg / yt-dlp / 模型） | [`dependency-bundling.md`](./dependency-bundling.md) |
| 打包流程（mac dmg / win Inno Setup / linux AppImage） | [`packaging.md`](./packaging.md) |
| Build pipeline / Makefile / CI 骨架 | [`build-pipeline.md`](./build-pipeline.md) |
| 生命週期（port 衝突、single-instance；tray 已砍） | [`tray-and-lifecycle.md`](./tray-and-lifecycle.md) |
| 多語系（中英雙語） | [`i18n.md`](./i18n.md) |
| 風險與緩解（R1–R12） | [`risks-and-mitigations.md`](./risks-and-mitigations.md) |
| Plan B（R9 contingency，線上下載預置模型） | [`plan-b-online-download.md`](./plan-b-online-download.md) |
| 技術設計文件（索引） | [`TDD.md`](./TDD.md) |

TDD 底下還拆分：
- [`api-endpoints.md`](./api-endpoints.md) — 保留 / 刪除 / 新增的 API 清單
- [`code-reuse-plan.md`](./code-reuse-plan.md) — 從 edge-ai-platform 哪些檔案複製、改寫、新寫
- [`removed-code.md`](./removed-code.md) — 要砍掉的目錄 / 檔案 / import 清單

---

## 1. 產品定位（一段話）

visionA-local 是 `edge-ai-platform` 的**單機桌面版**，把原本需要 EC2 + Docker + nginx 的 web 工具改造為「雙擊即用」的 GUI 應用，目標體驗對標 Docker Desktop / Ollama。所有依賴（Python runtime、KneronPLUS SDK、ffmpeg、yt-dlp、預置 .nef 模型）**全部內嵌**在安裝檔中，使用者機器**完全不需要**預先安裝任何東西，且**完全離線**即可運作。支援 **macOS 14/15、Windows 10/11、Ubuntu 22.04/24.04**，僅 x86_64（Apple Silicon 用 Rosetta）。

---

## 2. 高層架構（一句話 + 圖）

**Wails 殼（Go + WebView）→ spawn → Go server 子行程（Gin + 內嵌 Next.js）→ spawn → Python sidecar（KneronPLUS bridge）**

```
┌──────────────────────────────────────────────────┐
│  visionA-local  (Wails app — 使用者看到的殼)       │
│  ├─ 首次執行：安裝精靈（解壓 payload → 建 venv）   │
│  ├─ 一般模式：Dashboard（關閉視窗 = 結束程式）     │
│  └─ 內嵌 WebView → http://127.0.0.1:3721/        │
│                          │                        │
│                 spawn    ▼                        │
│  ┌────────────────────────────────────────┐       │
│  │ visiona-local-server (Go binary)        │       │
│  │  - Gin HTTP + WebSocket                 │       │
│  │  - go:embed Next.js 靜態檔              │       │
│  │  - REST: /api/devices, /api/models, ... │       │
│  │  - WS:   /ws/devices, /ws/server-logs   │       │
│  │           │                              │       │
│  │  spawn    ▼                              │       │
│  │  ┌─────────────────────────────────┐    │       │
│  │  │ python3 kneron_bridge.py         │    │       │
│  │  │  - KneronPLUS SDK                │    │       │
│  │  │  - 推論 / 裝置列舉 / 模型載入    │    │       │
│  │  └─────────────────────────────────┘    │       │
│  │  spawn (on demand)                       │       │
│  │  ┌─────────────────────────────────┐    │       │
│  │  │ ffmpeg / yt-dlp                  │    │       │
│  │  └─────────────────────────────────┘    │       │
│  └────────────────────────────────────────┘       │
└──────────────────────────────────────────────────┘
```

詳見 [`architecture-overview.md`](./architecture-overview.md)。

---

## 3. 最重要的 5 個架構決策（摘要）

| # | 決策 | 為什麼 |
|---|------|-------|
| **D1** | **三層程序模型**（Wails 殼 + Go server 子行程 + Python sidecar），**不**合併成 single binary | Go server 要長時間跑、UI 殼可獨立崩潰重啟；KneronPLUS 必須用真的 Python interpreter；`installer/app.go` 已驗證此模型可行（894 行成熟程式碼） |
| **D2** | **Python runtime 雙策略**：主策略 A = 內嵌 [python-build-standalone](https://github.com/astral-sh/python-build-standalone)（完全離線）；備策略 B = 偵測系統 `python3` 作為 fallback / 開發模式 | 使用者決策：要完全離線，但要保留 fallback。A 確保第一次執行就能跑（符合「一鍵安裝」），B 用在 `--dev` 模式與 standalone runtime 壞掉時的救援 |
| **D3** | **完全放棄程式碼簽章**：macOS 用 ad-hoc sign、Windows 無 Authenticode、Linux AppImage 無簽章 | 使用者決定不買憑證，接受 Gatekeeper / SmartScreen 警告。但**必須**寫清楚首次啟動 workaround 文件（見 [`packaging.md`](./packaging.md) §6） |
| **D4** | **x86_64 only**，三平台都不做 ARM / Universal Binary | 使用者是 Intel Mac；目標受眾也是內部 FAE + 客戶 demo 機，多為 x86_64。Apple Silicon 走 Rosetta 2。這大幅簡化 build pipeline（不用 `lipo`、不用雙架構 wheel） |
| **D5** | **預置模型全部打包**（~73MB），**不做** auto-update、**不收** telemetry | 符合「完全離線、零踩坑」原則。auto-update 對內部工具不值得投入（見 R6），且每次升級都會放 SmartScreen 警告重新觸發 |

---

## 4. 程式碼來源策略（摘要）

新專案 `local_tool/` 從零建立，但可以自由從 `edge-ai-platform/` 取用程式碼：

- **直接複製（~60% 程式碼）**：`installer/`、`server/internal/{api,camera,config,deps,device,driver,inference,model}`、`server/scripts/kneron_bridge.py`、`server/data/`、`server/pkg/logger`
- **改寫（~20%）**：`server/main.go`（移除 cluster / tunnel / relay）、`server/internal/api/router.go`（刪 cluster routes）、`server/internal/config/config.go`（刪 relay / gitea flags）、`installer/app.go`（改名 + 加入 Python runtime 雙策略）、`frontend/`（刪 cluster / relay UI）
- **新寫（~20%）**：Python runtime 偵測與 fallback 邏輯、i18n 系統、新版 Makefile / build 腳本、Inno Setup 腳本、AppImage 腳本
- **刪除**：`server/internal/{cluster,tunnel,update}`、`server/cmd/relay-server`、`server/pkg/hwid`、`docker/`、`scripts/deploy-*.sh`、`server/scripts/firmware/` + `update_kl720_firmware.py`（flash 砍掉）

詳見 [`code-reuse-plan.md`](./code-reuse-plan.md) 與 [`removed-code.md`](./removed-code.md)。

---

## 5. 第一個 Milestone 範圍建議（M1：End-to-End Skeleton）

**目標：從零起一個可以在 macOS 跑通的最小可行版本。其他平台與功能後續 milestone 處理。**

| # | 任務 | 說明 | 預估大小 |
|---|------|------|---------|
| M1-1 | 建立 repo 骨架 | `local_tool/` 目錄結構 + go.mod + Makefile 骨架 | S |
| M1-2 | 複製 server core | 從 edge-ai-platform 複製 `server/internal/{api,camera,config,deps,device,model,inference}` + `pkg/logger` | S |
| M1-3 | 清理 main.go | 改寫 `server/main.go`：移除 cluster / tunnel / relay / hwid / GiteaURL | M |
| M1-4 | 清理 config.go | 砍 relay / tunnel / gitea / GUIMode 相關 flags | S |
| M1-5 | 清理 router.go | 刪除 `/api/clusters/*`、`/ws/clusters/*`、`/auth/token` | S |
| M1-6 | 複製 frontend | 複製 `frontend/` 進 local_tool | S |
| M1-7 | **清理前端 UI**（Q-C=C2） | **M1 必做**：刪除 `src/app/clusters/`、`src/app/workspace/cluster/`、`src/components/cluster/`、`relay-token-sync.tsx`、`lib/api/{clusters,tunnel,update}.ts`；修改 sidebar（移除 Clusters 導航項）、Dashboard（移除 cluster 卡片）、Settings（移除 relay / cluster 區塊）；最終 `pnpm build` 通過且 UI 乾淨、沒有殘留的 cluster / relay / tunnel 入口 | M |
| M1-8 | Go server 本地 build | `make build` 產出 `visiona-local-server`（含 embedded Next.js），可直接 `./visiona-local-server` 跑起來 | S |
| M1-9 | 複製 installer shell | 從 `installer/` 複製 `app.go` + `main.go` + `embed.go` + platform_*.go，改名為 `visiona-local` | M |
| M1-10 | 改寫 installer | 移除 relay/dashboard 欄位、加入 Python runtime 雙策略的**空殼**（先走 B — 系統 Python） | M |
| M1-11 | payload 打包 | `make payload-macos`：把 `dist/visiona-local-server` + `data/` + `scripts/` 塞進 `visiona-local/payload/` | S |
| M1-12 | macOS installer build | `wails build` → `.app` → ad-hoc sign → 手動打包 dmg（dmgbuild） | M |
| M1-13 | End-to-end 驗證 | 全新 mac 上雙擊 .dmg → 裝起來 → Mock 模式看到 3 台假裝置跑推論，且 UI 完全沒有 cluster / relay / tunnel 入口 | M |

**M1 不做：** Python runtime 內嵌（策略 A）、Windows、Linux、打包最佳化、i18n、新 Logo、yt-dlp 內嵌。
**M1 必做（與前一版差異）：** 前端清理已從 M2 提前到 M1（使用者決策 Q-C=C2），tray 整條從計畫中移除（使用者決策 Q-A=A3）。

**M1 產出物：** macOS x86_64 `.dmg`，可在全新機器上（只要系統有 python3）跑通 Mock 模式，且前端 UI 已清乾淨。

### 後續 milestone 建議（M2~M6 概覽）

- **M2**：i18n 中英切換 + Settings 分頁調整（前端 cluster / relay UI 清理已於 M1 完成；tray 已砍）
- **M3**：Python runtime 策略 A（內嵌 python-build-standalone）+ KneronPLUS wheel 離線安裝
- **M4**：Windows Inno Setup + WinUSB driver 安裝
- **M5**：Ubuntu AppImage + udev rules
- **M6**：ffmpeg / yt-dlp 內嵌 + 完整依賴離線化 + 打包最佳化

---

## 6. 與 PRD / 設計規格的對應

- PRD US-1（第一次安裝 < 3 分鐘）→ 見 [`packaging.md`](./packaging.md) §3（首次啟動解壓流程）
- PRD US-2（Mock 模式零門檻試玩）→ 已內建於 `deviceMgr` 的 `mockMode` flag，沿用
- PRD US-3（插 USB 裝置自動偵測）→ 見 [`dependency-bundling.md`](./dependency-bundling.md) §2（KneronPLUS wheel + driver）
- Design 生命週期（關閉視窗 = 結束、single-instance）→ 見 [`tray-and-lifecycle.md`](./tray-and-lifecycle.md)（lifecycle 章節）
- Design 中英雙語 → 見 [`i18n.md`](./i18n.md)

---

## 7. 審閱紀錄

| 日期 | 審閱者 | 結論 |
|------|-------|------|
| 2026-04-11 | PM Agent | 待審 |
| 2026-04-11 | Design Agent | 待審 |
| 2026-04-11 | 使用者 | 待確認 |