# 專案進度 — visionA-local

## 目的：全新專案（從 edge-ai-platform 衍生的 local 版本）
## 當前階段：第二階段 — M2-M6 全部完成 ✅
## 當前狀態：使用者驗收中
## 最後更新:2026-04-11

## 🎉 M1 達成總結
- `dist/visiona-local.dmg` (70MB) 可雙擊安裝
- 全新環境下能 mount → 拖到任意位置 → 雙擊執行
- Mock 模式 server 子程序自動啟動（Bundle 內 `Resources/bin/visiona-local-server`）
- API endpoints 全部 200：health、info、devices、models
- 乾淨退出（SIGTERM → 5s → SIGKILL）
- 資料目錄：`~/Library/Application Support/visiona-local/`（lock + ipc-port + logs + custom-models）
- 第三輪 P0 bugs 修復：(1) APFS case-insensitive 自我毀滅、(2) `--python` flag 不存在、(3) `Resources/bin/` 路徑漏 `bin/` 子目錄

## M1 收尾（C 已完成）
- ✅ `GET /` 404 修復：Makefile 加 `build-embed` target，把 frontend/out → server/web/out 同步，再 build server binary。dmg 71MB 含完整主 UI（21KB 首頁 + Next.js chunks）

## M2-M6 任務清單（使用者選 Y：全包，macOS 為主）

### M2 — i18n + Settings 分頁調整
| # | 任務 | 狀態 |
|---|------|------|
| M2-1 | i18n 中英雙語切換 | ✅ |
| M2-2 | Settings 4 分頁重構 | ✅ |
| M2-3 | 清 cluster.* i18n keys | ✅ |
| M2-4 | sidebar Workspace 接 i18n | ✅ |
| M2-5 | rebuild dmg + smoke test | ✅（71MB, root+settings 200, server 從 bundle Resources 起） |

### M3 — Python runtime 策略 A 內嵌 + KneronPLUS wheel
| # | 任務 | 狀態 |
|---|------|------|
| M3-1 | vendor-python (PBS 3.12.9, 15MB) | ✅ |
| M3-2 | vendor-wheels (9 wheels, 71MB) | ✅ |
| M3-3 | ensureBundledPython() 實作 | ✅ |
| M3-4 | payload-macos stage python + wheels | ✅ |
| M3-5 | dylib codesign | ✅ 不需要（Gatekeeper 沒擋） |
| M3-6 | rebuild dmg + smoke test | ✅ 157MB, venv + 9 wheels + import kp 全通過 |

### M6 — ffmpeg + yt-dlp 內嵌（完整離線）
| # | 任務 | 狀態 |
|---|------|------|
| M6-1 | vendor-ffmpeg | ✅（77MB **GPL** build, 由 VISIONA_ALLOW_GPL_FFMPEG flag 放行） |
| M6-2 | vendor-ytdlp | ✅（35MB, yt-dlp 2026.03.17） |
| M6-3 | payload-macos stage ffmpeg + yt-dlp | ✅ |
| M6-4 | server internal/deps/ env var 偵測 | ✅（VISIONA_BUNDLE_BIN_DIR） |
| M6-5 | rebuild dmg | ✅ 220MB |

## 🔴 P1 release blocker：ffmpeg 授權
- macOS 上現成的 ffmpeg static binary 全部都是 GPL build（含 --enable-gpl --enable-libx264）
- 使用者決定 **B**：暫定使用 GPL build，發佈前由法務 review
- 必須在 PRD 第三方授權頁明確標 `ffmpeg: GPL build (under legal review)`
- 替代方案保留：自 build LGPL（需 build pipeline）/ online download / 砍 ffmpeg 功能

### M4 / M5 — Windows / Linux（無法在這台 Mac 驗證，僅寫 script）
| # | 任務 | 狀態 |
|---|------|------|
| M4-1 | Inno Setup .iss script | ✅ installer/windows/visiona-local.iss |
| M4-2 | Makefile wails-windows / exe target | ✅ uname 守門 |
| M4-3 | payload-windows | ✅ 在 macOS 上跑通 vendor 部分（378MB） |
| M5-1 | build-appimage.sh | ✅ installer/linux/build-appimage.sh |
| M5-2 | Makefile wails-linux / appimage | ✅ uname 守門 |
| M5-3 | payload-linux + udev rule | ✅ installer/linux/99-kneron.rules + install-udev.sh，在 macOS 上跑通 vendor（317MB） |

### lifecycle 補件（M1+ TODO 移入 M2-M6 末尾）
| # | 任務 | 狀態 |
|---|------|------|
| L-1 | watchServer() 每 10s health check | ✅ 連續 3 次失敗 emit server:dead event |
| L-2 | Fatal 原生對話框 | ✅ macOS osascript / Win PS / Linux zenity-kdialog-stderr |
| L-3 | Wails /ipc/raise endpoint | ✅ 隨機 port + wails-ipc-port 檔案 |
| L-4 | stale process 清理 | ✅ macOS/Linux lsof+ps；Windows 留 TODO |

## 專案概述

visionA-local 是 `/Users/jimchen/Innovedus/edge-ai-platform` 的 local 版本，目標是把原本要 deploy 到 EC2/staging Docker 環境的網頁工具，改造成可在本地單機執行的桌面應用，並打包成 GUI 安裝檔，支援 macOS / Windows / Ubuntu 三平台。

**任務等級**：L 級（完整流程）

## 進度表

| 階段 | 狀態 | 完成時間 | 備註 |
|------|------|----------|------|
| 需求討論（三方聯合） | ✅ 已完成 | 2026-04-11 | 四輪討論 + 交叉審閱完成 |
| PRD | ✅ 已完成 | 2026-04-11 | v1.2 定稿 |
| 設計規格 | ✅ 已完成 | 2026-04-11 | 第四輪修訂定稿 |
| 系統架構 / TDD | ✅ 已完成 | 2026-04-11 | 第四輪修訂 + Plan B 補件 |
| 開發（增量式） | 🔄 進行中 | - | M1 啟動（2026-04-11） |
| Review | ⏳ 待開始 | - | - |
| 測試 | ⏳ 待開始 | - | - |
| 打包 / 安裝檔 | ⏳ 待開始 | - | - |
| 交付 | ⏳ 待開始 | - | - |

## 當前待辦
- [x] 第一輪三方分析（已完成）
- [x] 使用者回答 15 個關鍵決策問題（已完成）
- [x] PM Agent 產出正式 PRD（2026-04-11）
- [x] Design Agent 產出正式設計規格（2026-04-11）
- [x] Architect Agent 產出正式 Design Doc + TDD（2026-04-11）
- [x] 第三輪使用者決策（砍 tray、B4、C2、D2、E1/E2/E3）
- [x] Design Agent 依第三輪決策修訂設計規格（2026-04-11）
- [x] **PM Agent 依第三輪決策修訂 PRD**（2026-04-11 恢復完成）
- [x] **Architect Agent 依第三輪決策修訂架構文件**（2026-04-11 恢復完成）
- [ ] 三方互相審閱（PM↔Design↔Architect 交叉 review）
- [ ] 使用者確認三份文件

## M1 開發進度（第二階段）

| # | 任務 | 狀態 |
|---|------|------|
| M1-1 | repo 骨架初始化 | ✅ 完成（Review 通過） |
| M1-2 | 複製 server core（跳過 cluster/tunnel/flash/update） | ✅ 完成（Review 通過） |
| M1-3 | 改寫 main.go / config.go / router.go | ✅ 完成（Review 通過） |
| M1-4 | 複製 frontend | ✅ 完成 |
| M1-5 | build Go server binary | ✅ 完成（Review 通過） |
| M1-6 | 複製 server/data 預置模型 | ✅ 已於 M1-2 併入（8 個 .nef, 73MB）|
| M1-7 | 清理前端 cluster/relay/tunnel UI | ✅ 完成（Review 通過） |
| M1-8 | pnpm build 通過 | ✅ 已於 M1-7 併入驗收 |
| M1-9 | 複製 installer shell 改名 visiona-local | ✅ 完成（Review 通過） |
| M1-10 | 改寫 installer + Python 雙策略空殼 | ✅ 完成（Review 通過） |
| M1-11 | payload 打包 | ✅ 完成（103MB，含 server binary + 8 nef） |
| M1-12 | wails build + ad-hoc sign + dmgbuild | ✅ 完成（.dmg 70MB 產出） |
| M1-13 | 全新 mac 端到端驗證 | ✅ 完成（5 核心承諾全達成；2 P0 + 1 路徑 bug 已修復） |

## 第二輪產出（進行中）
- Architect：`/Users/jimchen/visionA/local-tool/.autoflow/04-architecture/`
  - `design-doc.md`（索引）
  - `TDD.md`（索引）
  - `architecture-overview.md`
  - `dependency-bundling.md`
  - `packaging.md`
  - `build-pipeline.md`
  - `tray-and-lifecycle.md`
  - `i18n.md`
  - `risks-and-mitigations.md`
  - `api-endpoints.md`
  - `code-reuse-plan.md`
  - `removed-code.md`

## 重要決策紀錄

### 來源與策略
- **參考原專案**：`/Users/jimchen/Innovedus/edge-ai-platform`
- **程式碼策略**：重新建立 local-tool，可從 edge-ai-platform 自由取用任何程式碼（不做 fork、不做 submodule）
- **產品名稱**：visionA-local
- **Bundle ID**（暫定）：`com.innovedus.visiona-local`

### 產品定位
- 單機桌面應用，**不需要 proxy / nginx / relay / tunnel**
- Web UI 跑在 localhost（沿用原本 3721 埠或視情況調整）
- 必須能打包成 GUI 安裝檔，支援 **macOS / Windows / Ubuntu**
- 目標是「裝起來像一般 app」的體驗（類似 Docker Desktop / Ollama）

### 功能取捨（全照建議）
| 功能 | 決定 |
|------|------|
| 裝置管理（USB 連 Kneron） | ✅ 保留 |
| 攝影機串流（MJPEG + FFmpeg） | ✅ 保留 |
| 模型管理（上傳/切換 .nef） | ✅ 保留 |
| 推論引擎（分類/偵測/臉辨） | ✅ 保留 |
| Mock 模式 | ✅ 保留 |
| Tray（系統列常駐） | ❌ 砍（2026-04-11 改變：Q7 選關閉=結束後 tray 價值降低） |
| Cluster（多裝置叢集） | ❌ 砍 |
| Relay / Tunnel（遠端連線） | ❌ 砍 |

### 技術決策
- **GUI 框架**：Wails（沿用 edge-ai-platform 的 `installer/`）
- **依賴打包**：一鍵安裝所有依賴 — Python runtime + KneronPLUS SDK + ffmpeg + 預置模型 .nef 全部包進安裝檔，使用者不需要事先裝任何東西
- **前端清理**：清掉 relay 模式切換、cluster 管理等 UI

### 原專案技術堆疊（沿用）
- 前端：Next.js 16 + React 19 + TypeScript + shadcn/Radix + Tailwind + Zustand
- 後端：Go 1.26 + Gin + go:embed
- 硬體：Python KneronPLUS SDK
- 儲存：本地 JSON + 記憶體（無 DB）

### 第四輪使用者決策（2026-04-11，三方交叉審閱後）

| # | 問題 | 決定 |
|---|------|------|
| R4-1 | Kneron 授權 | **繼續內嵌**（不主動問 Kneron，B4 延續，發佈前 gate 維持） |
| R4-2 | MJPEG 延遲指標 | **首次 ≤250ms / 穩定後 ≤150ms** |
| R4-3 | WCAG 2.2 AA | **不做**（改為「盡力而為」，明確 scope 外） |
| R4-4 | 安裝時間 / RAM 指標 | **放寬**：安裝上限 5 分鐘、Mock idle RAM ≤600MB |
| R4-5 | 資料目錄命名 | **全小寫 `visiona-local`**（符合 Bundle ID + Linux 慣例） |
| R4-6 | 快捷鍵 | ⌘R → ⌘Shift+R；⌘Shift+W 取消（⌘4 已涵蓋） |
| R4-7 | 首次推論時間 AC | 拆為 **首次 30s / 回訪 15s** 兩級 |
| R4-8 | OS 通知策略 | 裝置連/斷 → App 內 toast；Server 崩潰 → shell out 原生通知 |

### 第三輪使用者決策（2026-04-11，三方第二輪文件後）

| # | 問題 | 決定 |
|---|------|------|
| Q-A | Tray 角色衝突（Q7 選關閉=結束後 tray 價值變低） | **A3 砍掉 tray**，省跨平台圖資產與 Wails tray 踩坑。從「保留功能」改為「不做」 |
| Q-B | Kneron 預置模型 re-distribution 授權 | **B4**：先假設可重新散布，開發時繼續內嵌，**發佈前必須再確認**（風險標記） |
| Q-C | M1 範圍 | **C2 不接受「M1 先不清前端」**：M1 就要把前端 cluster/relay UI 清乾淨，一次到位 |
| Q-D | vendor/ 目錄管理 | **D2 不進 git**，用 `make vendor-sync` 下載 |
| Q-E1 | macOS 資料目錄 | 用 `~/Library/Application Support/visionA-local/`（OS 慣例） |
| Q-E2 | Workspace 提升為 sidebar 一級 | OK |
| Q-E3 | Settings「外觀」分頁取消，語言併入「一般」 | OK |

### 第二輪使用者決策（2026-04-11）

| # | 問題 | 決定 |
|---|------|------|
| Q1 | Python runtime 策略 | **A**（完全離線內嵌 python-build-standalone），同時**保留 B**（偵測系統 Python）作為 fallback 選項 |
| Q2 | 程式碼簽章 | **C** 都不買（內部工具接受警告） |
| Q3 | 最低 OS 版本 | 都最新兩版（macOS 14/15、Windows 10/11、Ubuntu 22.04/24.04） |
| Q4 | ARM 支援 | 三平台都**只做 x86_64**，之後有需求再加（使用者是 Intel Mac） |
| Q5 | 預置模型 | 全部打包（~73MB） |
| Q6 | Auto-update | 先不做 |
| Q7 | 視窗關閉行為 | **B** 傳統式（關閉 = 結束程式） |
| Q8 | 預設執行模式 | 直接真實硬體模式（不預設 Mock） |
| Q9 | 韌體燒錄 flash | **B** 砍掉 |
| Q10 | yt-dlp / media/url | **A** 保留（要打包 yt-dlp） |
| Q11 | Bundle ID | `com.innovedus.visiona-local` 確認 |
| Q12 | Telemetry / 崩潰回報 | 預設不做 |
| Q13 | 多語系 | 中英雙語 |
| Q14 | Logo / 品牌 | 先沿用 edge-ai-platform，之後有需要再換 |
| Q15 | 深色模式 | 跟隨系統 |

## M1-10 留下的 M2/M1+ TODO（不阻斷 M1）
- `ensureBundledPython()` 實作（解壓 python-build-standalone、建 venv、離線 pip install wheels）— M2
- Wails `/ipc/raise` endpoint（真正的 single-instance focus）— M1+
- `watchServer()` 健康偵測 goroutine（每 10s health check）— M1+
- `isOurStaleServer` / `killByPort`（stale process 清理）— M1+
- Fatal 錯誤的原生對話框（目前只 emit event）— M1+

## 未解決問題
- **Kneron 預置模型 re-distribution 授權**（B4 決策）：開發階段先假設可用，發佈前必須跟 Kneron 官方確認。若不允許需改為首次啟動線上下載，會破壞「完全離線」承諾。
- **內部 Gitea Releases / GitHub Releases 基礎設施**：發佈策略假設有此通路，待確認。
- **CI runner 三平台是否齊備**：macOS / Windows / Linux runner 狀況待確認。

## 第一輪三方分析產出（已完成）
- PM：`/Users/jimchen/visionA/local-tool/.autoflow/01-requirements/pm-analysis-round1.md`
- Design：`/Users/jimchen/visionA/local-tool/.autoflow/03-design/design-analysis-round1.md`
- Architect：`/Users/jimchen/visionA/local-tool/.autoflow/04-architecture/architect-analysis-round1.md`