jim800121/visionA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: visionA monorepo with local-tool subproject

Browse Source 
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>
This commit is contained in:
jim800121chen 2026-04-11 22:10:38 +08:00
commit c54f16fca0
261 changed files with 39966 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
.gitignore vendored Normal file
View File

@ -0,0 +1,43 @@
# OS
.DS_Store
Thumbs.db
.AppleDouble
.LSOverride
# Editor
.vscode/
.idea/
*.swp
*.swo
# ─────────────────────────────────────
# local-tool 子專案的 build 產物
# ─────────────────────────────────────
# 不進 git 的依賴與產物（決策 R4-D2）
local-tool/vendor/
local-tool/dist/
local-tool/payload/
# Go server 的 embed 與 build 產物
local-tool/server/web/out/
local-tool/server/visiona-local-server
# Frontend
local-tool/frontend/node_modules/
local-tool/frontend/.next/
local-tool/frontend/out/
# Wails 產物
local-tool/visiona-local/build/bin/
local-tool/visiona-local/build/darwin/Resources/
local-tool/visiona-local/build/windows/Resources/
local-tool/visiona-local/build/linux/Resources/
local-tool/visiona-local/visiona-local
local-tool/visiona-local/visiona-local.exe
local-tool/visiona-local/payload/
# 環境變數
.env
.env.local
.env.*.local

27
README.md Normal file
View File

@ -0,0 +1,27 @@
# visionA
Innovedus visionA monorepo. Currently contains:
## Subprojects
### `local-tool/`
**visionA-local** — local-first edge AI desktop tool, derived from edge-ai-platform.
Wails + Go + Next.js, packaged as macOS dmg / Windows exe / Linux AppImage.
See [`local-tool/README.md`](./local-tool/README.md) for details.
## Repository
This repo is mirrored across two hosts:
- **Gitea (primary)**: https://gitea.innovedus.com/jim800121/visionA
- **GitHub (mirror)**: https://github.com/jim800121/visionA (private)
Use the `pushall` git alias to push to both:
```bash
git config alias.pushall '!git push gitea main && git push github main'
git pushall
```
## License
TBD (internal use)

163
local-tool/.autoflow/01-requirements/pm-analysis-round1.md Normal file
View File

@ -0,0 +1,163 @@
# visionA-local — PM 第一輪需求分析
> 階段：第一階段（三方聯合討論）— 需求探索
> 作者：PM Agent
> 日期：2026-04-10
> 狀態：第一輪分析草稿，**非 PRD**，待 Design / Architect 回饋與使用者確認
---
## 1. 產品定位：與原 edge-ai-platform 的差異
| 面向 | edge-ai-platform（原專案） | visionA-local（本專案） |
|------|---------------------------|------------------------|
| 部署形態 | 伺服器/容器，EC2 + Docker + 反向代理 | 單機桌面 App（Mac / Win / Ubuntu） |
| 網路模型 | 多人可遠端連線（有 relay / tunnel / cluster） | 只跑 localhost，一人一機 |
| 安裝體驗 | Ops 手動部署、curl install script、需先裝 ffmpeg/python | 一鍵 GUI 安裝檔，內嵌所有依賴 |
| 多裝置策略 | 支援 cluster（多 Kneron 叢集） | 單機最多接多顆 USB，但**不做 cluster** |
| 使用場景 | 共享平台、遠端存取、多人協作 | 個人開發、現場 POC、離線 demo |
**核心轉換：從「共享基礎設施」變成「個人工具」**。這個定位決定了所有後續取捨——任何為了「多人」「遠端」「規模化」而生的功能都該砍掉，任何為了「安裝便利」「離線可用」「單人順手」的體驗都要加強。
### 目標使用者（Persona 草案，待細化）
1. **Innovedus 內部應用工程師 / FAE（主要）** — 帶筆電去客戶現場做 Kneron KL720/KL730 demo，不能依賴網路或客戶 IT 環境。核心需求：**「接上去就能跑」**。
2. **外部開發者 / 評估客戶（次要）** — 剛拿到 Kneron 開發板想快速上手試玩，沒耐心搞 Python 環境與 SDK 安裝。核心需求：**「不踩坑」**。
3. **Solution Architect / 產品經理（第三）** — 非工程背景，想用 Mock 模式體驗產品能力，向客戶說故事。核心需求：**「不用寫 code」**。
此產品定位是**內部工具 + POC 工具**，不是 production 服務。這個前提會影響我們對可靠性、可觀測性、license、auto-update 等的取捨。
---
## 2. 核心 User Stories（6 個關鍵情境）
| # | 情境 | Persona | 成功體驗 |
|---|------|---------|----------|
| US-1 | **第一次安裝** | 全部 | 下載安裝檔 → 雙擊 → 照指示點幾下 → 桌面出現 app icon + tray 圖示，全程 < 3 分鐘、無需 terminal |
| US-2 | **Mock 模式試玩** | 產品經理 | 啟動 app 後預設就能進入 Mock 模式，看到 3 個假裝置、跑假推論流，不用接任何硬體 |
| US-3 | **連實體 Kneron 裝置** | FAE | 插上 USB → App 自動偵測 → 顯示裝置型號與韌體版本 → 點「connect」就能跑 |
| US-4 | **切換/上傳模型** | 開發者 | 從內建的預置 .nef 模型選一個，或拖拉自己的 .nef 進來，不用手動拷貝檔案到特定路徑 |
| US-5 | **跑即時攝影機推論** | FAE | 選一顆接上的 webcam → 點「Start」→ 看到 MJPEG 串流 + overlay 推論結果 |
| US-6 | **從 tray 快速控制** | 全部 | 關閉主視窗後 app 仍在 tray，點 tray 可看到裝置狀態 / 開啟 UI / 離開 |
**延伸情境（次要，可進 Phase 2）：**
- US-7：上傳影片 / 圖片做離線推論（原專案已有）
- US-8：匯出推論結果（JSON / CSV / 影片）
- US-9：查看系統依賴狀態與日誌
---
## 3. 功能範圍確認（對照原專案 API / 頁面）
### 3.1 後端 API 保留 / 刪除
| API 群組 | 決定 | 備註 |
|---------|------|------|
| `/api/system/*`（health / info / metrics / deps） | ✅ 保留 | local 也需要，但 metrics 可能簡化 |
| `/api/system/update-check` | ⚠️ 視情況 | 取決於使用者是否要 auto-update（**待確認**） |
| `/api/system/restart` | ✅ 保留 | Tray 需要 |
| `/api/models/*`（list / get / upload / delete） | ✅ 全保留 | 核心 |
| `/api/devices/*`（list / scan / connect / disconnect / flash / inference start/stop） | ✅ 全保留 | 核心 |
| `/api/camera/*`（list / start / stop / stream） | ✅ 全保留 | 核心 |
| `/api/media/upload/*`（image / video / batch） | ✅ 保留 | US-7 需要 |
| `/api/media/url` | ⚠️ 建議砍 | 需要 yt-dlp 依賴，local 版應儘量減少外部依賴；若砍掉 yt-dlp 可少一個依賴 |
| `/api/clusters/*`（全部） | ❌ 砍 | 決策已確認 |
| `/ws/clusters/*` | ❌ 砍 | 同上 |
| `/ws/devices/*`、`/ws/server-logs` | ✅ 保留 | 核心 |
| `/auth/token`（relay token） | ❌ 砍 | local 不需要 relay |
| relay / tunnel 相關中介層 | ❌ 砍 | 決策已確認 |
### 3.2 前端頁面保留 / 刪除
對照 `frontend/src/app/` 結構：
| 路由 | 決定 |
|------|------|
| `/`（首頁 / dashboard） | ✅ 保留，但**重新設計**——local 版首頁應該是「快速開始」而非「叢集總覽」 |
| `/devices` | ✅ 保留 |
| `/models` | ✅ 保留 |
| `/workspace`（推論工作區） | ✅ 保留 |
| `/settings` | ✅ 保留，但**清掉 relay 設定、cluster 設定** |
| `/clusters` | ❌ 整個砍掉 |
### 3.3 其他模組處理
| 模組 | 決定 |
|------|------|
| `server/internal/cluster/` | ❌ 刪除 |
| `server/internal/relay/` | ❌ 刪除 |
| `server/internal/tunnel/` | ❌ 刪除 |
| `server/internal/flash/`（韌體更新） | ⚠️ **需 Architect 確認**：local 版要不要保留韌體燒錄？可能在現場 demo 會用到 |
| `server/internal/update/`（自我更新） | ⚠️ 取決於 auto-update 決策 |
| `installer/`（Wails） | ✅ 作為 visionA-local 的 GUI shell 基礎 |
---
## 4. 驗收標準方向（待細化為量化指標）
local 版的「能用」應該用**使用者體驗時間**與**零依賴**兩個維度定義：
| 驗收面向 | 建議門檻 |
|---------|---------|
| **安裝時間** | 全新一台機器（無 Python、無 ffmpeg、無 SDK）從下載安裝檔到開啟 app 首屏 < 5 分鐘 |
| **首次推論時間** | 從 app 開啟到 Mock 模式跑出第一幀推論結果 < 30 秒（無需使用者任何設定） |
| **實機接入時間** | 插上 Kneron USB → app 偵測到裝置 → connect 成功 < 10 秒 |
| **零外部依賴** | 使用者機器**完全不需要**預先安裝 Python / ffmpeg / KneronPLUS / 任何 SDK |
| **離線可用** | 完全斷網下，除了 update-check 之外所有核心功能正常 |
| **跨平台** | macOS 12+ (arm64/amd64)、Windows 10+ (amd64)、Ubuntu 22.04+ (amd64) 三平台一致體驗 |
| **安裝檔大小** | 單平台安裝檔 < 500 MB（**需 Architect 評估是否可行**，預置模型數量會影響） |
| **資源佔用（idle）** | Mock 模式 idle 時 CPU < 5%、RAM < 500 MB |
---
## 5. 需要 Architect / Design 回答的問題
### 給 Architect 的問題
1. **KneronPLUS SDK 跨平台打包**：KneronPLUS 在 mac / win / linux 的安裝方式不一樣（mac 需 driver、win 需 .dll、linux 需 udev rules），Wails 能不能把這些差異都抽象掉？是否需要在 post-install 步驟處理？
2. **Python runtime 內嵌策略**：我們要嵌入整個 Python 3.12 + KneronPLUS site-packages，單平台大概會長多大？有沒有更輕的方案（例如只嵌入需要的子模組）？
3. **ffmpeg 內嵌**：直接打包 static binary 還是透過 brew/winget 裝？static binary 比較省事但會讓安裝檔變大 50-100MB。
4. **預置模型 .nef**：要嵌入幾顆？哪幾顆？影像分類 / 物件偵測 / 臉辨各一顆？每顆多大？
5. **韌體燒錄（flash）功能**：local 版要不要保留？這會牽涉到韌體檔案也要打包進去。
6. **單一執行檔 vs 分離 installer**：原專案 edge-ai-platform 是 single binary + Wails installer，visionA-local 是否直接用 Wails 做 shell，把 server binary 包在 Wails 裡？
7. **update 機制**：Wails 有沒有現成的 auto-update 框架？或者每次都讓使用者重下？
8. **程式碼簽章**：Mac notarization 與 Windows Authenticode 要不要做？這影響發行流程與金錢成本。
9. **Tray 的跨平台一致性**：Wails tray 在三平台體驗一致嗎？Linux tray 尤其有坑。
10. **日誌與崩潰回報**：local 版該怎麼收集錯誤？要不要做 opt-in 的遠端 crash report？
### 給 Design 的問題
1. **Onboarding 流程**：第一次開啟 app 要不要有歡迎頁 / 快速教學？還是直接進 Mock 模式讓使用者自己摸索？
2. **首頁重新設計**：原版首頁是「叢集總覽」，local 版首頁應該呈現什麼？Dashboard？設備列表？還是 workspace 直接當首頁？
3. **Tray 的使用者流程**：點 tray icon 是打開主視窗、還是彈出 menu、還是開 mini dashboard？Mac / Win / Linux 各自慣例不同。
4. **Mock 模式的視覺提示**：使用者要能很明顯知道「我現在在跑假資料」，避免誤以為是真推論。是否要加 watermark / badge？
5. **安裝器的外觀**：Wails installer 的首屏長什麼樣？只有一顆「安裝」按鈕？還是要有品牌頁 / EULA / 路徑選擇？
6. **錯誤狀態**：裝置拔掉、模型載入失敗、ffmpeg 壞了——這些狀態的視覺與文案怎麼處理？
7. **暗色模式**：原專案有沒有暗色？local 版要不要跟隨系統？
8. **裁切 UI 範圍**：清掉 relay / cluster 後，`settings` 頁會剩什麼？需要重新規劃資訊架構嗎？
---
## 6. 需要使用者確認的問題
1. **Auto-update**：要不要做自動更新？如果要，是「背景下載 + 提示重啟」還是「只提示有新版，讓使用者自己下載」？
2. **程式碼簽章 / 公證**：要不要投資做 Apple Developer ID notarization 與 Windows code signing？這需要購買憑證（Apple $99/年、Windows EV cert $300-600/年），不做的話 Mac 會跳「unidentified developer」警告、Windows 會被 SmartScreen 攔截。
3. **發佈通路**：只放 Gitea Releases 讓內部下載？還是要上 Mac App Store / Microsoft Store / Snap Store？
4. **License / 啟用機制**：要不要做 license key 控制（防止外流）？還是完全開放？
5. **遙測**：要不要收集匿名使用數據（開啟次數、功能使用頻率、崩潰報告）？以便改進產品？
6. **目標使用者優先級**：內部 FAE、外部客戶、產品經理三種 persona，哪一種是 MVP 要優先服務的？這會影響 onboarding 設計。
7. **預置模型範圍**：同意內嵌「影像分類 + 物件偵測 + 臉辨」各一顆嗎？或者要更多 / 更少？
8. **韌體燒錄功能**：local 版保留嗎？是 FAE 現場 demo 的實用功能，但會增加打包複雜度。
9. **`media/url`（YouTube URL 匯入）功能**：要不要砍？砍了可以少一個 yt-dlp 依賴。
10. **Linux 支援優先級**：決策上寫了支援 Ubuntu，但實際開發優先級：Mac > Win > Linux 還是三平台齊進？Linux tray / USB 權限問題最多。
---
## 下一步
這份第一輪分析**不是 PRD**，目的是讓 Architect 與 Design 看過後給出技術與體驗面的反饋，以及讓使用者確認第 6 節的 10 個問題。待以下輸入收到後，PM 會進入第二輪——撰寫正式的 PRD（含 RICE、完整 User Stories、功能規格、成功指標、風險評估）。
需要的輸入：
- [ ] 使用者回答第 6 節的 10 個問題
- [ ] Architect 的技術可行性回饋（第 5 節問題 1-10）
- [ ] Design 的體驗面回饋（第 5 節問題 1-8）

84
local-tool/.autoflow/02-prd/PRD.md Normal file
View File

@ -0,0 +1,84 @@
# visionA-local — 產品需求文件（PRD）索引
> 版本：v1.2（第四輪使用者決策套用）
> 作者：PM Agent
> 日期：2026-04-11
> 狀態：**三方交叉審閱完成 + 第四輪決策落地**
> 任務等級：L 級（完整流程）
> **品牌命名 vs 資料目錄命名**：產品品牌名維持 `visionA-local`（大小寫混寫，對應現有 Logo 與對外文案）；**資料目錄、Bundle ID、CLI 執行檔、安裝檔檔名**統一用全小寫 `visiona-local`（對齊 Bundle ID `com.innovedus.visiona-local` 與 Linux 檔案系統慣例）。第四輪 R4-5 決策。
---
## 文件導覽
本 PRD 採模組化結構。各章節為一句話摘要 + 子檔案連結，子檔案內含完整細節。
| 章節 | 摘要 | 子檔案 |
|------|------|--------|
| 1. 產品策略與定位 | visionA-local 是 edge-ai-platform 的單機桌面版，專為「帶著筆電做 Kneron demo 的人」而生，價值主張是「裝起來就能跑、離線可用、零依賴」 | [`strategy.md`](./strategy.md) |
| 2. 目標使用者與使用情境 | 三種 Persona：內部 FAE（主要）、外部開發者 / 評估客戶、Solution Architect / PM；6 個核心 User Story | [`user-research.md`](./user-research.md) |
| 3. 產品願景與非目標 | visionA-local **不做**：cluster、relay、tunnel、tray、auto-update、程式碼簽章、telemetry、韌體燒錄、多架構、商店上架 | [`vision-and-non-goals.md`](./vision-and-non-goals.md) |
| 4. 功能清單與 API 對照 | 對照原 edge-ai-platform，列出保留 / 刪除 / 新增的前後端功能與 API endpoint | [`features/feature-inventory.md`](./features/feature-inventory.md) |
| 5. 使用者流程 | 首次安裝 → First-Run → 日常使用 → 離開 | [`features/user-flows.md`](./features/user-flows.md) |
| 6. 非功能需求與驗收標準 | 量化驗收條件：安裝時間、首次推論時間、安裝檔大小、資源占用、離線可用 | [`nonfunctional.md`](./nonfunctional.md) |
| 7. 發佈與交付策略 | 內部 Gitea Releases / GitHub Releases；不上商店、不做 auto-update、不做憑證簽章 | [`release-strategy.md`](./release-strategy.md) |
| 8. 風險與相依性 | 交叉引用 Architect Round 1 的 R1-R5 技術風險 + PM 補充的產品風險 | [`risks.md`](./risks.md) |
---
## 快速摘要（TL;DR）
**做什麼**：把 `edge-ai-platform`（原本要部署到 EC2 / Docker 的 Kneron AI 邊緣運算平台）改造成**單機桌面應用**，打包成 macOS / Windows / Ubuntu 三平台的 GUI 安裝檔。
**為誰做**：主要是 Innovedus 內部 FAE（帶筆電到客戶現場做 demo），次要是外部開發者（剛拿到 Kneron 板想快速上手）和 Solution Architect / PM（想用 Mock 模式說故事）。
**核心轉換**：從「共享基礎設施」→「個人工具」。任何為「多人 / 遠端 / 規模化」而生的功能都砍掉，任何為「安裝便利 / 離線可用 / 單人順手」的體驗都強化。
**最重要的 3 個產品決策**：
1. **一鍵離線安裝**：Python runtime + KneronPLUS SDK + ffmpeg + 預置模型 .nef 全部內嵌進安裝檔（單平台約 200MB），使用者不需要預先裝任何東西、也不需要連網。使用者還可以 fallback 使用系統 Python。
2. **砍掉 50% 的原始碼**：cluster、relay、tunnel、tray、relay-token、gitea-url、韌體燒錄、auto-update、docker / deploy scripts 全部刪除。新專案只保留核心推論路徑。
3. **內部工具定位**：不投資憑證簽章（使用者接受 Gatekeeper / SmartScreen 警告）、不上商店、不做 telemetry、不做 license key。發佈到內部 Gitea Releases。
**不做什麼（明確排除）**：多裝置 cluster、遠端連線、**系統列 tray**、自動更新、程式碼簽章、崩潰遙測、韌體 flash、ARM 架構、Mac App Store / Microsoft Store / Snap Store 上架、license 啟用機制。
---
## 發佈範圍（MVP）
visionA-local 不分 Phase 1 / Phase 2 / Phase 3——**所有核心功能一次到位**，因為這是內部工具，沒有「分階段驗證市場」的必要。MVP 即 GA。
**MVP 必達功能**：
- macOS（x86_64）/ Windows（x86_64）/ Ubuntu（x86_64）三平台安裝檔
- 首次啟動 First-Run 流程（歡迎 → 模式選擇 → 硬體偵測）
- 裝置管理（USB Kneron 偵測 / 連線）
- 模型管理（預置 .nef + 自上傳）
- 推論引擎（分類 / 偵測 / 臉辨）
- 攝影機串流（MJPEG + 推論 overlay）
- 媒體推論（圖片 / 影片 / URL 上傳）
- Mock 模式（零硬體入口）
- 中英雙語 + 跟隨系統的深色模式
- **M1 即一次清乾淨前端** cluster / relay UI（不留半調子 legacy）
**MVP 排除**：cluster、relay、tunnel、**系統列 tray**、auto-update、程式碼簽章、telemetry、韌體燒錄、ARM 架構。
---
## 交叉審閱清單
本 PRD 完成後需：
- [x] **Architect 審閱**：所有需求技術上可行？Effort 估算合理？R1-R5 風險有被充分反映？（2026-04-11 完成，見 `/Users/jimchen/visionA/local-tool/.autoflow/04-architecture/architect-cross-review.md`）
- [x] **Design 審閱**：體驗面沒有遺漏？First-Run 流程已被納入？（2026-04-11 完成，見 `/Users/jimchen/visionA/local-tool/.autoflow/03-design/design-cross-review.md`）
- [x] **PM 自審**（v1.2）：第四輪決策已點對點落地（2026-04-11）
- [ ] **使用者最終確認**：整份 PRD v1.2 的發佈範圍、非目標、驗收標準皆無誤？
---
## 變更紀錄
| 版本 | 日期 | 作者 | 變更 |
|------|------|------|------|
| v1.0 | 2026-04-11 | PM Agent | 第一階段產出；以 15 個使用者決策 + 三方第一輪分析為基礎撰寫 |
| v1.1 | 2026-04-11 | PM Agent | 套用第三輪使用者決策：砍 tray（Q-A）、Kneron 模型授權改風險標記（Q-B）、M1 前端一次清乾淨（Q-C）、macOS 資料目錄改 `~/Library/Application Support/visionA-local/`（Q-E1）、Workspace 升 sidebar 一級（Q-E2）、Settings 外觀分頁取消並把語言併入一般（Q-E3） |
| v1.2 | 2026-04-11 | PM Agent | 套用第四輪使用者決策（三方交叉審閱後）：R4-1 Kneron 授權暫不主動問、R4-2 MJPEG 延遲改首次≤250ms / 穩定後≤150ms、R4-3 WCAG 2.2 AA 正式列為非目標（盡力而為）、R4-4 安裝時間上限放寬至 5 分鐘、Mock idle RAM 放寬至 ≤600MB、R4-5 資料目錄/Bundle ID 全小寫 `visiona-local`、R4-6 ⌘R 改 ⌘Shift+R、⌘Shift+W 取消、R4-7 首次推論拆首次≤30s/回訪≤15s 兩級、R4-8 OS 通知策略分層（裝置 toast / 崩潰 shell out 原生通知）；另補 sidebar 描述對齊 Design（4 主導航 + Settings 底部獨立區）、新增 4.8 第三方授權宣告章節（ffmpeg LGPL、yt-dlp、Python 等）、新增 R11 發佈通路 / R12 CI runner 風險追蹤項、新增 5.5 single-instance 第二次雙擊 UX、5.6 OS 通知策略 |

201
local-tool/.autoflow/02-prd/features/feature-inventory.md Normal file
View File

@ -0,0 +1,201 @@
# 4. 功能清單與 API 對照（對照原 edge-ai-platform）
本章節列出 visionA-local 相對於原 edge-ai-platform 的功能取捨。所有 ✅ / ❌ / ⚠️ 決定都已依使用者 Q1-Q15 與三方第一輪分析定案。
## 4.1 後端 API 對照表
| API 群組 | Endpoint | 去留 | 說明 |
|---------|----------|------|------|
| **系統 / 健康** | `GET /api/system/health` | ✅ 保留 | 基本健康檢查 |
| | `GET /api/system/info` | ✅ 保留 | 顯示版本、平台、執行目錄 |
| | `GET /api/system/metrics` | ✅ 保留（簡化） | local 版可省略 prometheus 整合，回傳簡單 JSON |
| | `GET /api/system/deps` | ✅ 保留 | 顯示依賴狀態（Python / ffmpeg / KneronPLUS） |
| | `GET /api/system/update-check` | ❌ 砍 | Q6 決定不做 auto-update |
| | `POST /api/system/restart` | ✅ 保留 | Settings 頁「重啟服務」按鈕會用到（原 Tray 用途已取消） |
| **模型管理** | `GET /api/models` | ✅ 保留 | 列出所有模型 |
| | `GET /api/models/:id` | ✅ 保留 | |
| | `POST /api/models/upload` | ✅ 保留 | 支援拖放上傳 |
| | `DELETE /api/models/:id` | ✅ 保留 | |
| | `GET /api/models/:id/download` | ✅ 保留 | |
| **裝置管理** | `GET /api/devices` | ✅ 保留 | |
| | `POST /api/devices/scan` | ✅ 保留 | USB 掃描 |
| | `POST /api/devices/:id/connect` | ✅ 保留 | |
| | `POST /api/devices/:id/disconnect` | ✅ 保留 | |
| | `POST /api/devices/:id/flash` | ❌ 砍 | Q9 決定砍掉韌體燒錄 |
| | `POST /api/devices/:id/inference/start` | ✅ 保留 | |
| | `POST /api/devices/:id/inference/stop` | ✅ 保留 | |
| **攝影機** | `GET /api/camera` | ✅ 保留 | 列出 webcam |
| | `POST /api/camera/:id/start` | ✅ 保留 | |
| | `POST /api/camera/:id/stop` | ✅ 保留 | |
| | `GET /api/camera/:id/stream` | ✅ 保留 | MJPEG 串流 |
| **媒體上傳** | `POST /api/media/upload/image` | ✅ 保留 | |
| | `POST /api/media/upload/video` | ✅ 保留 | |
| | `POST /api/media/upload/batch` | ✅ 保留 | |
| | `POST /api/media/url` | ✅ 保留 | Q10 決定保留（打包 yt-dlp） |
| **Cluster** | `/api/clusters/*`（全部 endpoint） | ❌ 全砍 | |
| **WebSocket** | `/ws/clusters/*` | ❌ 砍 | |
| | `/ws/devices/*` | ✅ 保留 | 裝置狀態即時推送 |
| | `/ws/server-logs` | ✅ 保留 | Server log 顯示（供進階 / 設定頁使用，非 tray） |
| **認證 / Relay** | `POST /auth/token` | ❌ 砍 | relay token，localhost 不需要 |
| | relay / tunnel 中介層 | ❌ 砍 | |
## 4.2 前端頁面對照表
對照 `frontend/src/app/`：
| 路由 | 去留 | 說明 |
|------|------|------|
| `/`（Dashboard） | ✅ 保留（重新設計） | 拿掉 cluster 統計，首頁改為「快速開始 + 裝置狀態 + 最近活動」 |
| `/devices` | ✅ 保留 | 裝置列表 + connect / disconnect |
| `/models` | ✅ 保留 | 模型庫 |
| `/workspace` 或 `/workspace/[deviceId]` | ✅ 保留（**升為 sidebar 一級**） | **核心頁面**：單裝置推論工作區。**第三輪 Q-E2 決策**：Workspace 從「進入 Device 後的子頁」升級為 sidebar 一級入口，讓使用者不需要先挑裝置就能進工作區（內部可顯示「請先連線裝置」狀態） |
| `/workspace/cluster` | ❌ 砍 | |
| `/clusters` | ❌ 砍 | |
| `/settings` | ✅ 保留（重新設計） | 清掉 relay / cluster 設定。**第三輪 Q-E3 決策**：取消「外觀」分頁（深色模式跟隨系統不需獨立分頁）、將「語言」併入「一般」分頁。最終分頁結構：**一般（含語言）/ 硬體 / 模型 / 進階**，共 4 個分頁 |
## 4.3 元件對照表
對照 `frontend/src/components/`：
| 分類 | 元件 | 去留 |
|------|------|------|
| `camera/` | camera-feed, camera-controls, camera-overlay, source-selector, camera-inference-view, batch-image-thumbnails | ✅ 全保留 |
| `devices/` | device-card, device-list, device-health-card, device-connection-log, device-status | ✅ 保留 |
| | flash-dialog, flash-progress | ❌ 砍（Q9） |
| `models/` | model-card, model-grid, model-filters, model-upload-dialog, model-detail, model-comparison-dialog | ✅ 全保留 |
| `inference/` | inference-panel, classification-result, confidence-slider, performance-metrics, video-progress | ✅ 全保留 |
| `cluster/` | cluster-card, cluster-list, cluster-create-dialog, cluster-performance | ❌ 全砍 |
| `dashboard/` | stat-card, activity-timeline, connected-devices-list | ✅ 保留（拿掉 cluster 欄位） |
| `layout/` | sidebar, header, connection-status, help-button | ✅ 保留但改寫（sidebar 為 **4 個主導航 + Settings（底部獨立區，用 divider 分隔）**：Dashboard / Devices / Models / **Workspace** + `── divider ──` + Settings。對應 Design spec/01-IA §1.2） |
| — | onboarding-dialog, guided-tour | ✅ 保留並強化（First-Run） |
| — | relay-token-sync | ❌ 砍 |
| — | server-log-viewer, server-status-dashboard | ✅ 保留（桌面 app 需要） |
| — | theme-sync, lang-sync, store-hydration | ✅ 保留 |
## 4.4 Server 內部模組對照表
對照 `server/internal/`：
| 模組 | 去留 |
|------|------|
| `api/` | ✅ 改寫（刪除 cluster / tunnel / relay handler 與 route） |
| `camera/` | ✅ 直接複製 |
| `device/` | ✅ 直接複製 |
| `model/` | ✅ 直接複製 |
| `inference/` | ✅ 直接複製 |
| `config/` | ✅ 改寫（砍掉 RelayURL / RelayToken / GiteaURL / GUIMode） |
| `deps/` | ✅ 直接複製 |
| `cluster/` | ❌ 整包刪除 |
| `tunnel/` | ❌ 整包刪除 |
| `flash/` | ❌ 整包刪除（Q9） |
| `update/` | ❌ 整包刪除（Q6） |
| `relay/` | ❌ 整包刪除 |
| `tray/` | ❌ 整包刪除（**第三輪 Q-A** 決策砍掉 tray） |
`server/main.go` 需移除的 import 與初始化：
- `internal/cluster`、`internal/tunnel`、`pkg/hwid`、`internal/flash`、`internal/update`、`internal/tray`
- `cfg.RelayURL` / `RelayToken` / `GiteaURL` flag
- `tunnelClient.Start()`、`clusterMgr`、`relayWebURL()`、`trayMgr` 等呼叫
- `--gui` mode、relay-server cmd、tray init
## 4.5 新增的功能（相對於原專案）
| 新功能 | 說明 |
|--------|------|
| **First-Run 歡迎流程** | 歡迎畫面 → 模式選擇（真實 / Mock）→ 硬體偵測（真實模式）→ 完成 |
| **內嵌依賴解壓流程** | 首次啟動時把 Python wheels / ffmpeg / nef 從 Wails payload 解壓到 OS 慣例資料目錄（macOS：`~/Library/Application Support/visiona-local/`；Windows / Linux 依各自慣例，由 Architect TDD 定義） |
| **Python fallback 策略** | 優先使用內嵌 Python（Q1 決定 A + B），找不到時 fallback 到系統 Python |
| **原生 menu bar（macOS / Win / Linux）** | 釋放 ⌘N / ⌘W / ⌘Q 等桌面快捷鍵；快速動作（新增裝置 / 上傳模型 / 開啟工作區）改走 menu bar，**不再透過 tray** |
| **拖放 .nef / 圖片 / 影片到視窗任意處** | 桌面 app 慣例 |
| **Mac Gatekeeper 警告引導頁** | 因為不做 notarization |
| **Windows SmartScreen 警告引導頁** | 因為不做 EV cert |
| **Mock 模式視覺標記** | 主視窗標題列 + 首頁徽章 + sidebar 底部狀態列（**不再含 tray badge**） |
## 4.6 原專案要刪除的檔案清單（具體路徑）
```
server/internal/cluster/ ← 整包刪
server/internal/tunnel/ ← 整包刪
server/internal/flash/ ← 整包刪（Q9）
server/internal/update/ ← 整包刪（Q6）
server/internal/tray/ ← 整包刪（第三輪 Q-A）
server/cmd/relay-server/ ← 整包刪
server/pkg/hwid/ ← relay token 用的，可刪
docker/ ← 整包刪
scripts/deploy-aws.sh ← 刪
scripts/deploy-ec2.sh ← 刪
frontend/src/app/clusters/ ← 整包刪
frontend/src/app/workspace/cluster/← 整包刪
frontend/src/components/cluster/ ← 整包刪
frontend/src/components/relay-token-sync.tsx ← 刪
frontend/src/components/devices/flash-*.tsx ← 刪
```
> **第三輪 Q-C 決策**：M1（即 MVP）階段必須一次把前端 cluster / relay / tray 相關 UI 全部清乾淨，**不允許「先留著不動」**。若開發過程中發現 legacy 相依讓清理成本很高，也必須在 M1 內解決。
## 4.7 RICE 優先級（簡化版）
因為 MVP 範圍已定案（一次到位），此處 RICE 僅用於**開發順序**而非功能取捨。
| 功能 | Reach（內部人數）| Impact（0.25-3）| Confidence | Effort（人週）| RICE | 建議開發順序 |
|------|-----------------|----------------|------------|--------------|------|-------------|
| Wails 殼 + payload 解壓流程 | 10 | 3 | 100% | 2 | 15 | 1（阻斷性） |
| Go server 瘦身（刪 cluster / relay / tray） | 10 | 3 | 100% | 1 | 30 | 2 |
| 前端 sidebar / 路由 / 首頁改寫（含 Workspace 升一級 + 清 cluster/relay/tray UI） | 10 | 2.5 | 100% | 1.5 | 16.7 | 3 |
| Python runtime + wheels 內嵌 | 10 | 3 | 80% | 2 | 12 | 4（R1/R3 風險） |
| 裝置偵測 + connect（核心推論路徑）| 10 | 3 | 100% | 1 | 30 | 5 |
| First-Run 歡迎流程 + Mock 模式入口 | 10 | 2 | 100% | 1 | 20 | 6 |
| 攝影機串流 + 推論 overlay | 10 | 2.5 | 100% | 1 | 25 | 7 |
| 媒體上傳（image / video / URL） | 7 | 1.5 | 100% | 1 | 10.5 | 8 |
| 中英雙語 + 深色模式跟隨系統（Settings 語言併入一般） | 10 | 1 | 100% | 0.5 | 20 | 9 |
| 打包輸出（dmg / exe / AppImage） | 10 | 3 | 70% | 2 | 10.5 | 10（阻斷性發佈） |
> **第三輪 Q-A 決策**：原排序第 6 的「Tray（三平台）」已移除，後續項目依序向前遞補。
> **注意**：Reach 取「預計內部使用人數 × 次數」近似值，因為是內部工具沒有市場規模概念。
## 4.8 第三方依賴的授權宣告（第四輪新增）
visionA-local 內嵌以下第三方工具，對應授權與宣告責任如下：
| 依賴 | 用途 | 授權 | 宣告要求 |
|------|------|------|---------|
| **ffmpeg**（LGPL build）| 攝影機 / 影片處理 | **LGPL v2.1+** | ⚠️ **必須宣告**：(1) 在安裝檔內附 `LICENSE-ffmpeg.txt`（含完整 LGPL 條文與 copyright notice）；(2) About 對話框顯示 `Powered by FFmpeg (LGPL)` 與連結；(3) 若未來改用 GPL build 的 ffmpeg，整個 visionA-local 必須改為 GPL 授權，**本 MVP 只能用 LGPL build**；(4) 動態連結 ffmpeg binary（不靜態連結成 Go binary），符合 LGPL 的 "user can replace the library" 條款 |
| **yt-dlp** | `/api/media/url` YouTube 影片下載 | **Unlicense（public domain-equivalent）+ MIT fork 歷史** | ✅ 建議宣告：About 對話框列出 `yt-dlp (Unlicense)`；內附 `LICENSE-yt-dlp.txt`。無強制要求但好習慣 |
| **KneronPLUS SDK**（wheel） | 裝置 / 推論 | **Kneron 專有授權**（re-distribution 待確認，見 R5 / R9） | ⚠️ **發佈前 gate**（R5）：授權允許後才能正式對外發佈；內嵌時必須保留 Kneron 的 copyright notice 與 `LICENSE-KneronPLUS.txt` |
| **Python runtime**（python-build-standalone）| 執行 KneronPLUS | **PSF License 2.0（Python 本體）+ 各組件授權** | ✅ 必須宣告：內附 `LICENSE-python.txt`；About 對話框列出 Python 版本與授權 |
| **Python wheels**（numpy / opencv / pyusb 等） | 推論依賴 | 各 wheel 不同（多為 BSD / MIT / Apache 2.0）| ✅ 必須宣告：內附 `third_party_licenses.txt`，列出每個 wheel 的授權條文 |
| **Wails v2** | GUI 殼 | **MIT** | ✅ About 對話框列出 |
| **Next.js / React / shadcn / Radix / Tailwind / Zustand** | 前端 | **MIT 為主**（個別 check） | ✅ About 對話框列出主要依賴；前端 build 時由 webpack-license-plugin 自動產出 `frontend-licenses.txt` |
### 4.8.1 授權檔案落點
所有授權檔案放在安裝後的 `<APPDATA>/licenses/` 目錄：
```
<APPDATA>/licenses/
├── LICENSE-visionA-local.txt (本產品 — 內部工具，待定)
├── LICENSE-ffmpeg.txt (LGPL v2.1+)
├── LICENSE-yt-dlp.txt (Unlicense)
├── LICENSE-KneronPLUS.txt (Kneron 專有)
├── LICENSE-python.txt (PSF)
├── third_party_licenses.txt (Python wheels 合併)
├── frontend-licenses.txt (前端 npm 依賴合併)
└── README.md (宣告總覽與對應表)
```
About 對話框提供「檢視第三方授權」按鈕 → 開啟上述目錄或彈出瀏覽器檢視。
### 4.8.2 架構責任分工
- **Architect**：在 `04-architecture/dependency-bundling.md` / `packaging.md` 補實作細節（檔案來源、打包流程、ffmpeg 必須動態連結而非靜態）
- **Frontend**：在 Settings > 進階 或 Help > About 對話框加「第三方授權」入口
- **DevOps**：CI build 流程加入授權檔案收集腳本，確保每次 release 都帶齊
### 4.8.3 MVP 邊界聲明
本 MVP 是**內部工具**，不對外商業發佈，因此：
- ✅ 授權宣告做到位（LGPL 強制項目必做）
- ❌ **不做** OSS license compliance tool 的正式掃描（如 FOSSA、Black Duck）
- ❌ **不做** SBOM（Software Bill of Materials）產出
- 若未來對外商業發佈需補上述合規流程

295
local-tool/.autoflow/02-prd/features/user-flows.md Normal file
View File

@ -0,0 +1,295 @@
# 5. 使用者流程
本章節描述三個關鍵使用者流程：**首次安裝 → First-Run → 日常使用**。每個流程都標注對應的 User Story 與驗收標準。
## 5.1 首次安裝流程（對應 US-1）
```
┌─────────────────────────────────────────┐
│ 1. 使用者從內部 Gitea Releases 下載安裝檔 │
│ macOS → .dmg │
│ Windows → .exe（Inno Setup） │
│ Ubuntu → .AppImage │
└────────────┬────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ 2. 雙擊安裝檔 │
│ macOS: .dmg mount → 拖拉到 Applications │
│ 首次開啟跳 Gatekeeper 警告 │
│ → 右鍵 → 開啟（安裝頁文件說明） │
│ Win: .exe 安裝精靈（Inno Setup 預設流程） │
│ SmartScreen 警告 → 仍要執行 │
│ Linux: 給 .AppImage chmod +x → 雙擊 │
└────────────┬────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ 3. Wails 殼啟動 → 偵測是否首次執行 │
│ 首次：開啟安裝精靈（沿用原 installer UI） │
│ 後續：跳過，直接進主畫面 │
└────────────┬────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ 4. 安裝精靈執行以下步驟（有進度條）： │
│ a. 解壓 payload 到應用資料目錄 │
│ (mac: ~/Library/Application Support/ │
│ visiona-local/；Win/Linux 依慣例) │
│ b. 建立 Python venv（優先用內嵌 Python） │
│ c. pip install --no-index wheels/ │
│ （numpy / opencv / pyusb / KneronPLUS）│
│ d. 解壓 ffmpeg binary │
│ e. 解壓預置 .nef 模型 │
│ f. 平台特定步驟： │
│ - Win: 裝 WinUSB driver（跳 UAC） │
│ - Linux: 寫入 udev rules（跳 sudo） │
│ - Mac: ad-hoc codesign dylib │
│ g. 啟動 edge-ai-server 子行程 │
│ h. 等待 server ready（http://127.0.0.1:3721）│
└────────────┬────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ 5. 進入 First-Run 歡迎流程（見 5.2） │
└─────────────────────────────────────────┘
```
**關鍵驗收點：**
- 第 4 步 a-h 全部自動化，使用者無需任何 CLI 操作
- 若 Python fallback 失敗（系統無 Python），明確告知使用者到哪下載
- 若 Windows 拒絕 UAC，提供「手動安裝 driver」的指引
- 整個流程目標 ≤ 3 分鐘 / **上限 ≤ 5 分鐘**（一般硬體 + SSD）— 第四輪 R4-4 決策
## 5.2 First-Run 歡迎流程（對應 US-2）
```
┌─────────────────────────────────────────┐
│ Step 1 — 歡迎畫面 │
│ ┌─────────────────────────────────────┐ │
│ │ [visionA-local Logo（沿用 EAP）] │ │
│ │ │ │
│ │ 「邊緣 AI 推論，裝起來就能跑」 │ │
│ │ │ │
│ │ [開始使用] [稍後再說] │ │
│ └─────────────────────────────────────┘ │
└────────────┬────────────────────────────┘
│（點擊「開始使用」）
▼
┌─────────────────────────────────────────┐
│ Step 2 — 執行模式選擇 │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ 🟢 真實硬體 │ │ 🟡 Mock 模式 │ │
│ │ │ │（先看看） │ │
│ │ 需要 Kneron │ │ 無需硬體 │ │
│ │ KL720/KL730 │ │ 假裝置 + 假推論│ │
│ │ USB 裝置 │ │ │ │
│ │ │ │ │ │
│ │ [選擇] │ │ [選擇] │ │
│ └──────────────┘ └──────────────┘ │
│ │
│ 預設：真實硬體（依據 Q8） │
└────────────┬────────────────────────────┘
│
├─── 選真實硬體 ───▶ Step 3a（硬體偵測）
│
└─── 選 Mock ──────▶ Step 3b（Mock 準備）
┌─────────────────────────────────────────┐
│ Step 3a — 硬體偵測（真實模式） │
│ 「請插上 Kneron 裝置…」 │
│ [自動掃描 USB，持續 10 秒] │
│ ├ 成功：顯示偵測到的裝置卡片 │
│ │ [前往 Workspace] │
│ └ 失敗：顯示排錯清單 │
│ 1. 確認 USB 已插好 │
│ 2. 試試 USB 3.0 埠 │
│ 3. 重插一次 │
│ 4. 檢查驅動是否安裝 │
│ [重試] [切換 Mock 模式] │
└─────────────────────────────────────────┘
┌─────────────────────────────────────────┐
│ Step 3b — Mock 模式準備 │
│ 「已進入 Mock 模式，您將看到 3 個假裝置」 │
│ [進入 Dashboard] │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ 完成 → 進入 Dashboard │
│ 右上角顯示目前模式（真實 / Mock） │
│ 主視窗標題列 + sidebar 底部狀態列同步顯示模式│
└─────────────────────────────────────────┘
```
**關鍵驗收點：**
- AC-2.1：Mock 模式是一鍵選項（非預設）
- AC-2.2：進入 Mock 後 ≤ 30 秒看到假推論（首次）/ ≤ 15 秒（回訪）— 第四輪 R4-7 拆兩級
- AC-2.3：Mock 模式有明確視覺標記（主視窗標題列 + 首頁徽章 + sidebar 底部狀態列）
- AC-2.4：Mock 模式**不 spawn Python sidecar**，純前端 state + Go server（對應 nonfunctional §6.1 的 Mock idle RAM ≤ 600MB 預算）
- 三步都可「稍後再說」跳過，直接進 Dashboard
## 5.3 日常使用流程
### 5.3.1 典型使用會話（FAE 在客戶現場）
```
1. 使用者從 app 目錄或桌面捷徑開啟 visionA-local
↓
2. Wails 殼啟動 → 跳過 First-Run（已完成）
↓
3. 啟動 edge-ai-server 子行程（< 2 秒）
↓
4. 主視窗開啟 → Dashboard
↓
5. 使用者插上 Kneron USB
↓
6. Devices 頁自動顯示新裝置（WebSocket push）
↓
7. 使用者點「Connect」→ 進入 Workspace
↓
8. 選 webcam + 選模型 → 點 Start
↓
9. 看到 MJPEG 串流 + 推論 overlay
↓
10. demo 完畢 → 點 Stop → 關閉主視窗 → 程式退出（Q7 傳統式）
```
**關鍵驗收點：**
- 步驟 3 到步驟 9 整段 ≤ 30 秒
- 步驟 5 到步驟 6（USB 偵測）≤ 3 秒
- 步驟 7 到步驟 9（connect 到第一幀）≤ 10 秒
### 5.3.2 跨會話狀態持久化
> **路徑說明（第三輪 Q-E1 + 第四輪 R4-5）**：資料目錄名統一全小寫為 `visiona-local`（對齊 Bundle ID `com.innovedus.visiona-local` 與 Linux 檔案系統慣例）。macOS 採 OS 慣例路徑 `~/Library/Application Support/visiona-local/`；Windows 預期為 `%APPDATA%\visiona-local\`；Linux 預期為 `~/.local/share/visiona-local/` 或 `$XDG_DATA_HOME/visiona-local/`。以下以 `<APPDATA>` 表示該目錄。
| 狀態 | 儲存位置 | 是否跨會話保留 |
|------|---------|----------------|
| 上次選的模型 | `<APPDATA>/config.json` | ✅ 是 |
| 上次選的 webcam | `<APPDATA>/config.json` | ✅ 是 |
| 上次的模式（真實 / Mock） | `<APPDATA>/config.json` | ✅ 是 |
| 上傳的自訂模型 | `<APPDATA>/models/` | ✅ 是 |
| 推論歷史 / 日誌 | `<APPDATA>/logs/` | ✅ 是（滾動保留） |
| 語言偏好 | `<APPDATA>/config.json` | ✅ 是 |
| 深色模式 | N/A | 跟隨系統，無覆寫 |
### 5.3.3 快速操作流程（原 Tray 流程 — 已砍）
> **第三輪 Q-A 決策**：系統列 tray 已砍掉。原本透過 tray 提供的快速操作（顯示主視窗、Server 狀態、快速動作、模式切換、結束）改由以下方式提供：
>
> | 原 Tray 項目 | 新的入口 |
> |-------------|---------|
> | 顯示主視窗 | 桌面 / Dock / 工作列 icon（OS 原生行為） |
> | Server 狀態 | Dashboard 的 Server 狀態卡片 + sidebar 底部狀態列 |
> | 快速動作（新增裝置 / 上傳模型 / 開啟工作區）| 原生 menu bar：`File → New Device / Upload Model / Open Workspace` |
> | 模式切換（真實 / Mock）| Settings 一般分頁；或 Dashboard 右上角的模式指示器 |
> | 關於 | 原生 menu bar：`Help → About` |
> | 結束（⌘Q）| 原生 menu bar + OS 標準快捷鍵 |
>
> Q7 已決定「關閉視窗 = 結束程式」，搭配 tray 被砍，整體生命週期就是「打開 = 跑、關閉 = 結束」的傳統桌面 app 模式。
## 5.4 錯誤處理流程
### 5.4.1 Port 3721 被占用
```
Server 啟動失敗 → 顯示錯誤對話框：
「連接埠 3721 已被其他程式占用。
請關閉占用該埠的程式，或在 Settings 中變更 server 埠號。」
[設定埠號] [結束]
```
### 5.4.2 Python venv 建立失敗
```
First-Run 步驟 4b 失敗 → 顯示錯誤對話框：
「無法建立 Python 執行環境。
可能原因：
- 系統 Python 版本不符（需要 3.10+）
- 磁碟空間不足（需要 ~500MB）
- 權限不足
[檢視日誌] [重試] [結束]」
```
### 5.4.3 KneronPLUS wheel 安裝失敗
```
First-Run 步驟 4c 失敗 → 顯示錯誤對話框：
「KneronPLUS SDK 安裝失敗。
請確認：
- 已允許 UAC 提權（Windows）
- 已安裝 libusb（Linux：sudo apt install libusb-1.0-0）
[檢視日誌] [重試] [結束]」
```
### 5.4.4 Mac Gatekeeper 警告
```
首次開啟 → Mac 跳出「無法開啟，因為來自未識別的開發者」
→ First-Run 歡迎頁提供說明：
「第一次開啟時，請在 Finder 中對 visionA-local 按右鍵，
選擇『開啟』，然後確認警告。
這是因為 visionA-local 未購買 Apple notarization。」
```
### 5.4.5 Windows SmartScreen 警告
```
首次下載執行 → SmartScreen 跳出警告
→ 發佈說明頁提供引導：
「點選『更多資訊』→『仍要執行』。
這是因為 visionA-local 未購買 Windows 程式碼簽章。」
```
## 5.5 Single-instance 行為與第二次雙擊 UX（第四輪補）
**背景**：visionA-local 以 single-instance 模式運作（單一程式實例），避免多個 Wails 殼搶 Go server 的 127.0.0.1:3721 port。實作細節請參考 Architect 的 `04-architecture/lifecycle.md`（single-instance lock 章節）。
**PRD 層級要求的 UX 行為**：
| 情境 | 預期行為 | 驗收點 |
|------|---------|--------|
| 第一次雙擊 icon（無已開啟的 visionA-local） | 正常啟動，走 First-Run 或直達 Dashboard | 與 5.1 / 5.2 流程一致 |
| **第二次雙擊 icon（已有 visionA-local 在前景）** | **把既有視窗帶到前景 + focus**，**不開第二個視窗**、**不顯示錯誤** | 無閃爍、無崩潰 |
| **第二次雙擊 icon（已有 visionA-local 但視窗最小化 / 隱藏）** | **把既有視窗還原並帶到前景 + focus** | 使用者不會以為「怎麼沒反應」 |
| **第二次雙擊 icon（已有 visionA-local 但 Go server 已 crash）** | 第二個實例偵測到 lock 殘留但 server 不在，清理 lock 後正常啟動 | 不該無限卡住 |
**快捷鍵相關**：
- 原生 menu bar `File → 重啟 Server` 的快捷鍵為 **⌘Shift+R**（macOS）/ **Ctrl+Shift+R**（Win/Linux）— 第四輪 R4-6 決策：從原 `⌘R` 改為 `⌘Shift+R`，避免與瀏覽器 reload 的肌肉記憶衝突
- 原本規畫的 `⌘Shift+W` 取消（⌘W / ⌘4 已可關閉視窗）— 第四輪 R4-6 決策
- 其餘快捷鍵維持：`⌘Q` 結束、`⌘W` 關閉視窗（= 結束，Q7 傳統式）、`⌘,` 開 Settings、`⌘1-⌘4` 切換主導航
**第二次雙擊的具體 Design 規格待 Design Agent 在 `03-design/spec/` 補齊**（動畫時間、focus ring 表現、Dock icon bounce 等細節）。PRD 層級只定義行為意圖，不定義視覺細節。
## 5.6 OS 通知策略（第四輪 R4-8 決策）
visionA-local 採**分層通知策略**，不是所有事件都走原生 OS 通知，避免噪音與跨平台一致性問題。
| 事件 | 通知管道 | 理由 |
|------|---------|------|
| 裝置連線成功（USB 插入 + connect OK） | **App 內 toast**（右下角，auto-dismiss 3 秒）| 使用者 app 已在前景，OS 通知是多餘噪音；跨平台一致 |
| 裝置斷線（USB 拔出 / connect 失敗） | **App 內 toast**（右下角，auto-dismiss 5 秒 + 錯誤色）| 同上 |
| 模型上傳完成 | **App 內 toast** | 同上 |
| 推論開始 / 停止 | **狀態列更新 + 無 toast**（過於頻繁，改用持續性狀態指示） | 避免噪音 |
| First-Run 步驟完成 | **步驟條更新 + 無 toast** | First-Run 本身就是向導，不需額外通知 |
| **Server 崩潰**（Go server 意外退出）| **shell out 原生 OS 通知**（`osascript` on macOS / PowerShell `New-BurntToastNotification` 或 WinRT on Windows / `notify-send` on Linux）+ app 內錯誤對話框 | 重大錯誤，使用者可能切到其他視窗，必須確保看到 |
| **Python sidecar 崩潰**（推論 backend 掛了）| **shell out 原生 OS 通知** + app 內錯誤對話框 | 同上 |
| **致命錯誤**（無法啟動、依賴缺失）| **app 啟動對話框**（blocking） | 無 app 可用，必須擋住使用者 |
### 實作要求
- **App 內 toast** 沿用原 edge-ai-platform 的 `sonner` 或 shadcn toast 元件
- **原生 OS 通知** 採 shell out 策略（不引入 go-toast 等第三方 binding，避免增加依賴與打包複雜度）
- macOS：`osascript -e 'display notification "..." with title "visionA-local"'`
- Windows：PowerShell `New-BurntToastNotification` 或直接用 Wails 提供的 `runtime.MessageDialog`（如支援）
- Linux：`notify-send "visionA-local" "..."`
- 若 shell out 失敗（工具不存在），靜默 fallback 到 app 內錯誤對話框
- **權限要求**：macOS 首次顯示原生通知時會觸發系統通知權限請求，First-Run 需在文案裡提及「本 app 在出現嚴重錯誤時會通知你」
### 驗收點
- AC-7.1（新增）：裝置連/斷僅以 app 內 toast 呈現，不觸發系統通知
- AC-7.2（新增）：Go server 或 Python sidecar 崩潰時，使用者就算切到其他視窗也能透過系統通知得知
- AC-7.3（新增）：macOS 的通知權限請求時機在 First-Run 或首次崩潰時才觸發，不在 app 啟動時無緣無故詢問

163
local-tool/.autoflow/02-prd/nonfunctional.md Normal file
View File

@ -0,0 +1,163 @@
# 6. 非功能需求與驗收標準
## 6.1 效能需求（量化）
| 指標 | 目標值 | 上限值 | 測量方法 |
|------|--------|--------|---------|
| **安裝時間**（下載完成 → app 首屏）| ≤ 3 分鐘 | **≤ 5 分鐘**（硬性上限） | 全新機器 + SSD + 一般規格 CPU，計時從雙擊安裝檔到 Dashboard 顯示。**第四輪 R4-4 決策**：上限放寬至 5 分鐘（原 3 分鐘僅為目標值，考量到 Python runtime 解壓 + 5 個 wheel 離線 install 的實測預算）。 |
| **首次推論時間 — 首次安裝後第一次啟動**（app 首次開啟 → Mock 第一幀）| ≤ 20 秒 | **≤ 30 秒** | 首次啟動需觸發 Python sidecar 冷啟動、wheel 載入、模型 warmup。**第四輪 R4-7 決策**：首次推論拆為兩級目標。 |
| **首次推論時間 — 回訪（第 2 次以後）**（app 啟動 → Mock 第一幀）| ≤ 10 秒 | **≤ 15 秒** | 無需再解壓依賴，僅 Python sidecar + 模型載入。**第四輪 R4-7 決策**：回訪目標較首次嚴格。 |
| **實機接入時間**（插 USB → connect 成功）| ≤ 5 秒 | ≤ 10 秒 | 計時從 USB 插入到 Devices 頁顯示「Connected」 |
| **攝影機串流啟動時間**（按 Start → 第一幀）| ≤ 2 秒 | ≤ 3 秒 | 計時從 Start 按鈕點擊到第一幀畫面 |
| **Mock 模式 idle CPU 占用** | ≤ 3% | ≤ 5% | Mock 模式下 60 秒平均值（Mock 模式**不 spawn Python sidecar**，僅前端 state + Go server） |
| **Mock 模式 idle RAM 占用** | ≤ 500 MB | **≤ 600 MB** | Mock 模式下 60 秒平均值。**第四輪 R4-4 決策**：原 400/500MB 放寬至 500/600MB（Wails + WebView2/WKWebView + Go server 基底已約 350-450MB，扣掉 Python 後空間有限）。**注意**：Mock 模式不 spawn Python sidecar，因此不計入 Python runtime 的 ~150MB。 |
| **真實推論 RAM 占用** | ≤ 1 GB | ≤ 1.5 GB | 跑一個分類 + 一個偵測模型（含 Python sidecar） |
| **攝影機串流延遲 — 首次啟動串流**（capture → UI 顯示）| ≤ 200 ms | **≤ 250 ms** | MJPEG 時間戳比對；首次啟動 MJPEG pipeline warmup 較慢。**第四輪 R4-2 決策**。 |
| **攝影機串流延遲 — 穩定後**（capture → UI 顯示）| ≤ 120 ms | **≤ 150 ms** | MJPEG 時間戳比對；啟動 5 秒後的穩定值。**第四輪 R4-2 決策**：MJPEG 瀏覽器端 decode 不可能做到 100ms 以下，務實值為 150ms。 |
## 6.2 安裝檔大小需求
| 平台 | 目標值 | 上限值 | 組成 |
|------|--------|--------|------|
| macOS（x86_64 .dmg）| ≤ 220 MB | ≤ 300 MB | Wails shell + Go server + Next.js + Python wheels + ffmpeg + .nef + Python runtime |
| Windows（x86_64 .exe）| ≤ 200 MB | ≤ 300 MB | 同上 + WinUSB driver |
| Ubuntu（x86_64 .AppImage）| ≤ 200 MB | ≤ 300 MB | 同上 |
> **注意**：Architect Round 1 估算約 195-215 MB，在目標內。主要體積來自 ffmpeg（~40MB）+ Python wheels（~40MB）+ 預置模型（~73MB）。
## 6.3 零依賴需求
**核心需求**：使用者機器完全**不需要**預先安裝以下任何項目：
- ❌ 不需要 Python（內嵌 Python runtime + fallback 至系統 Python）
- ❌ 不需要 ffmpeg（內嵌靜態 binary）
- ❌ 不需要 KneronPLUS SDK（內嵌 wheel）
- ❌ 不需要 Node.js（前端已 embed 進 Go binary）
- ❌ 不需要 Docker
- ❌ 不需要 git
- ❌ 不需要任何開發工具
**唯一例外**：
- macOS / Linux：基本系統函式庫（glibc / libc 等標準元件）
- Windows：首次啟動需允許 UAC 以安裝 WinUSB driver
- Linux：首次啟動需 sudo 寫入 `/etc/udev/rules.d/99-kneron.rules`
## 6.4 離線可用需求
**核心需求**：除 `update-check`（本 MVP 已砍）之外，所有核心功能在**完全斷網**情況下必須正常運作，包含：
- ✅ 安裝過程（使用內嵌 wheels，`pip install --no-index`）
- ✅ First-Run 歡迎流程
- ✅ 裝置偵測 / connect / 推論
- ✅ 模型上傳 / 切換
- ✅ 攝影機串流
- ✅ 媒體上傳（圖片 / 影片）
- ⚠️ `/api/media/url`（yt-dlp）**例外**：需連網才能下載 YouTube 影片
## 6.5 相容性需求
### 6.5.1 作業系統（Q3 決定：都最新兩版）
| 平台 | 支援版本 | 架構 | 備註 |
|------|---------|------|------|
| macOS | 14 (Sonoma)、15 (Sequoia) | x86_64 | Q4 只做 x86_64，Intel Mac |
| Windows | 10、11 | x86_64 | Windows 10 需要 1809 以上（WinUSB） |
| Ubuntu | 22.04 LTS、24.04 LTS | x86_64 | 其他發行版不保證（用 AppImage 可能可以） |
**明確不支援**：macOS 13 以下、Windows 10 1809 以下、Ubuntu 20.04 以下、所有 ARM 架構、其他 Linux 發行版（Fedora、Arch 等）。
### 6.5.2 Kneron 硬體
- KL720（第一優先）
- KL730
- 未來其他 KL 系列視 KneronPLUS wheel 支援度
### 6.5.3 攝影機
- macOS：AVFoundation 能列到的 webcam 皆支援
- Windows：DirectShow / Media Foundation 能列到的 webcam 皆支援
- Linux：V4L2 能列到的 webcam 皆支援
## 6.6 安全性需求
**內部工具，安全模型較寬鬆**，但仍需滿足：
- ✅ Server 只監聽 `127.0.0.1`，**絕對不 bind 0.0.0.0**
- ✅ 無 CORS 允許任意 origin
- ✅ 使用者資料（模型、config）存在 OS 慣例目錄，非系統路徑（macOS：`~/Library/Application Support/visiona-local/`；Windows / Linux 依各自 OS 慣例，由 Architect TDD 定義）
- ❌ 無需 TLS（localhost 不需要）
- ❌ 無需認證（單人工具）
- ❌ 無需加密儲存（檔案系統權限足矣）
- ⚠️ Python sidecar 的 subprocess 呼叫必須做參數 escape，避免 injection
## 6.7 可維護性需求
- ✅ 日誌寫入 OS 慣例資料目錄下的 `logs/` 子目錄（macOS：`~/Library/Application Support/visiona-local/logs/`），滾動保留最近 7 天
- ✅ Crash 發生時 Go server 留下 stack trace 到 log file（本地，不上傳）
- ✅ server 狀態面板（沿用原 `server-status-dashboard`）可顯示目前依賴狀態
- ❌ 無遠端遙測 / 崩潰回報（Q12）
- ❌ 無 auto-update（Q6）
## 6.8 可用性需求（UX 層級）
### 6.8.1 本地化（Q13 決定）
- **中英雙語**：繁體中文（zh-TW）+ 英文（en）
- 首次啟動依系統語言判斷，可在 Settings 切換
- 所有 UI 字串、錯誤訊息、First-Run 文案都需雙語
### 6.8.2 主題（Q15 決定）
- **預設跟隨系統**（macOS appearance、Windows theme、Linux GTK theme）
- 使用者無法手動覆寫（簡化 Settings）
- **第三輪 Q-E3 決策**：因為沒有手動覆寫需求，Settings 不設「外觀」分頁；語言偏好併入「一般」分頁
### 6.8.3 無障礙（WCAG 2.2 AA **明確 scope 外**）
**第四輪 R4-3 決策**：WCAG 2.2 AA 正式合規**不是 MVP 目標**。內部工具、使用者是內部 FAE，使用者群體明確，不需要通過政府採購或公共部門的無障礙稽核。
- ✅ **盡力而為**：繼承 shadcn/Radix 元件提供的預設無障礙屬性（ARIA role、focus ring、keyboard nav）
- ✅ **盡力而為**：鍵盤可操作的主要流程（Tab navigation 可達 First-Run、Dashboard、Devices、Workspace 的核心按鈕）
- ❌ **不做**：WCAG 2.2 AA 正式稽核
- ❌ **不做**：螢幕閱讀器（VoiceOver / Narrator / NVDA）完整測試
- ❌ **不做**：色彩對比度驗證工具（axe / Lighthouse A11y）的正式通過
- ❌ **不做**：自訂快捷鍵衝突檢查
- ❌ **不做**：大字體 / 高對比 / 減少動態效果的偏好設定
**未來升級路徑**：若未來要發佈給外部客戶或政府單位，需補完整的 WCAG 2.2 AA 稽核與修正。本 MVP 不保證合規。
**本條也列入非目標**：見 [`vision-and-non-goals.md`](./vision-and-non-goals.md) 3.2.2 生命週期 / 營運相關段落（已補）。
## 6.9 可打包 / 可發佈需求
- ✅ 可從 CI（GitHub Actions 或類似）一鍵產出三平台安裝檔
- ✅ 可從單一 commit tag 觸發 release build
- ✅ 產出的安裝檔檔名含版本號：`visionA-local-1.0.0-macos.dmg` 等
- ✅ 發佈目標：內部 Gitea Releases 或 GitHub Releases（由使用者選擇）
- ❌ 不發佈到任何商店
## 6.10 總體驗收標準對照表
| 類別 | 指標 | 目標 / 上限 | 來源 |
|------|------|------|------|
| 效能 | 安裝時間 | 目標 ≤ 3 分鐘 / **上限 ≤ 5 分鐘** | 6.1 |
| 效能 | 首次推論時間（首次啟動）| 目標 ≤ 20 秒 / **上限 ≤ 30 秒** | 6.1 |
| 效能 | 首次推論時間（回訪）| 目標 ≤ 10 秒 / **上限 ≤ 15 秒** | 6.1 |
| 效能 | 實機接入時間 | 目標 ≤ 5 秒 / 上限 ≤ 10 秒 | 6.1 |
| 效能 | 串流延遲（首次）| 目標 ≤ 200 ms / **上限 ≤ 250 ms** | 6.1 |
| 效能 | 串流延遲（穩定後）| 目標 ≤ 120 ms / **上限 ≤ 150 ms** | 6.1 |
| 體積 | macOS 安裝檔 | ≤ 220 MB | 6.2 |
| 體積 | Windows 安裝檔 | ≤ 200 MB | 6.2 |
| 體積 | Ubuntu 安裝檔 | ≤ 200 MB | 6.2 |
| 資源 | Mock idle CPU | ≤ 3%（上限 5%）| 6.1 |
| 資源 | Mock idle RAM | ≤ 500 MB（**上限 600 MB**）| 6.1 |
| 依賴 | 完全零預裝 | 必須 | 6.3 |
| 離線 | 核心功能離線可用 | 必須 | 6.4 |
| 相容 | macOS 14/15 x86_64 | 必須 | 6.5 |
| 相容 | Windows 10/11 x86_64 | 必須 | 6.5 |
| 相容 | Ubuntu 22.04/24.04 x86_64 | 必須 | 6.5 |
| 語言 | 中英雙語 | 必須 | 6.8.1 |
| 主題 | 跟隨系統深色模式 | 必須 | 6.8.2 |
| 發佈 | CI 一鍵三平台 build | 必須 | 6.9 |
**第一次成功率（北極星指標）**：內部 FAE 在客戶現場首次安裝後 **5 分鐘內**順利跑出第一次推論的比例 ≥ 95%。（對應安裝時間上限 5 分鐘 + 首次推論上限 30 秒，合計仍在 5 分 30 秒內。）

68
local-tool/.autoflow/02-prd/pm-cross-review.md Normal file
View File

@ -0,0 +1,68 @@
# PM 交叉審閱報告
> 審閱者：PM Agent
> 日期：2026-04-11
> 審閱對象：Design 第三輪修訂版 + Architect 第三輪修訂版
> 基準：PRD v1.1（含第三輪決策 Q-A / Q-B / Q-C / Q-E1/E2/E3）
---
## ✅ 對齊的項目
- **6 個核心 User Story（US-1~US-5、US-7~US-9）**：Design 的 First-Run（spec/04）、Wireframes（spec/03）、狀態設計（spec/08）與 Architect 的 API 清單、依賴打包、lifecycle 章節，皆能找到對應落地。US-6（tray）已在 PRD v1.1 標註移除，兩端同步刪除。
- **IA 與 Settings 四分頁**：Design IA（4 主區 + 一般/硬體/模型/進階）與 PRD feature-inventory 4.2 完全一致；Workspace 升一級、外觀分頁取消並把語言併入一般分頁都正確落地。
- **資料目錄（macOS `~/Library/Application Support/visionA-local/`）**：PRD、Design First-Run、Architect TDD §6（Log 路徑）、lifecycle §2（single-instance lock）、api-endpoints §3（IPC port 檔案）全部一致，未見 `~/.visiona-local/` 殘留。
- **非功能需求落地**：Architect 的 packaging.md 預估 ~195-210MB（PRD 上限 300MB、目標 ≤ 220MB 內）、Python runtime 雙策略（PRD 6.3 的零預裝）、離線 wheel 安裝（PRD 6.4）、只 bind 127.0.0.1（PRD 6.6）、中英雙語 + 跟隨系統主題（PRD 6.8）皆完整對應。
- **三平台、x86_64、無簽章**：Architect D3/D4、packaging §1 與 PRD 6.5、release-strategy 一致。R3/R5 Gatekeeper / SmartScreen 的 workaround 已寫進 Design First-Run 歡迎頁 + `SignatureWarningNotice` 元件 + Architect packaging §2.5。
- **M1 一次清乾淨前端 cluster/relay UI（Q-C）**：Architect design-doc §5 M1-7 已明確列為 M1 必做，且 Design 02-pages-diff 的刪除清單一致。
- **Tray 整條已砍（Q-A）**：Design 05-tray.md 確認刪除、Architect `tray-and-lifecycle.md` 只保留 lifecycle 內容並加註、`server/internal/tray/` 列入 removed-code。
---
## ⚠️ 發現的問題
### 對 Design 的問題
- **D-01 [🟡 需修]** **sidebar 一級入口數量描述不一致**：PRD feature-inventory 4.3 寫「sidebar 為 **5 項一級入口**：Dashboard / Devices / Models / Workspace / Settings」，但 Design spec/01-IA §1.2 明確把 Settings 放在 sidebar **最下方並用 divider 與主導航區隔**（= 4 主 + Settings 特殊位置）。兩端語意其實一致，但字面上會引起工程師混淆。**建議 PM 端把 PRD 4.3 改為「4 個主導航 + Settings（底部獨立區）」與 Design 對齊**（由 PM 自行修）。
- **D-02 [🟡 需修]** **Mock 切換入口驗收條件未覆蓋 AC-2.4**：PRD AC-2.4 要求「Mock 與真實模式可隨時在 Settings 切換，切換不需重啟 app」。Design design-spec.md §「待確認 #4」列出切換入口為 Settings > 硬體 + Devices 頁右上 pill + First-Run Step 2，Wireframe 3.3 Devices 頁也有 pill，但 **沒有明確說「切換不需重啟」** 這個非功能條件。建議 Design 在 spec/08-states §8.7 的「切換 Mock/Real 模式」補一句：「切換透過 /api/system/restart 或純前端 state，無需關閉 app」，並與 Architect 確認該 API 行為。
- **D-03 [🟢 建議]** **US-3（AC-3.5 Windows UAC 說明 / AC-3.6 Linux udev 說明對話框）只散落在 First-Run Step 3 Phase 2B 的排錯清單**：PRD 明確要求「顯示說明對話框」，Design 只把這兩項做成「可點擊展開的排錯項目」。建議強化成 OS 偵測後的主動 modal（至少首次 connect 失敗時觸發一次），與 US-3 的 AC 更精準對齊。不做不至於違反 AC 文字，但體驗上可再好一點。
- **D-04 [🟢 建議]** **Workspace wireframe 缺少 AC-5.4「即時 FPS / 延遲 / CPU / RAM 占用」的明確位置**：spec/03-wireframes §3.4 Control 區只畫了 `Perf: FPS 24 / Latency: 42ms`，沒畫 CPU / RAM。建議在 Control Panel 下補一個小型資源監視區塊，或直接把 `performance-metrics` 元件畫進 wireframe，避免開發階段漏做。
### 對 Architect 的問題
- **A-01 [🔴 阻斷]** **R9 Plan B（Kneron 授權不過 → 首次啟動線上下載）沒有落地設計**：risks-and-mitigations R9 把 Plan B 寫成「改為首次啟動線上下載」，但 Architect 的 `dependency-bundling.md`、`packaging.md`、`build-pipeline.md` **完全沒有** 設計對應流程（例如：下載進度 UI、URL 設定、斷線重試、完整性 checksum、AppData 內的模型資料夾結構、跟 First-Run Step 1 的整合點）。這會讓「開發到一半才發現授權不過」變成**架構重做**的風險。**建議 Architect 補一份極簡的 R9 Plan B TDD**（不用實作，但要描述資料流與 fallback 時機），並且與 Design 討論 First-Run 要不要插入「下載模型」步驟（會影響 4.4 現有流程圖）。這一項直接影響能否安心進入開發。
- **A-02 [🟡 需修]** **Settings 頁 Server Port 改動缺 API 支援**：Design spec/03-wireframes §3.5「硬體」分頁有 `Server Port（預設 3721，衝突時可改）`，但 Architect 的 `api-endpoints.md` 保留的 `/api/system/*` 並沒有「變更 port」的 endpoint；packaging / lifecycle 也沒說明變更 port 之後 Wails 殼要怎麼重新連 WebView（因為 WebView URL 寫死在 lifecycle §1）。建議：(a) 增加 `POST /api/system/config` 或明確說明「port 只能從 Wails menu 改，改完要重啟 server」；(b) 在 TDD 補一段說明 port 衝突錯誤流程（PRD 5.4.1 有定義但 TDD 未對應）。
- **A-03 [🟡 需修]** **i18n 範圍未涵蓋 Wails 安裝精靈**：PRD 6.8.1 + Design spec/10 要求「所有 UI 字串、錯誤訊息、First-Run 文案都需雙語」，Architect `i18n.md` §1 雖然有寫「Wails app（安裝精靈、錯誤對話框）：Go 端 i18n map」，但 §2 之後只展開前端 locale 檔結構，**Go 端 i18n map 的具體實作未展開**（沒有檔案路徑、沒有 key 清單、沒有語系偵測方式）。建議補 §3「Go 端 i18n 實作」，至少說明：檔案位置、語系偵測 API、key 命名慣例。
- **A-04 [🟡 需修]** **idle 資源目標在 TDD 與 PRD 不一致**：PRD 6.1 要求 Mock idle CPU ≤ 3%（上限 5%）、RAM ≤ 400MB（上限 500MB）；Architect TDD §5 只寫「CPU < 5%、RAM < 500MB」——這是**上限**而非**目標**。會導致開發時只盯上限。建議 TDD §5 補上「目標值 / 上限值」兩欄與 PRD 對齊。
- **A-05 [🟢 建議]** **安裝時間目標（PRD 6.1 ≤ 3 分鐘 / 上限 5 分鐘）在 TDD 沒有對應的技術預算拆解**：Architect dependency-bundling / packaging 完全沒有「解壓 90MB python + pip install 5 個 wheel 要花多久」的估算。如果最後超過 5 分鐘，PRD 的北極星指標「5 分鐘內跑出第一次推論 ≥ 95%」會直接破功。建議 Architect 在 dependency-bundling.md 補一張「各步驟時間預算表」（解壓 / venv / pip install / 啟動 server / WebView load），即使是估算也好。
---
## ❓ 需要使用者或三方討論的問題
1. **R9 Plan B 什麼時候要做決定**：目前 R9 標為 P1 release blocker，但若等到 M6 才確認 Kneron 授權，屆時才發現要做 Plan B，可能要延宕 1-2 個月。**建議 Orchestrator 在進入 M1 前就請使用者 / Kneron 業務啟動授權溝通**，平行進行，不要等。
2. **port 衝突 UX 決策歸屬**：PRD 5.4.1 + Design 8.2 都畫了「更改 Port」按鈕，但 Architect 沒有對應 API。三方需要決定：(a) 做到底（加 API + 重啟流程）；(b) 簡化為「請使用者關閉占用程式後重啟」（砍掉按鈕）。Design / Architect 需同步。
3. **M1 端到端 smoke test 的驗收定義**：Architect M1-13 寫「Mock 模式看到 3 台假裝置跑推論，且 UI 完全沒有 cluster / relay / tunnel 入口」。建議使用者 / PM 確認這個就是 M1 的 Definition of Done，以免 M1 延伸到「連真實裝置也要通」。
---
## 結論
**是否可以進入開發階段？** — **有條件是**。
**條件清單（照順序處理）**：
1. **[阻斷] A-01**：Architect 補 R9 Plan B 的簡版設計（資料流 + First-Run 整合點），否則開發到後期有架構重做風險。
2. **[需修] D-02 / A-02**：Mock 切換與 Server Port 變更的 API / 重啟行為要三方對齊，否則 Wireframe 按鈕會變成空按鈕。
3. **[需修] A-03 / A-04**：Architect 補 Go 端 i18n 實作章節、TDD §5 效能目標對齊 PRD。
4. **[需修] D-01**：PM 自行把 PRD 4.3 sidebar 描述對齊 Design IA（5 項 → 4 主 + Settings）。
5. **[討論] Q1 Kneron 授權**：Orchestrator 在 M1 啟動前協助使用者聯繫 Kneron 平行確認，不要等到 M6。
以上條件完成後，三方文件可視為 ready，進入 Reviewer 審查 + 開發（M1）階段。其餘 🟢 建議項目可在 M1 / M2 迭代時處理，不作為開發阻斷。

142
local-tool/.autoflow/02-prd/release-strategy.md Normal file
View File

@ -0,0 +1,142 @@
# 7. 發佈與交付策略
## 7.1 發佈通路（Q 決定：內部 Gitea / GitHub Releases）
**決策**：
- ✅ **內部 Gitea Releases**（首選）
- ✅ **GitHub Releases**（備援 / 合作夥伴用）
- ❌ **不上** Mac App Store、Microsoft Store、Snap Store、Flatpak
**理由**：
- 內部工具性質，不需要商店觸達
- 商店上架需要 sandbox（App Store）、開發者帳號 / 簽章（所有商店），均已被 Q2 排除
- Gitea / GitHub Releases 提供版本管理與下載追蹤即可
## 7.2 發佈頻率
| 類型 | 頻率 | 觸發 |
|------|------|------|
| 主版本（1.0、2.0） | 1-2 次/年 | 重大功能加減 |
| 次版本（1.1、1.2） | 1 次/月 | 新功能 / 重大改進 |
| 修補版本（1.0.1）| 隨時 | Bug fix / 安全性 |
## 7.3 發佈產出物
每個 release 包含以下檔案：
| 檔名 | 平台 | 格式 | 預計大小 |
|------|------|------|---------|
| `visionA-local-{version}-macos-x64.dmg` | macOS 14/15 x86_64 | `.dmg` | ~220 MB |
| `visionA-local-{version}-windows-x64.exe` | Windows 10/11 x86_64 | Inno Setup `.exe` | ~200 MB |
| `visionA-local-{version}-linux-x64.AppImage` | Ubuntu 22.04/24.04 x86_64 | `.AppImage` | ~200 MB |
| `visionA-local-{version}-checksums.txt` | 全平台 | 文字 | < 1 KB（SHA256）|
| `RELEASE_NOTES.md` | 全平台 | Markdown | 依版本而異 |
**注意**：不提供 ARM 架構、不提供 `.deb` / `.rpm` / `.pkg`。
## 7.4 發佈前檢查清單（Launch Checklist）
每次 release 前必須通過：
### 功能面
- [ ] 三平台安裝檔可於對應 OS 成功安裝（手動測試）
- [ ] 三平台首次啟動可完成 First-Run 流程
- [ ] 三平台均可接 Kneron USB 並 connect 成功
- [ ] 三平台 Mock 模式可啟動並顯示假推論結果
- [ ] 三平台攝影機串流正常
- [ ] 三平台前端 cluster / relay / tray UI 已完全清除（**第三輪 Q-C 決策**，M1 必達）
### 效能面
- [ ] 安裝時間 ≤ 3 分鐘（測試機 SSD）
- [ ] 首次推論時間 ≤ 15 秒
- [ ] Mock idle CPU ≤ 3%、RAM ≤ 400 MB
- [ ] 安裝檔大小符合 6.2 節上限
### 相容性
- [ ] macOS 14 + 15 各測試一次
- [ ] Windows 10 + 11 各測試一次
- [ ] Ubuntu 22.04 + 24.04 各測試一次
### 文件
- [ ] RELEASE_NOTES.md 已撰寫
- [ ] 安裝指南更新（含 Gatekeeper / SmartScreen 警告處理）
- [ ] 內部 Wiki / Slack 通知已準備好
### 非需要項目（明確不做）
- ~~程式碼簽章~~（Q2）
- ~~notarization~~（Q2）
- ~~法律文件（Terms / Privacy）~~（內部工具）
- ~~商店審核~~
- ~~auto-update 清單~~（Q6）
## 7.5 發佈流程
```
1. 開發完成 → 合併到 main branch
2. 打 tag：git tag v1.0.0 && git push --tags
3. CI 觸發 → 三平台 build（GitHub Actions 或 self-hosted runner）
├─ macOS runner：wails build -platform darwin/amd64 → .dmg
├─ Windows runner：wails build -platform windows/amd64 → Inno Setup → .exe
└─ Linux runner：wails build -platform linux/amd64 → appimagetool → .AppImage
4. 產生 checksums.txt
5. 人工執行 Launch Checklist
6. 上傳到 Gitea / GitHub Releases
7. 內部公告（Slack channel / Email）：
- 新版本號
- 主要變更
- 下載連結
- 升級說明（因為沒 auto-update，需手動下載）
```
## 7.6 使用者升級路徑
因為 Q6 決定不做 auto-update：
```
1. 使用者從 Slack / Email 得知有新版
2. 手動到 Gitea / GitHub Releases 下載新版安裝檔
3. 安裝新版（舊版 config / 模型資料保留在 OS 慣例資料目錄；macOS：`~/Library/Application Support/visiona-local/`）
4. 首次啟動新版會自動讀取舊 config
```
**舊版本相容性**：
- config.json 結構必須向後相容（加欄位可以、改語意要寫 migration）
- 模型檔案格式不變（.nef 為 Kneron 標準）
- logs 目錄結構不變
## 7.7 Rollback 策略
若新版本爆出重大問題：
1. 在 Gitea / GitHub Releases 將該版本標記為 pre-release 或刪除
2. 內部通知：「請暫停升級 vX.Y.Z，改用 vX.Y.Z-1」
3. 使用者已升級者：手動下載舊版重裝（config 資料保留）
因為無 auto-update，rollback 成本相對低。
## 7.8 支援與回報
- **Bug 回報通路**：內部 Slack channel / Gitea Issues
- **Feature Request**：同上
- **文件**：內部 Wiki
- **無** SLA，best-effort 支援
## 7.9 長期維護策略
visionA-local 的維護預算應與 edge-ai-platform 主線共用：
- 核心業務邏輯（device / model / inference / camera）的修改同步從 edge-ai-platform cherry-pick
- visionA-local 特有的部分（installer、payload、tray、wails shell）獨立維護
- 目標：visionA-local 的**獨有程式碼 < 30%**，其餘都能與 edge-ai-platform 共享
## 7.10 非目標再次確認（發佈相關）
本章節再次強調發佈相關的非目標：
- ❌ 不上任何商店（Mac App Store / Microsoft Store / Snap Store 等）
- ❌ 不做程式碼簽章（macOS Developer ID / Windows EV cert）
- ❌ 不做 notarization
- ❌ 不做 auto-update
- ❌ 不做 telemetry / crash report
- ❌ 不做 license key
- ❌ 不做法律文件（Terms / Privacy Policy）— 因為是內部工具
- ❌ 不支援 ARM 架構（未來再評估）

198
local-tool/.autoflow/02-prd/risks.md Normal file
View File

@ -0,0 +1,198 @@
# 8. 風險與相依性
本章節整合 PM 視角的產品風險與 Architect Round 1 的技術風險。所有 R1-R5 原始編號沿用 Architect 的定義，PM 補充 P1-P5。
## 8.1 技術風險（來自 Architect Round 1，交叉引用）
### R1 — KneronPLUS Linux wheel 的 glibc / ABI 相容性
| 項目 | 內容 |
|------|------|
| 描述 | KneronPLUS Linux wheel 綁定特定 glibc 版本，可能無法在所有 Ubuntu 22.04 / 24.04 執行 |
| 可能性 | 高 |
| 影響 | 高（Linux 平台無法使用） |
| 緩解 | 實測 Ubuntu 22.04 + 24.04；若不過，在 6.5.1 相容性需求中限定版本；AppImage 內帶 libusb |
| PM 補充 | 若 R1 發生，可考慮 Linux 為 Phase 2（先發 Mac / Win），但不推薦——會破壞「三平台齊發」定位 |
### R2 — Windows WinUSB driver 需 UAC 同意
| 項目 | 內容 |
|------|------|
| 描述 | Windows 首次啟動需安裝 WinUSB driver，若使用者拒絕 UAC 則 Kneron 裝置無法使用 |
| 可能性 | 中 |
| 影響 | 高（Windows 平台功能失效） |
| 緩解 | First-Run 明確說明原因；提供「手動安裝 driver」的後援文件；若拒絕 UAC 則引導進 Mock 模式 |
| PM 補充 | US-3 AC-3.5 已包含此 edge case 的驗收標準 |
### R3 — KneronPLUS macOS wheel 可能只有 x86_64
| 項目 | 內容 |
|------|------|
| 描述 | 若 KneronPLUS macOS wheel 只有 x86_64 而無 arm64，M 系 Mac 會走 Rosetta（KneronPLUS dylib 抗議） |
| 可能性 | 中 |
| 影響 | 高（M 系 Mac 無法使用） |
| 緩解 | Q4 已明確決定「三平台都只做 x86_64」，使用者目前是 Intel Mac。使用者若有 M 系需求再加 |
| PM 補充 | **此風險已被 Q4 決策降級為低優先**，但需在發佈說明寫明「目前只支援 Intel Mac」 |
### R4 — 離線 wheel 安裝失敗（無 pip / ensurepip）
| 項目 | 內容 |
|------|------|
| 描述 | Ubuntu 有時不預裝 `python3-venv`，導致離線 wheel 安裝失敗 |
| 可能性 | 中 |
| 影響 | 中（Linux 首次啟動失敗） |
| 緩解 | 沿用 `installer/app.go` 的 `installPython3Venv()` fallback，需 sudo；或引導使用者手動裝 |
| PM 補充 | Q1 決定 A + B（內嵌 Python + fallback 系統 Python），R4 的主要解法是優先走內嵌路線 |
### R5 — 預置模型 .nef 的授權限制（**發佈前必須確認**；對應 Architect R9）
| 項目 | 內容 |
|------|------|
| 描述 | Kneron 預置的 .nef 模型可能限制 re-distribution |
| 可能性 | 低—中（未知） |
| 影響 | 中（影響 73MB 預置模型的可打包性） |
| **狀態（第三輪 Q-B 決策）** | **不再是「阻斷開發」的風險**。使用者決定先**假設可重新散布**，開發階段繼續把預置模型內嵌到 payload 與打包流程中，讓 MVP 開發可以往前推進。**但這是一個「發佈前必須確認」的風險**——在正式 release 到 Gitea / GitHub Releases **之前**，PM 必須完成授權確認；否則不能對外發佈。 |
| **狀態（第四輪 R4-1 決策）** | 使用者決定**暫不主動問 Kneron**，維持第三輪「B4 假設可重新散布」路線繼續開發。理由：主動問若得到拒絕會立刻變阻斷；先開發到 M5/M6 有成品再談授權，談判籌碼與確認時機點更務實。**發佈前 gate 維持生效**——`v1.0.0` 到 Gitea / GitHub Releases 前必須完成授權確認，這條不變。此風險維持 P1 追蹤項。 |
| 緩解 | 1) 開發階段：先假設 OK，持續內嵌並測試打包；2) **發佈前 gate**：PM 完成 Kneron 官方 re-distribution 授權確認；3) 若最終不允許：fallback 方案改為「首次啟動線上下載預置模型」（會破壞完全離線承諾，需讓使用者知情），或移除預置模型、要求使用者自備 .nef。Architect TDD 需在 M2 前備齊 fallback 方案的極簡設計（對應 pm-cross-review A-01）。 |
| PM 行動 | **在 release `v1.0.0` 前**必須完成授權確認。第四輪決策：不主動聯繫 Kneron，但持續把本風險列入 `progress.md` 未解決問題，發佈前 gate 觸發時再啟動 |
| 追蹤 | 列入 `progress.md` 的「未解決問題」直到確認為止 |
### R11 — 發佈通路（內部 Gitea Releases / GitHub Releases）尚未確認可用（第四輪新增）
| 項目 | 內容 |
|------|------|
| 描述 | PRD 第 7 章（release-strategy）假設發佈到 Innovedus 內部 Gitea Releases 或 GitHub Releases。實際上這兩個通路是否已備好（repo 存在、release API 可用、存儲配額夠放 3 平台 × 每版本約 600MB 安裝檔）都尚未確認 |
| 可能性 | 中 |
| 影響 | 中（發佈日前才發現會導致臨時找替代通路，如 S3 直接連結 / 內部檔案伺服器） |
| 等級 | **P2 追蹤項** |
| 緩解 | 1) M1 啟動後第一週由 DevOps / PM 確認 Gitea Releases 可用性；2) 若不可用：退而求其次用 GitHub Releases（私有 repo）或 S3 pre-signed URL；3) 發佈腳本需支援至少兩種通路 |
| PM 行動 | M1 Week 1 完成通路確認並更新 release-strategy.md |
| 追蹤 | 列入 `progress.md` 的「未解決問題」直到確認為止 |
### R12 — CI runner 三平台齊備度未知（第四輪新增）
| 項目 | 內容 |
|------|------|
| 描述 | 三平台 build 需要 macOS / Windows / Linux CI runner。Innovedus 目前是否已有齊備的 self-hosted runner 或付費 GitHub Actions 額度尚未確認。macOS runner 尤其稀缺且昂貴 |
| 可能性 | 中—高 |
| 影響 | 中（若 runner 不齊備，會退化成「本地手動 build」，拖慢每次 release 時程，且不利於回歸測試） |
| 等級 | **P2 追蹤項** |
| 緩解 | 1) M1 啟動後第一週由 DevOps / PM 盤點 runner 現況；2) 短期可接受本地手動 build（開發者本機當 runner），但要有明確的 build SOP 與產物驗證腳本；3) 長期需在 M4-M5 前備好三平台自動化 runner，避免 release 時塞車 |
| PM 行動 | M1 Week 1 完成 runner 盤點，若缺則把補齊 runner 列為 M2/M3 的 infra 工作項 |
| 追蹤 | 列入 `progress.md` 的「未解決問題」直到確認為止 |
## 8.2 產品風險（PM 補充）
### P1 — 使用者因 Gatekeeper / SmartScreen 警告放棄安裝
| 項目 | 內容 |
|------|------|
| 描述 | Q2 決定不買程式碼簽章，Mac 會跳「unidentified developer」警告，Windows 會被 SmartScreen 攔截 |
| 可能性 | 高（每個新使用者第一次都會碰到） |
| 影響 | 中（有技術背景的使用者能克服，但非技術背景可能卡住） |
| 緩解 | First-Run 歡迎頁 + 發佈說明頁提供清晰的警告處理步驟；錄製 GIF / 截圖說明 |
| 責任 | Design Agent 負責 First-Run UX；PM 負責內部文件 |
### P2 — 內部 FAE 不知道有新版（因為無 auto-update）
| 項目 | 內容 |
|------|------|
| 描述 | Q6 決定不做 auto-update，舊版本可能永遠在外面跑，bug / 新功能無法觸達使用者 |
| 可能性 | 中 |
| 影響 | 中 |
| 緩解 | 每次 release 透過 Slack / Email 強力推播；在 Dashboard 下方顯示目前版本號，鼓勵自查；未來考慮加「check for updates」手動按鈕（不是 auto-update） |
| PM 行動 | 建立內部發佈通知機制 |
### P3 — 內部工具沒有 telemetry 導致無法知道使用者卡住在哪
| 項目 | 內容 |
|------|------|
| 描述 | Q12 決定不做遙測，若使用者首次安裝失敗可能直接放棄，PM / 工程師無感 |
| 可能性 | 中 |
| 影響 | 中（無法持續優化安裝體驗） |
| 緩解 | 每次新版發佈後主動問 5-10 位內部 FAE 的回饋；建立 Slack channel 接收主動回報；日誌會寫本地，請 FAE 遇問題時抓 log 送上來 |
| PM 行動 | 建立「新版發佈後主動 follow-up」的標準作業 |
### P4 — Scope creep：有人要求加回非目標清單裡的功能
| 項目 | 內容 |
|------|------|
| 描述 | 開發過程或發佈後，可能有人要求加 auto-update / 簽章 / cluster 回來 |
| 可能性 | 中 |
| 影響 | 高（會破壞「瘦身 50%」目標） |
| 緩解 | 本 PRD 第 3.2 節列出明確非目標；任何要求回加的功能必須回到三方討論重新評估 |
| PM 行動 | Orchestrator 主持三方討論時需嚴守非目標邊界 |
### P5 — KneronPLUS SDK 升版導致 wheel 不相容
| 項目 | 內容 |
|------|------|
| 描述 | KneronPLUS 未來新版 SDK 可能改 API / 改 ABI，導致 visionA-local 舊版裝置失效 |
| 可能性 | 低 |
| 影響 | 高（長期維護風險） |
| 緩解 | 固定 KneronPLUS wheel 版本，跟 edge-ai-platform 主線同步；升版前做 regression test |
| PM 行動 | 與 Architect 約定 KneronPLUS 版本升級的 review 流程 |
## 8.3 相依性
### 8.3.1 外部相依（核心）
| 相依 | 用途 | 風險 |
|------|------|------|
| KneronPLUS SDK（wheel） | 裝置 / 推論 | R1, R3, R5, P5 |
| Python 3.10+ | 執行 KneronPLUS | R4 |
| ffmpeg（LGPL build） | 攝影機 / 影片處理 | 低（已有靜態 binary） |
| libusb-1.0 | USB 存取 | R1（Linux） |
| Wails v2 | 桌面殼 | 低（已使用於 edge-ai-platform） |
| Go 1.26 | Server | 低 |
| Next.js 16 / React 19 | 前端 | 低 |
| yt-dlp | `/api/media/url` | 低（Q10 決定保留） |
### 8.3.2 內部相依
| 相依 | 用途 | 備註 |
|------|------|------|
| edge-ai-platform 主線 | 程式碼複製來源 | 需維持與主線的核心業務邏輯同步 |
| Innovedus 內部 Gitea | 發佈通路 | **R11 追蹤**：需確認 Release 機制可用 |
| 內部 CI runner（macOS / Windows / Linux） | 三平台 build | **R12 追蹤**：需確認三平台 runner 都可用 |
### 8.3.3 人員相依
| 角色 | 備註 |
|------|------|
| Architect | 負責打包與依賴策略 |
| Backend / Frontend 工程師 | 負責程式碼瘦身與改寫 |
| Design | 負責 First-Run UX、主視窗 menu bar 規格（原 Tray 規格已於第三輪 Q-A 取消） |
| PM | 負責 Kneron 授權確認（R5 緩解） |
| 內部 FAE | 首次發佈後的 5-10 位 beta 使用者 |
## 8.4 風險矩陣
```
影響 ↑
高 │ R1 R3 P5
│
│ R2 P1 P4
中 │ R4 R5 P2 P3
│
低 │
└───────────────────────────────→ 可能性
低 中 高
```
## 8.5 需要 Architect Round 2 驗證的風險點
進入第二輪架構設計前，Architect 必須實測並回報：
1. **R1**：在 Ubuntu 22.04 / 24.04 x86_64 實測 KneronPLUS wheel，確認 glibc 相容
2. **R3**：`lipo -info` 檢查 KneronPLUS macOS .dylib 的架構（確認是 x86_64 only 還是 Universal）
3. **R4**：實測 Ubuntu 22.04 離線 wheel 安裝流程，確認 venv 能建立
4. **R5**：PM 需在**發佈前**（非 Architect Round 2）提供 Kneron re-distribution license 確認結果；Round 2 只需確認「若發生 fallback，線上下載方案的技術可行性」
Architect Round 2 TDD 必須包含這四個風險的實測結果與緩解方案落地。
## 8.6 PM 需要進一步確認的事項（寫入 progress.md 未解決問題）
1. **R5 授權確認（發佈前 gate；P1）**：Kneron 預置 .nef 模型可否 re-distribution？需向 Kneron 官方詢問。**發佈 v1.0.0 前必須有結論**，開發階段先假設可行。**第四輪 R4-1 決策**：不主動聯繫，維持第三輪 B4 路線繼續開發，發佈前再啟動。
2. **R11 內部 Gitea Releases 機制（P2）**：是否已可用？是否需要申請新 repo？是否有儲存配額足以放 3 平台 × 每版本約 600MB？**第四輪 R4 新增**，M1 Week 1 前確認。
3. **R12 CI runner（P2）**：Innovedus 是否已有三平台 runner？若無，需評估自建 / GitHub Actions 成本。**第四輪 R4 新增**，M1 Week 1 前盤點。

74
local-tool/.autoflow/02-prd/strategy.md Normal file
View File

@ -0,0 +1,74 @@
# 1. 產品策略與定位
## 1.1 產品願景（模擬新聞稿）
> **標題：visionA-local 讓 Kneron AI 邊緣推論「裝起來就能跑」**
>
> **副標題**：為 Innovedus FAE 與 Kneron 開發者打造的單機桌面工具，不用架 server、不用裝 Python、不用連網
>
> 以往要讓客戶看一場 Kneron KL720 / KL730 的即時推論 demo，FAE 得扛一台預先設定好的筆電，祈禱客戶現場的網路、Python、KneronPLUS SDK、ffmpeg、驅動都沒問題。只要其中一個出包，demo 就得延期。
>
> visionA-local 把整套 edge-ai-platform 的能力打包成一顆單機桌面 app。下載、雙擊安裝、開啟——三分鐘內就能看到攝影機串流 + 推論 overlay。所有依賴都內嵌在安裝檔裡，完全離線也能用。
>
> 「我上禮拜到客戶現場，對方 IT 環境鎖得死緊，連 pip install 都被擋。以前這種狀況我只能道歉重約，這次我點一下 visionA-local，十分鐘後就開始 demo 了。」—— 一位 Innovedus 內部 FAE
>
> visionA-local 支援 macOS、Windows、Ubuntu 三平台，透過內部 Gitea Releases 發放給 Innovedus 團隊與合作客戶。v1.0 今日釋出。
## 1.2 核心問題
| 問題 | 目前痛點 | visionA-local 的解法 |
|------|----------|---------------------|
| **環境依賴地獄** | FAE / 開發者要預先裝 Python 3.12、建 venv、pip install KneronPLUS wheel、裝 ffmpeg、設 USB 權限，每個環節都可能失敗 | 一鍵安裝檔內嵌所有依賴，使用者機器零預裝需求 |
| **客戶現場網路不穩 / 被鎖** | 原 edge-ai-platform 要跑在 server 上，FAE 現場得架 Docker、設反向代理 | 桌面 app，localhost 跑就好，不需網路、不需 Docker、不需 root |
| **多人系統搬回單人用** | edge-ai-platform 為多人共享設計，FAE 一個人用很重 | 砍掉 cluster / relay / tunnel / token 認證，UI 更簡單 |
| **沒硬體就體驗不到** | 沒 Kneron 板就完全無法試用 | Mock 模式零硬體入口，產品經理也能玩 |
## 1.3 與 edge-ai-platform 的差異定位
| 面向 | edge-ai-platform | visionA-local |
|------|------------------|--------------|
| 部署形態 | 伺服器 / 容器（EC2 + Docker + nginx） | 單機桌面 App（macOS / Windows / Ubuntu） |
| 網路模型 | 多人可遠端連線（含 relay / tunnel / cluster） | 只跑 localhost，一人一機 |
| 安裝體驗 | Ops 手動部署、curl 腳本、需先裝 ffmpeg / Python | 一鍵 GUI 安裝檔，內嵌所有依賴 |
| 多裝置策略 | 支援 cluster（多 Kneron 叢集） | 單機可接多顆 USB，但不做 cluster |
| 使用場景 | 共享平台、遠端存取、多人協作 | 個人開發、現場 POC、離線 demo |
| 更新策略 | CI/CD + Docker image push | 使用者手動從 Gitea 下載新版 |
| 憑證與認證 | relay token + hwid | 無（localhost） |
## 1.4 價值主張
**一句話**：「裝起來像一般 app、離線也能跑、接上 Kneron 就推論。」
**三個支柱**：
1. **零依賴**：使用者機器完全不需要預先安裝任何東西
2. **零網路**：完全離線可用（唯一例外：可選的 update-check）
3. **零學習成本**：接上 USB → App 自動偵測 → 點一下就跑
## 1.5 OKR（內部工具導向，不追求成長 / 營收指標）
| Objective | Key Results |
|-----------|-------------|
| **O1：讓 Innovedus FAE 能在任何客戶現場 3 分鐘內開始 demo** | KR1：全新機器（無預裝）從下載安裝檔到開啟首屏 ≤ 5 分鐘<br>KR2：從 app 開啟到 Mock 模式跑出第一幀推論 ≤ 30 秒<br>KR3：插上 Kneron USB 到 connect 成功 ≤ 10 秒 |
| **O2：把 edge-ai-platform 的重複程式碼瘦身 50%** | KR1：cluster / relay / tunnel / deploy / docker 相關程式碼全部刪除<br>KR2：server / frontend 程式碼行數較原專案減少 ≥ 30%<br>KR3：安裝檔單平台 ≤ 500MB（目標 ~200MB） |
| **O3：建立可重複發佈的內部工具流程** | KR1：三平台安裝檔能從 CI 自動產出<br>KR2：首次發佈內部 Gitea Releases 後，至少 5 位內部 FAE 成功安裝並回報可用 |
## 1.6 成功指標（護欄指標 vs 體驗指標）
**體驗指標（追求極大化）：**
- 安裝時間（下載完成 → 首屏）：目標 < 3 分鐘，上限 < 5 分鐘
- 首次推論時間（app 開啟 → Mock 第一幀）：目標 < 15 秒，上限 < 30 秒
- 實機接入時間（插 USB → connect 成功）：目標 < 5 秒，上限 < 10 秒
**護欄指標（不能惡化）：**
- Mock 模式 idle CPU 佔用 ≤ 5%
- Mock 模式 idle RAM 佔用 ≤ 500 MB
- 安裝檔單平台大小 ≤ 500 MB
- 完全斷網時，除 update-check 外所有功能必須正常運作
## 1.7 北極星指標（內部工具）
由於不是對外商品，北極星指標不追求成長類數據，改用**可用性**為核心：
> **「內部 FAE 在客戶現場第一次 demo 成功率 ≥ 95%」**
「第一次成功」定義為：**首次安裝後 5 分鐘內順利跑出第一次推論**，不需要聯繫作者 debug。

136
local-tool/.autoflow/02-prd/user-research.md Normal file
View File

@ -0,0 +1,136 @@
# 2. 目標使用者與使用情境
## 2.1 Persona
### P1 — Innovedus 內部 FAE（主要 Persona，MVP 優先服務）
| 項目 | 內容 |
|------|------|
| 名字 | Arthur（化名） |
| 角色 | Innovedus 資深應用工程師 |
| 使用情境 | 帶筆電到客戶現場做 Kneron KL720 / KL730 推論 demo |
| 目標 | 不踩坑地開啟工具，接上 USB，立刻跑推論 |
| 痛點 | 客戶現場網路可能被擋、pip install 可能失敗、Python 環境可能衝突、ffmpeg 可能沒裝 |
| 技術素養 | 高（熟悉 CLI、Python、Docker） |
| 頻率 | 每週 1-3 次 |
| 一句話 | **「我希望打開筆電、雙擊 app、插 USB，就能 demo，不要再為了環境浪費客戶時間。」** |
### P2 — 外部開發者 / 評估客戶（次要 Persona）
| 項目 | 內容 |
|------|------|
| 名字 | Dora（化名） |
| 角色 | 剛拿到 Kneron 開發板的嵌入式 / AI 工程師 |
| 使用情境 | 評估 Kneron KL 系列是否適合自家專案 |
| 目標 | 不花一整天搞環境，快速看到「我的模型跑在 Kneron 上是什麼感覺」 |
| 痛點 | KneronPLUS SDK 安裝步驟繁瑣、文件分散、踩坑後找不到解答 |
| 技術素養 | 高，但對 Kneron 生態不熟 |
| 頻率 | 評估期 1-2 週內高頻，之後看決策 |
| 一句話 | **「我想用自己的 .nef 模型在 Kneron 上跑起來，不要先讀 200 頁文件。」** |
### P3 — Solution Architect / PM（第三順位 Persona）
| 項目 | 內容 |
|------|------|
| 名字 | Sam（化名） |
| 角色 | Innovedus / 合作夥伴的解決方案架構師或產品經理 |
| 使用情境 | 向客戶 / 內部高層介紹 Kneron 能做什麼，手邊沒有硬體 |
| 目標 | 用 Mock 模式看到「產品會長什麼樣」，不需要任何技術前置作業 |
| 痛點 | 不會寫 code、沒硬體、無法自己跑 demo |
| 技術素養 | 中（會用終端機但不寫程式） |
| 頻率 | 每月 1-2 次 |
| 一句話 | **「我要一個零摩擦的 demo 環境，能跑 Mock 就好，我只是要讓人看到願景。」** |
## 2.2 核心 User Stories（6 個關鍵情境）
### US-1：第一次安裝
**身份**：任意 Persona
**情境**：剛拿到 visionA-local 的下載連結，手邊是全新一台機器
**敘述**：
> 身為一名 Innovedus FAE，我希望下載安裝檔、雙擊、按幾下「下一步」，就能在不開啟 terminal、不輸入任何指令的情況下完成安裝，並在 3 分鐘內看到 app 首屏。
**驗收標準**：
- AC-1.1：下載 `.dmg` / `.exe` / `.AppImage`，無 terminal 操作可完成安裝
- AC-1.2：整個安裝過程（解壓 + 依賴設定）≤ 3 分鐘（一般硬體 + SSD）
- AC-1.3：安裝完成後，系統中出現 visionA-local app icon（Applications / 開始功能表 / 應用程式清單）
- AC-1.4：**即使使用者機器完全沒裝 Python / ffmpeg / KneronPLUS，仍能成功安裝並啟動**
- AC-1.5：首次啟動若需要管理員權限（Windows WinUSB driver、Linux udev rules），必須明確告知使用者原因
- AC-1.6：Mac 第一次開啟若出現 Gatekeeper 警告，app 內必須提供「右鍵 → 開啟」的引導說明（因為不做 notarization）
### US-2：Mock 模式試玩
**身份**：Solution Architect / PM（P3）
**情境**：想向高層 demo 產品能力，手邊沒有 Kneron 硬體
**敘述**：
> 身為一名 Solution Architect，我希望啟動 app 後能立刻進入 Mock 模式，看到 3 個假裝置、假的推論流在跑，不用接任何硬體，也不用研究怎麼切換模式。
**驗收標準**：
- AC-2.1：First-Run 流程中 Mock 模式是「一鍵進入」選項（非預設）
- AC-2.2：進入 Mock 模式後，≤ 30 秒內可看到假的裝置列表 + 假的推論結果
- AC-2.3：Mock 模式下，UI 必須有明確視覺區隔（主視窗標題列 / 首頁徽章 / sidebar 狀態列都要有 mock 標記）
- AC-2.4：Mock 與真實模式可隨時在 Settings 切換，切換不需重啟 app
### US-3：連實體 Kneron 裝置
**身份**：Innovedus FAE（P1）、外部開發者（P2）
**情境**：帶著 Kneron KL720 / KL730 USB dongle，想立刻 connect
**敘述**：
> 身為一名 FAE，我希望插上 Kneron USB 後，app 自動偵測到裝置、顯示型號與韌體版本，點一下「Connect」就能進入工作區開始推論。
**驗收標準**：
- AC-3.1：插入 USB 後，≤ 3 秒 app 偵測到裝置並顯示在 Devices 頁
- AC-3.2：偵測結果包含：裝置型號、韌體版本、序號、連線狀態
- AC-3.3：從「偵測到」到「connect 成功」的操作 ≤ 5 秒
- AC-3.4：connect 失敗時必須顯示具體原因（driver 問題 / 權限問題 / USB 3.0 問題），並提供排錯步驟
- AC-3.5：**Windows 第一次連接若需 UAC 安裝 WinUSB driver，必須顯示說明對話框**
- AC-3.6：**Linux 第一次連接若需寫入 udev rules，必須顯示說明對話框**
### US-4：切換 / 上傳模型
**身份**：外部開發者（P2）
**情境**：想把自己訓練的 .nef 模型換上去試跑
**敘述**：
> 身為一名開發者，我希望能從預置模型列表挑一個、或直接拖拉我的 .nef 檔進 app，不用手動複製檔案到特定資料夾、不用設環境變數。
**驗收標準**：
- AC-4.1：Models 頁列出所有預置模型（至少分類 / 偵測 / 臉辨各一顆）
- AC-4.2：支援拖放 .nef 檔到視窗任何地方觸發上傳
- AC-4.3：支援點「Upload」按鈕開啟原生 file picker
- AC-4.4：上傳成功後模型立刻出現在列表，可馬上切換
- AC-4.5：模型檔案預設存在 OS 慣例的應用資料目錄（macOS：`~/Library/Application Support/visiona-local/models/`；Windows / Linux 依 OS 慣例，由 Architect TDD 定義），使用者可查看但不需直接操作
### US-5：跑即時攝影機推論
**身份**：FAE（P1）
**情境**：要向客戶展示「接上 webcam + Kneron，就能即時做物件偵測」
**敘述**：
> 身為一名 FAE，我希望在 Workspace 頁選一顆 webcam、選一個推論模型、按下 Start，看到 MJPEG 即時串流搭配推論 overlay 顯示偵測結果。
**驗收標準**：
- AC-5.1：Workspace 頁能列出系統中所有可用的 webcam
- AC-5.2：選擇 webcam + 模型後，按 Start 在 ≤ 3 秒內看到第一幀
- AC-5.3：推論結果以 overlay（方框 / 標籤 / 信心度）形式顯示在串流上
- AC-5.4：能顯示即時 FPS、延遲、CPU / RAM 占用
- AC-5.5：按 Stop 能即時停止串流與推論，不留殘影
> **已移除：原 US-6「從 Tray 快速控制」**
>
> 第三輪 Q-A 決策砍掉系統列 tray。理由：Q7 已決定「關閉視窗 = 結束程式」，使 tray 失去背景常駐價值；加上跨平台圖資產與 Wails tray 踩坑成本高。所有快速控制改由主視窗原生 menu bar + sidebar 提供。
## 2.3 延伸情境（MVP 包含但非核心 Story）
- **US-7**：上傳影片 / 圖片做離線推論（對應 `/api/media/upload/*`）
- **US-8**：貼 YouTube / 網路影片 URL 做推論（對應 `/api/media/url`，Q10 決定保留，需打包 yt-dlp）
- **US-9**：查看系統依賴狀態與 server 日誌（對應原 `server-status-dashboard` / `server-log-viewer`）
## 2.4 使用者旅程地圖（First-Run 場景）
| 階段 | 行為 | 感受 | 潛在痛點 | visionA-local 的解法 |
|------|------|------|----------|---------------------|
| 認知 | 從同事 / 內部公告得知有這個工具 | 期待 | 怕環境難搞 | 發佈說明寫明「零預裝、三分鐘安裝」 |
| 下載 | 從內部 Gitea Releases 下載 | 中性 | Mac 不知道該下哪個 | 下載頁清楚列出三平台檔名 |
| 安裝 | 雙擊安裝檔，跟指示走 | 若順利：放心；若跳警告：焦慮 | Mac Gatekeeper 警告、Win SmartScreen 攔截 | 發佈說明頁 + First-Run 歡迎頁有「看到警告？點這裡」的引導 |
| First-Run | 選擇模式（真實 / Mock） | 好奇 | 不知道該選哪個 | Mock 作為「無硬體入口」強調「不用接設備也能玩」 |
| 第一次成功 | 看到第一幀推論結果 | 驚喜 | — | 「3 分鐘就看到結果」—— 這就是價值 |
| 日常使用 | 打開 → 接 USB → 推論 → 關閉 | 滿意 | 若每次都要重新設定則挫敗 | Settings 記住上次偏好 |

86
local-tool/.autoflow/02-prd/vision-and-non-goals.md Normal file
View File

@ -0,0 +1,86 @@
# 3. 產品願景與非目標
## 3.1 產品願景
**visionA-local 是一顆「裝起來像一般桌面 app」的 Kneron AI 邊緣推論工具，讓任何人在任何機器上都能三分鐘內開始推論。**
我們相信：內部工具也應該有「消費級產品」的使用體驗。環境依賴、連網要求、管理員權限——這些讓 edge-ai-platform 難以在客戶現場順利跑起來的摩擦點，通通要在 visionA-local 消失。
## 3.2 非目標（Non-Goals）— 明確列出 visionA-local **不做** 的事
以下功能在 MVP 以及可預見的 v1.x 範圍內**都不會實作**。列出非目標是為了避免開發過程中出現 scope creep，也讓三方討論時有明確界線。
### 3.2.1 網路 / 多人協作相關 — 全部不做
| 非目標 | 為什麼不做 |
|--------|-----------|
| **Cluster / 多裝置叢集管理** | 單機工具不需要叢集。cluster API、cluster 頁面、叢集 workspace 全部刪除 |
| **Relay / tunnel / 遠端連線** | 只跑 localhost，沒有遠端存取的需求。relay token、tunnel client、hwid 全部刪除 |
| **多人協作 / 權限管理** | 一人一機，無帳號、無權限、無 ACL |
| **Gitea URL 整合** | 原本用於雲端 relay 註冊，local 版不需要 |
### 3.2.2 生命週期 / 營運相關 — 全部不做
| 非目標 | 為什麼不做 |
|--------|-----------|
| **Auto-update（自動更新）** | 使用者 Q6 明確決定不做。使用者需手動從 Gitea Releases 下載新版 |
| **程式碼簽章 / notarization** | 使用者 Q2 明確決定都不買（macOS Developer ID $99/年 + Windows EV cert $300-600/年）。內部工具可接受 Gatekeeper / SmartScreen 警告 |
| **Telemetry / 崩潰回報** | 使用者 Q12 明確決定不做。沒有匿名使用追蹤、沒有崩潰上傳 |
| **License key / 啟用機制** | 內部工具不需要防外流機制 |
| **WCAG 2.2 AA 正式合規**（第四輪 R4-3）| 使用者明確決定不做稽核。僅保留 shadcn/Radix 提供的預設無障礙屬性（盡力而為）。未來要發佈給外部客戶或政府單位時再補。詳見 [`nonfunctional.md`](./nonfunctional.md) §6.8.3 |
### 3.2.3 平台 / 架構相關 — 暫不做（但保留未來擴充空間）
| 非目標 | 為什麼不做 | 未來可能性 |
|--------|-----------|-----------|
| **ARM 架構支援** | 使用者 Q4 決定：三平台都只做 x86_64（使用者目前是 Intel Mac） | 之後有需求可加 macOS arm64 + Linux arm64 |
| **Mac App Store 上架** | 內部工具，且 App Store 需要 sandbox 限制 USB 存取 | 無計畫 |
| **Microsoft Store 上架** | 同上 | 無計畫 |
| **Snap / Flatpak** | 發佈流程過重，AppImage 已涵蓋 | 無計畫 |
| **macOS 13 以下 / Windows 10 以下 / Ubuntu 20.04 以下** | 使用者 Q3 決定：只支援各平台最新兩版 | 無計畫 |
### 3.2.4 功能相關 — 刻意砍掉
| 非目標 | 為什麼不做 |
|--------|-----------|
| **韌體燒錄 / Flash** | 使用者 Q9 明確決定砍掉。`server/internal/flash/` 整包刪除，相關 UI 也移除 |
| **系統列 Tray（常駐圖示）** | **第三輪 Q-A 決策**：Q7 已決定「關閉視窗 = 結束程式」，Tray 失去背景常駐價值；加上跨平台圖資產（.icns / .ico / .png@各 DPI）與 Wails tray 踩坑成本高，CP 值不划算。`server/internal/tray/` 整包刪除，GUI controller 亦無需保留 |
| **多 Kneron dongle cluster 協作** | 可以同時接多顆，但不做叢集協調 |
| **Kneron 以外的硬體支援** | 本工具專為 Kneron KL 系列設計 |
### 3.2.5 商業 / 營運相關 — 全部不做
| 非目標 | 為什麼不做 |
|--------|-----------|
| **商業模式 / 訂閱制 / IAP** | 內部工具，零商業化需求 |
| **廣告** | 同上 |
| **使用者帳號 / 登入** | 單機工具，無帳號 |
| **雲端同步 / 備份** | 所有資料存本機（macOS：`~/Library/Application Support/visiona-local/`；Windows / Linux 待 Architect 補慣例路徑），不上雲 |
| **分享 / 協作功能** | 不支援匯出 share link 給同事 |
| **產品定價** | 免費（內部工具） |
| **法律文件（Terms / Privacy Policy）** | 內部工具，但若未來要發佈給外部客戶需補 |
## 3.3 非目標的交叉引用
- **Architect Round 1** Section 6「要砍掉的程式碼清單」列出具體路徑，與本節 3.2.1、3.2.4 對應。
- **Design Round 1** Section 1「前端頁面去留」列出要砍的 `/clusters` 頁面與 `cluster-*` 元件，與本節 3.2.1 對應。
- **功能清單**（[`features/feature-inventory.md`](./features/feature-inventory.md)）用 ✅ / ❌ 標示每個 API 與頁面的去留，這是本節的完整對照表。
## 3.4 「如果有人要求加這些功能怎麼辦？」
當 MVP 開發過程中，若有人（使用者、FAE、其他工程師）提出要加上任何非目標裡的功能：
1. **先指向本節**：「這在 PRD 的非目標清單裡，MVP 不做。」
2. **如果真的有充分理由**：回到三方聯合討論，重新評估是否把某項從非目標移出。
3. **絕對不要**：私下塞進 MVP 範圍。一旦破壞非目標邊界，瘦身 50% 程式碼的目標就守不住了。
## 3.5 非目標的風險
列出非目標本身也有風險：
| 風險 | 可能情境 | 緩解 |
|------|---------|------|
| **使用者因 Gatekeeper / SmartScreen 警告而放棄安裝** | 不做程式碼簽章的後果 | First-Run 文件 / 歡迎頁清楚說明「點右鍵開啟」的步驟 |
| **沒 auto-update 導致舊版永遠在外面跑** | 不做自動更新的後果 | 透過內部 Slack / Email 通知新版，每次新版本都要求使用者手動更新 |
| **沒 telemetry 導致無法知道使用者在哪裡卡住** | 不做遙測的後果 | 依賴主動回報（內部 Slack channel）、定期 user interview |
| **不支援 ARM Mac 會讓 M 系使用者要跑 Rosetta（效能 + 穩定性問題）** | 只做 x86_64 的後果 | 使用者目前是 Intel Mac，m 系需求出現時再評估 |

189
local-tool/.autoflow/03-design/design-analysis-round1.md Normal file
View File

@ -0,0 +1,189 @@
# visionA-local 設計分析（第一輪）
> Design Agent · 第一階段三方聯合討論 · 2026-04-10
> 本文件為「分析」而非「規格」，目的是盤點現況、指出差異、收斂疑問。
---
## 1. 原 frontend 的盤點（edge-ai-platform）
### 1.1 現有頁面（`src/app/`）
| 路由 | 用途 | 去留 |
|------|------|------|
| `/`（Dashboard） | 概覽：模型數、裝置數、連線數、活動時間軸 | ✅ 保留，但需拿掉 cluster 相關統計 |
| `/models` | 模型庫：上傳、切換、比對 `.nef` | ✅ 保留 |
| `/devices` | USB Kneron 裝置列表、連線狀態、Flash | ✅ 保留 |
| `/clusters` | 叢集列表 / 建立叢集 | ❌ 砍 |
| `/workspace/[deviceId]` | 單裝置工作區：攝影機 + 模型 + 推論 | ✅ 保留（核心頁面） |
| `/workspace/cluster` | 叢集工作區 | ❌ 砍 |
| `/settings` | 設定頁 | ✅ 保留，需重新設計（見下） |
### 1.2 現有元件分類
| 分類 | 元件 | 去留 |
|------|------|------|
| `camera/` | camera-feed, camera-controls, camera-overlay, source-selector, camera-inference-view, batch-image-thumbnails | ✅ 全保留 |
| `devices/` | device-card, device-list, device-health-card, flash-dialog, flash-progress, device-connection-log, device-status | ✅ 全保留 |
| `models/` | model-card, model-grid, model-filters, model-upload-dialog, model-detail, model-comparison-dialog | ✅ 全保留 |
| `inference/` | inference-panel, classification-result, confidence-slider, performance-metrics, video-progress | ✅ 全保留 |
| `cluster/` | cluster-card, cluster-list, cluster-create-dialog, cluster-performance | ❌ 全砍 |
| `dashboard/` | stat-card, activity-timeline, connected-devices-list | ✅ 保留（拿掉 cluster 欄位） |
| `layout/` | sidebar, header, connection-status, help-button | ✅ 保留但需改寫（見第 2 節） |
| `onboarding-dialog.tsx`, `guided-tour.tsx` | 新手引導 | ✅ 保留並強化（First-Run） |
| `relay-token-sync.tsx` | Relay token 同步 | ❌ 砍 |
| `server-log-viewer.tsx`, `server-status-dashboard.tsx` | 後端狀態 | ✅ 保留（桌面 app 尤其需要） |
| `theme-sync.tsx`, `lang-sync.tsx`, `store-hydration.tsx` | 基礎設施 | ✅ 保留 |
### 1.3 Sidebar 改動
原 5 項導航去掉 `/clusters`，變成 4 項：Dashboard / Models / Devices / Settings。Logo 字母 `E` 應換成 visionA-local 品牌識別。
---
## 2. 從「網頁工具」到「桌面 app」的 UX 差異
| 維度 | 原 Web 版行為 | 桌面 app 應做的調整 |
|------|-------------|-------------------|
| **視窗外觀** | 瀏覽器 tab，有 URL bar、書籤列 | 原生視窗、無 URL bar、使用系統 window chrome；mac 可考慮 frameless + traffic lights |
| **啟動方式** | 使用者打開瀏覽器輸入 localhost:3721 | 雙擊 app icon 即開；可選開機自啟動（預設關） |
| **路由表達** | URL 是使用者心智模型 | URL 隱藏在內部，導航完全靠 sidebar；移除 deep link 依賴 |
| **背景常駐** | 關掉分頁 = 關掉工具 | 關閉視窗 ≠ 結束程式：收進 tray，server 持續運作 |
| **檔案互動** | 上傳透過 `<input type=file>` | 支援拖放到視窗任一處、支援「以 visionA-local 開啟」系統關聯 `.nef` / 圖片 |
| **選單列** | 瀏覽器選單 | 原生 menubar：File / Edit / View / Devices / Help，含快捷鍵 |
| **快捷鍵** | 瀏覽器佔用大量快捷鍵 | 釋放 ⌘N/⌘W/⌘, 等，對應到桌面 app 常見動作 |
| **主題** | 跟隨 Tailwind theme，手動切換 | 預設跟隨系統（light/dark/auto），記住偏好 |
| **通知** | 瀏覽器 Notification API（需授權） | 原生 OS 通知（mac Notification Center / Win toast / Linux libnotify） |
| **更新** | F5 就是最新 | 需要 in-app update 提醒（沿用 Wails updater 或自建） |
| **字級與密度** | 預設 web 字級 | 桌面 app 可略緊湊，但仍要遵守 44px 觸控目標（平板模式） |
---
## 3. 首次啟動體驗（First-Run）流程草案
使用者下載 `.dmg` / `.exe` / `.AppImage` → 安裝 → 第一次打開。建議流程（最多 3 步，可跳過）：
```
Step 1 — 歡迎畫面
• visionA-local logo + 一句話 value prop
• "開始使用" / "稍後再說"
Step 2 — 執行模式選擇
• 🟢 真實硬體模式：插上 Kneron USB 裝置即可開始
• 🟡 Mock 模式：沒有硬體也能探索功能（預設選項，降低門檻）
• 可隨時在 Settings 切換
Step 3 — 硬體偵測（僅真實模式）
• 自動掃描 USB 裝置
• 成功 → 顯示偵測到的裝置卡片，CTA「前往 Workspace」
• 失敗 → 顯示排錯清單（驅動、權限、USB3、重插）+「切換 Mock 模式」備案
完成後 → 進入 Dashboard，guided-tour 可選擇啟動
```
**設計重點：**
- 不強迫註冊、不要 email、不要網路。這是離線工具。
- Mock 模式作為「我先看看」的無摩擦入口，降低首次挫敗。
- 硬體偵測失敗要**主動給解法**，不要只顯示紅字。
---
## 4. Tray 互動設計建議
### 狀態圖示（menubar / systray）
| 狀態 | 圖示 | 說明 |
|------|------|------|
| Server 運行中，有裝置連線 | 🟢 實心 logo | 正常 |
| Server 運行中，無裝置 | ⚪ 淺色 logo | Idle |
| Server 啟動中 | 🔵 動態 pulse | Loading |
| Server 錯誤 | 🔴 logo + 驚嘆號 | 需使用者處理 |
| Mock 模式 | logo + 小 "M" badge | 與真實模式視覺區隔 |
### 點擊行為（平台差異）
| 平台 | 左鍵 | 右鍵 |
|------|------|------|
| macOS | 直接展開選單（mac 慣例，無左右之分） | — |
| Windows | 叫出主視窗（Win 慣例） | 展開選單 |
| Linux/GNOME | 展開選單（行為差異大，以選單為主） | 展開選單 |
### 選單項目（統一內容）
```
▸ 顯示 visionA-local ⌘0
▸ Server 狀態：Running (localhost:3721) [唯讀]
─────────
▸ 快速動作
├ 新增裝置…
├ 上傳模型…
└ 開啟工作區
─────────
▸ 模式：● 真實 ○ Mock [可切換]
▸ 開機自動啟動 [checkbox]
─────────
▸ 關於 visionA-local
▸ 檢查更新…
▸ 結束 ⌘Q
```
---
## 5. 跨平台一致性的取捨
**原則：視覺統一 × 互動遵循平台慣例。**
| 項目 | 策略 |
|------|------|
| 色彩 / 字型 / 間距 / 元件樣式 | 跨平台完全一致（Design Tokens 統一） |
| 主視窗標題列 | mac frameless + traffic lights；win/linux 用標準 title bar（避免自畫 close button 的坑） |
| 快捷鍵修飾鍵 | mac 用 ⌘、win/linux 用 Ctrl；由 menu 定義，不手動寫字串 |
| 右鍵選單 | 原生 context menu（Wails runtime 提供） |
| 檔案對話框 | 原生 file picker，不自畫 |
| 通知 | 原生 OS 通知，訊息格式統一 |
| Tray 圖示尺寸 | mac 16pt template、win 16×16/32×32、linux 22×22，各自獨立資產 |
| 字型 | 跟隨系統字型（mac SF Pro、win Segoe UI、linux Inter/Ubuntu） |
**刻意不一致的地方：** 不要做自定義 title bar、不要覆寫原生選單，越原生越好。
---
## 6. 需要 PM / Architect 回答的問題
### 給 PM
1. **目標使用者**：主要是 Kneron 工程師內部使用？還是要給客戶 demo？這影響 First-Run 的技術門檻設定。
2. **Mock 模式的完整度**：Mock 是否要提供預錄的推論結果影片？還是可以完全用假資料？
3. **多語系**：原專案有 i18n（`useTranslation`），local 版要支援哪些語言？繁中 only 還是 en+zh？
4. **使用者資料**：模型、裝置設定存哪？`~/Library/Application Support/visionA-local/` 這類 OS 慣例目錄？
5. **錯誤回報**：是否要內建 feedback / 錯誤回報機制（匿名 telemetry）？
### 給 Architect
1. **單例鎖**：同一台機器同時開多個 visionA-local 視窗時，是否共用同一個後端 server？需要 single-instance lock。
2. **Port 衝突處理**：3721 被佔用時的 fallback 策略？UI 怎麼呈現？
3. **Tray 實作**：Wails v2 的 tray API 在 linux 上支援度如何？有無需要 systray fallback？
4. **檔案關聯**：要不要註冊 `.nef` 為 visionA-local 可開啟？這要寫進 installer。
5. **深色模式偵測**：Wails 能否偵測系統主題變更並即時 push 給前端？
6. **原生選單**：Wails 的 menu API 跨平台一致性如何？還是要各平台寫一份？
---
## 7. 需要使用者本人決定的設計向問題
| # | 問題 | 選項 |
|---|------|------|
| 1 | **品牌識別** | A. 直接沿用 edge-ai-platform 既有視覺（字母 E），只換名字 / B. 做一個新的 visionA-local logo 與色系 / C. 先用臨時 wordmark，上線前再處理 |
| 2 | **深色模式策略** | A. 預設跟隨系統 + 可手動覆寫（推薦） / B. 只提供 dark（技術工具常見） / C. 只提供 light |
| 3 | **首次啟動引導** | A. 強制走完 3 步歡迎流程 / B. 只顯示歡迎畫面，可一鍵跳過 / C. 完全跳過，直接進 Dashboard，用 tooltip 引導 |
| 4 | **Mock 模式預設** | A. 第一次啟動預設 Mock（零門檻）/ B. 第一次啟動預設真實硬體 / C. 強制使用者選擇 |
| 5 | **視窗關閉行為** | A. 關閉 = 收進 tray，server 繼續（像 Docker Desktop）/ B. 關閉 = 結束程式 / C. 讓使用者在 Settings 選擇 |
| 6 | **開機自啟動** | A. 預設關，使用者可開 / B. 首次啟動時詢問 / C. 預設開 |
| 7 | **多語系範圍** | 繁中 only / 繁中 + 英文 / 全部沿用原專案語言 |
| 8 | **Dashboard 去 cluster 後的排版** | A. 維持 4 個 stat card，把 cluster 換成別的指標（例：累計推論次數）/ B. 減為 3 個 stat card，讓版面更寬鬆 |
| 9 | **Tray 是否可選關閉** | A. Tray 是核心體驗，強制常駐 / B. Settings 可關閉 tray，改為傳統 app 模式 |
| 10 | **Settings 頁面改造程度** | A. 僅移除 relay/cluster 相關設定 / B. 重新設計為桌面 app 風格（分頁式：一般/硬體/模型/外觀/進階） |
---
## 下一步建議
1. 使用者先回答第 7 節的 10 個問題（尤其 1, 2, 3, 4, 5）
2. 並行進行：Architect 回答第 6 節的技術問題
3. 第二輪我會產出 IA（資訊架構圖）、First-Run 流程 wireframe、Tray 互動規格、Settings 分頁結構草案
4. 第三輪再進入完整 Design Tokens + 元件規格 + HTML Prototype

152
local-tool/.autoflow/03-design/design-cross-review.md Normal file
View File

@ -0,0 +1,152 @@
# Design 交叉審閱報告
> 審閱者：Design Agent｜日期：2026-04-11（第三輪文件完成後）
> 審閱對象：PM PRD（`02-prd/`）、Architect TDD + Design Doc（`04-architecture/`）
> 立場：從 UX 角度檢視產品需求與技術方案是否會衝擊使用者體驗
---
## ✅ 對齊的項目
1. **三方都確認砍掉 tray**：PRD §3 非目標、TDD §8（`tray-and-lifecycle.md`）、Design §5 一致。
2. **macOS 資料目錄統一為 `~/Library/Application Support/visiona-local/`**（Q-E1）：PRD `user-flows.md`、Architect `architecture-overview.md §4.2`、Design `04-first-run.md §4.1` 路徑一致。
3. **Workspace 升 sidebar 一級**（Q-E2）：PRD feature-inventory、Design IA、Architect code-reuse-plan 三處都標註。
4. **Mock 模式預設關閉、需明確選擇**：PRD AC-2.1、Design `04-first-run.md §4.4`、Architect `deviceMgr.mockMode` flag 一致。
5. **Settings 4 分頁結構**（Q-E3）：PRD、Design 一致採「一般／硬體／模型／進階」。
6. **首次啟動體驗可跳過**：PRD `user-flows.md §5.2`、Design `04-first-run.md §4.2` 都明確三步皆可略過。
---
## ⚠️ 發現的問題
### 對 PM 的問題
- **D→PM-01 [🟡]** **「首次推論 ≤ 15 秒」的 AC 與 First-Run 三步流程衝突。**
PRD `nonfunctional.md §6.1` 的驗收值寫「app 啟動 → Mock 第一幀 ≤ 15 秒」，但 Design `04-first-run.md` 的首次流程是**歡迎 → 模式選擇 → 硬體偵測（真實模式時要掃 10 秒）**，在真實模式下光硬體掃描 timeout 就 10 秒，不可能 15 秒到第一幀。建議：把 AC 拆成「首次（含 First-Run）≤ 30 秒」與「回訪（跳過 First-Run）≤ 15 秒」兩個指標，否則測試會一律 fail。
- **D→PM-02 [🟡]** **`user-flows.md §5.3.1` 步驟 3「啟動 Go server < 2 秒」與 TDD `tray-and-lifecycle.md §4.1` 的 `waitHealthy(10s)` 不一致。**
PM 寫「< 2 秒」，Architect 給自己留了 10 秒 timeout。Design 需要知道真實值才能決定 First-Run 是否要插 skeleton／splash。建議 PM 與 Architect 對齊，Design 才能設計正確的 loading 體驗。
- **D→PM-03 [🟢]** **Error flow `5.4.1` Port 3721 被佔用的文案與 Architect 不符。**
PRD 寫「請關閉占用該埠的程式，或在 Settings 變更 port」，但 TDD `tray-and-lifecycle.md §3.2` 的 `pickPort()` 會**自動挑 3722、3723...**，根本不需要使用者介入。兩邊敘述衝突，Design `08-states.md` 我暫時沿用 PRD 版，但若採 Architect 自動挑 port，應改成 info toast「已改用 port 3722」。
- **D→PM-04 [🟢]** **`nonfunctional.md §6.8.3` 寫「不做額外無障礙驗證」，與 Design `09-accessibility.md` WCAG 2.2 AA 承諾衝突。**
Design 規格第三輪明確寫 WCAG 2.2 AA、鍵盤 tab 順序、ARIA label。建議 PRD 在非功能需求同步把 a11y 拉到「必達」等級，或 Design 降級；兩邊必須一致。
- **D→PM-05 [🟢]** **Non-goals 文字微矛盾。** PRD `feature-inventory.md` 寫「原生 menu bar（File → New Device / Upload Model）」，但 `vision-and-non-goals.md` 暗示「不做 quick action」。menu bar 其實就是 quick action 的一種，建議 PM 把「不做 tray」與「有 menu bar」的界線在 non-goals 裡寫清楚，避免未來有人誤解成「連 menu bar 都不能做」。
### 對 Architect 的問題
- **D→Arch-01 [🔴]** **完整冷啟時間沒有明確預算，影響 First-Run AC。**
Architect `TDD.md §5` 只寫「冷啟 < 5 秒」，但三層程序（Wails → Go server → 首次 scan 才 spawn Python sidecar）的疊加時間沒拆開。Design 需要知道：
- Wails WebView 載入 Next.js：? 秒
- Go server `waitHealthy`：最多 10 秒
- Python sidecar 首次 spawn + KneronPLUS import：? 秒（實測一下，KneronPLUS 通常要 2-3 秒）
若總和超過 5 秒，Design `04-first-run.md §4.5 Phase 1` 的「掃描 USB 進度條」需要改成「**準備硬體子系統中...**」以免使用者誤以為 USB 掃描很慢。**請 Architect 在 M1 後補上實測數字。**
- **D→Arch-02 [🔴]** **Port picking 導致使用者書籤／歷史的 URL 不穩。**
`tray-and-lifecycle.md §3.2` 決定「3721 被佔 → 往上挑 3722、3723」，但 WebView 是 `http://127.0.0.1:{port}/`。使用者**不會**直接開瀏覽器書籤 localhost（Wails 殼包住 WebView），這對一般使用者 OK，但對「進階使用者想用 Chrome DevTools 連」「Settings 要顯示實際 port」的情境要設計出口。
**Design 建議**：在 Settings > 進階新增唯讀欄位「目前 Server Port：3722」+「複製」按鈕；Dashboard Server Status 卡片也顯示實際 port。TDD 目前只寫「Server logs 印 warning」不夠。
- **D→Arch-03 [🟡]** **Single-instance 第二次雙擊的 UX 未定義。**
`tray-and-lifecycle.md §2.3` 說收到 `/ipc/raise` 會 `WindowShow(ctx)` 浮到前面。Design 需要確認：
1. 第二個程序啟動是**完全靜默**（只 raise，沒有任何提示）還是**顯示 toast**（「已有另一個 visionA-local 在執行中」）？
2. macOS 從 Dock click 的行為由 Cocoa 處理，但 Linux AppImage 每次都是新程序，體驗不一致——Design 建議三平台統一走「靜默 raise + 可選 toast」。
3. 如果 `raiseExistingInstance()` 失敗（例如 IPC port 讀不到），目前邏輯是覆寫 lock、視為新程序——這會造成使用者看到「兩個視窗」，**非常糟糕**。建議改為「失敗即顯示錯誤 modal + 退出」。
- **D→Arch-04 [🟡]** **Python sidecar crash 的 UI 呈現缺失。**
`tray-and-lifecycle.md §4.3` 寫「Python sidecar 空閒 N 分鐘自動 kill、崩潰時 Go server 自動重啟最多 3 次」。Design 需要知道：
1. 重啟那 1-2 秒使用者會看到什麼？目前的推論畫面會卡住／白屏？
2. 3 次失敗後呈現的錯誤頁需要內容（Design `08-states.md` 只有通用 Critical error template，沒有 sidecar-specific）。
3. 自動 kill（閒置省記憶體）後下一次使用者點推論，Design 需要顯示「正在重新啟動推論引擎...」spinner，否則 Start 按鈕按下後會有 2-3 秒無回應。
**建議 Architect 新增事件 `POST /ws/server-logs` 類型 `sidecar.state` 讓前端訂閱**，Design 才能做對應 UI。
- **D→Arch-05 [🟡]** **Python 雙策略（A 內嵌 / B 系統）切換沒有 UI 入口。**
`dependency-bundling.md §1.5` 寫可透過 `--python-mode=bundled|system` CLI flag 切換，但使用者不會跑 CLI。Design 規格 Settings > 進階 應該有「Python 執行模式：內嵌（目前）／ 系統／ 自動」的唯讀顯示 + 重設按鈕。**Design 這邊會補 wireframe，但需要 Architect 確認前端能讀 `.installed` meta 的 API（目前 `/api/system/deps` 是否涵蓋？）。**
- **D→Arch-06 [🟡]** **資料目錄遷移／升級情境未處理。**
Architect 第三輪把 macOS 資料目錄從 `~/.visiona-local/` 改到 `~/Library/Application Support/visiona-local/`（Q-E1），但 **`edge-ai-platform` 舊使用者**可能已有 `~/.visiona-local/` 的資料。雖然 visionA-local 是新專案沒有「升級」概念，但**如果使用者曾經裝過 edge-ai-platform 的 local 模式**（有些人可能有），啟動時要不要偵測舊路徑、詢問是否遷移？Design 建議：**M1 範圍內不處理，但 First-Run 增加一段說明「若你之前用過舊版 visionA，請手動搬移 `~/.visiona-local/` 到新路徑」**。Architect 是否同意不自動遷移？
- **D→Arch-07 [🟢]** **`watchServer()` 健康檢查頻率 10 秒對 UX 太慢。**
`tray-and-lifecycle.md §4.2` 寫每 10 秒 healthcheck、失敗 3 次才判定掛掉，代表使用者最糟要等 **30 秒**才看到錯誤。建議縮短為「每 3 秒、失敗 2 次」＝ 6 秒內可感知。
- **D→Arch-08 [🟢]** **macOS 第二個程序的 `⌘N`「新增視窗」語意未定義。**
砍掉 tray 後，`feature-inventory.md §4.5` 提到 menu bar 有「File → New Device」。但 macOS 慣例 File menu 常有「New Window (`⌘N`)」——我們是單例 app，這個快捷鍵要完全拿掉還是改成「新增裝置」？Design 建議改成「New Device (`⌘N`)」避免衝突。
---
## 📋 R9 Plan B 的 First-Run 下載流程草案
若 Kneron 不允許 re-distribution，預置 `.nef` 無法內嵌，首次啟動必須線上下載 ~73MB 模型。Design 設計以下 fallback UX：
**流程修改：** 在現有 First-Run Step 2（模式選擇）與 Step 3（硬體偵測）之間**插入一個新步驟 2.5「下載預置模型」**。
```
Step 1 歡迎 → Step 2 模式選擇 → [NEW] Step 2.5 下載模型 → Step 3 硬體偵測 → Dashboard
```
**Step 2.5 Wireframe：**
```
┌─────────────────────────────────────────────────────┐
│ [略過 →] │
│ │
│ 下載預置 AI 模型 │
│ 首次使用需要下載約 73 MB 的範例模型 │
│ │
│ ┌──────────────────────────────────────┐ │
│ │ 📦 fd_mask.nef 14 MB ✓ │ │
│ │ 📦 yolov5s.nef 18 MB ⟳ │ │
│ │ 📦 resnet50.nef 22 MB … │ │
│ │ 📦 mobilenet.nef 8 MB … │ │
│ │ 📦 tiny_yolo.nef 11 MB … │ │
│ └──────────────────────────────────────┘ │
│ │
│ 整體進度：[■■■■□□□□□□] 40% (29 MB / 73 MB) │
│ 預估剩餘：45 秒 │
│ │
│ 來源：Innovedus 內部 CDN │
│ │
│ ⓘ 若要完全離線使用，請聯絡 IT 取得完整安裝包 │
│ │
│ [取消下載] [暫停] │
│ │
│ 2.5 / 3 │
└─────────────────────────────────────────────────────┘
```
**互動規則：**
1. **離線偵測**：Wails app 啟動時先 ping Innovedus 內部 CDN（HEAD 請求，5 秒 timeout）。無法連線 → 顯示「離線提示卡」：「目前無法連線到模型伺服器。你可以 (A) 稍後重試 (B) 改用 Mock 模式 (C) 手動放置 .nef 到 `<APPDATA>/data/nef/`」。
2. **斷線續傳**：每個模型用獨立 HTTP request，失敗可單獨重試，不重新下載已完成的。
3. **跳過**：「略過」→ 直接進 Step 3，但 Models 頁會顯示空狀態「還沒有預置模型，請到 Settings > 進階 下載」。
4. **完成條件**：至少 1 個模型下載成功即可繼續；0 個則強制退回 Step 2 選 Mock。
5. **Settings 入口**：Settings > 進階 新增「重新下載預置模型」按鈕，使用者可隨時補。
**連帶影響（給 PM）：** PRD §6.4「離線可用」承諾必須加註解：「**例外**：若 R9 Plan B 觸發，首次啟動需一次性下載 ~73 MB 預置模型。後續使用仍完全離線。」
**Design 估計**：Plan B 的 First-Run UI 工作量約 0.5 人週（只新增 1 個 step + 1 個 Settings 按鈕 + 文案）。
---
## ❓ 需要使用者或三方討論的問題
1. **D→PM-01 的 AC 拆分**：使用者想要「15 秒」適用於所有情境，還是接受「首次 30 秒 / 回訪 15 秒」？
2. **D→Arch-02 的實際 port 顯示位置**：Settings > 進階？還是 Dashboard Server 狀態卡？
3. **D→Arch-06 舊專案資料目錄遷移**：要不要自動偵測 `~/.visiona-local/` 並提示使用者？
4. **R9 Plan B 觸發時**，內部 CDN 是否可用？PM 需要與 Innovedus IT 先確認，避免 Plan B 時再花時間找 host。
5. **macOS `⌘N` 快捷鍵**（D→Arch-08）：要綁什麼動作？
---
## 結論
**整體結論：三方文件一致性高，砍 tray、Workspace 升一級、Settings 4 分頁、macOS 資料路徑這幾個第三輪決策都有落實到各自的文件裡。**
主要風險在於**三層程序的啟動時間沒有被端到端量化**（D→Arch-01），這會直接影響到 First-Run 與 NFR §6.1 的 AC 能不能達成，建議 Architect 在 M1 結束時就實測並回填。
次要問題是一些**邊界情境的 UX 未被 Architect 顯式處理**：port picking 的 UI 呈現、second-instance 的提示、sidecar crash／auto-kill 的 loading 狀態、Python 雙策略的切換入口。這些不是 blocker 但會影響「順手、穩定」的使用體驗，建議 Architect 在 M3 前補齊 API 事件（`sidecar.state`、實際 port 查詢）讓 Design 能接著做 UI。
R9 Plan B 的 First-Run 下載流程已草擬，Design 工作量可控（~0.5 人週），但**內部 CDN 可用性需要 PM 先確認**，避免真的觸發 Plan B 時措手不及。
**Design Agent 對 PRD 與 TDD 第三輪版的整體結論：原則上可進入實作階段，但上述 🔴 問題 2 條（D→Arch-01、D→Arch-02）建議在 M1 開始前先補，避免後續返工。其餘 🟡 🟢 可在 M2-M3 迭代解決。**

91
local-tool/.autoflow/03-design/design-spec.md Normal file
View File

@ -0,0 +1,91 @@
# visionA-local 設計規格（索引）
> Design Agent · 第二輪正式規格 · 2026-04-11（第三輪修訂 2026-04-11）
> 本文件為索引檔，各章節詳細內容請見 `spec/` 子檔。所有決策依據 progress.md（2026-04-11）定案。
## 文件結構
| # | 章節 | 檔案 | 一句話摘要 |
|---|------|------|-----------|
| 1 | 資訊架構（IA） | `spec/01-information-architecture.md` | 4 主區塊 + Settings，sidebar 導航，無 deep link |
| 2 | 頁面清單與變更對照 | `spec/02-pages-diff.md` | 對照原 edge-ai-platform 的保留／刪除／修改 |
| 3 | 主要頁面 Wireframe | `spec/03-wireframes.md` | Dashboard / Models / Devices / Workspace / Settings 結構描述 |
| 4 | First-Run Experience | `spec/04-first-run.md` | 歡迎 → 模式選擇 → 硬體偵測，可跳過 |
| 5 | ~~Tray 互動規格~~ | — | **已於第三輪決策 Q-A 砍除**（不做 tray）。編號保留以避免後續引用失效 |
| 6 | 跨平台 UX 差異 | `spec/06-cross-platform.md` | title bar、快捷鍵、對話框、通知 |
| 7 | Design Tokens | `spec/07-design-tokens.md` | 沿用 edge-ai-platform oklch tokens，補 L 級 elevation |
| 8 | 錯誤與空狀態 | `spec/08-states.md` | 全域錯誤分級 + 空狀態文案庫 |
| 9 | 無障礙（A11y） | `spec/09-accessibility.md` | **盡力而為**（R4-3 降級，非硬性目標）— 保留鍵盤、焦點、語意化 HTML 等低成本項目 |
| 10 | i18n 策略 | `spec/10-i18n.md` | 中英雙語，跟隨系統，沿用 react-i18next |
## 關鍵設計決策（摘要）
1. **視窗模型**：傳統桌面 app — **關閉視窗 = 結束程式**。**不做 tray icon**（第三輪決策 Q-A），省跨平台圖資產與 Wails tray 踩坑，也避免與「關閉 = 結束」的語意衝突。
2. **資訊架構扁平化**：從原 5 區（含 clusters）瘦身為 4 主區 + Settings。所有 cluster／relay 相關入口完全移除，**M1 就一次清乾淨**（第三輪決策 Q-C）。
3. **Dashboard 重定位**：原本是叢集總覽，現在改成「快速開始 + 單機狀態卡」，把首頁價值從「監看」轉為「起手」。
4. **預設真實硬體模式**：首次啟動不預設 Mock，但在模式選擇步驟提供 Mock 作為明確替代，且可隨時切換。
5. **First-Run 可全跳過**：三步流程（歡迎 / 模式 / 偵測），每一步右上都有「略過」，降低挫敗。
6. **深色模式跟隨系統**：不提供手動切換（Settings 僅顯示「目前跟隨系統」唯讀狀態，避免決策疲勞）。
7. **中英雙語**：預設跟隨系統 Locale（`zh-*` → 繁中；其他 → 英文），Settings 可手動切換。
8. **Logo 沿用 edge-ai-platform**：暫不重新設計品牌識別，僅把產品字樣改為「visionA-local」。
9. **Design Tokens 完全沿用**：原專案使用 shadcn + oklch 中性色盤，local 版無變更，只補 desktop 專用的 elevation 與 window chrome token。
10. **Settings 重構為分頁式**：**一般 / 硬體 / 模型 / 進階**（4 分頁，第三輪決策 Q-E3 取消「外觀」分頁，語言併入「一般」）。
11. **macOS 資料目錄**：`~/Library/Application Support/visiona-local/`（第三輪決策 Q-E1，遵循 OS 慣例；第四輪 R4-5 全小寫對齊 Bundle ID 與 Linux 慣例）。
## 第四輪決策採納對照（2026-04-11 交叉審閱後）
| # | 決策 | 落地位置 |
|---|------|---------|
| R4-2 | MJPEG 延遲目標：首次 ≤250ms / 穩定後 ≤150ms | `spec/03-wireframes.md` Workspace Perf 示例值改為 180ms |
| R4-3 | WCAG 2.2 AA 降級為「盡力而為」（非硬性目標） | `spec/09-accessibility.md` 全節改寫、design-spec 索引同步 |
| R4-5 | 資料目錄全小寫 `visiona-local`（對齊 Bundle ID 與 Linux 慣例） | `spec/06-cross-platform.md §6.7`、`spec/04-first-run.md §4.1/§4.6/§4.7`、`spec/03-wireframes.md §3.5`、`spec/10-i18n.md §10.2` |
| R4-6 | ⌘R → ⌘Shift+R；⌘Shift+W 取消 | `spec/06-cross-platform.md §6.2` |
| R4-8 | 通知策略：裝置連/斷 → App toast；Server 崩潰 → OS 原生通知 | `spec/06-cross-platform.md §6.4` |
| — | Single-instance 第二次啟動 → 靜默 raise（不彈 toast） | `spec/06-cross-platform.md §6.9`（新增） |
| — | Python sidecar crash loading + 自動重啟 | `spec/08-states.md §8.8`（新增） |
| — | Python 雙策略切換 UI 入口 | `spec/03-wireframes.md §3.5` Settings > 進階 |
| — | 深色模式：CSS `prefers-color-scheme`（不需 JS emit event） | `spec/06-cross-platform.md §6.8`、`spec/07-design-tokens.md §7.5` 註記 |
| — | i18n 即時切換 → M2 才做 | `spec/10-i18n.md §10.7` 明確標註 |
## 已知 contingency
- **R9 Kneron 預置模型 re-distribution**：第四輪 R4-1 決定繼續內嵌、不主動問 Kneron，發佈前 gate 維持。**若 R9 觸發**，First-Run 需插入「下載預置模型」步驟，完整 fallback 流程的 Wireframe 與互動規格草案保留在 `design-cross-review.md §「R9 Plan B 的 First-Run 下載流程草案」`，目前**不納入正式 design-spec**（避免誤導開發團隊）。若真的觸發，會把該草案升格為 `spec/04-first-run-plan-b.md`。
## 第三輪決策採納對照
| # | 原疑問 | 第三輪結果 |
|---|--------|----------|
| 1 | Tray 是否要做？ | **Q-A 砍掉 tray**。05-tray.md 已刪除；`⌘0 顯示主視窗` 等 tray 相關快捷鍵同步移除 |
| 3 | Workspace 升為 sidebar 一級 | **Q-E2 採納**。IA 已確定 4 主區塊含 Workspace |
| 4 | Settings「外觀」分頁取消 | **Q-E3 採納**。Settings 為 4 分頁（一般 / 硬體 / 模型 / 進階），語言在「一般」 |
| — | macOS 資料目錄 | **Q-E1**：`~/Library/Application Support/visiona-local/`（取代 `~/.visiona-local/`，R4-5 全小寫） |
| — | M1 範圍 | **Q-C**：M1 就要清乾淨前端 cluster/relay UI，不分期 |
## 第三輪修訂後仍待確認 / 仍需使用者回饋
1. **Mock 模式的視覺標記**（沿用第二輪建議）
預設真實硬體模式後，Mock 變成明確的「次要體驗」。建議在 header 右側加一個永久性 `Mock` badge（黃色），避免使用者誤把假結果當成真推論。此項已寫入 wireframe，**未見使用者反對，視為採納**。
2. **簽章警示的 UX**（Q2 決策：不買憑證）
macOS 會跳 Gatekeeper 警告、Windows 會跳 SmartScreen。這些是 **OS 層的對話框，App 內無法攔截**；但首次啟動完成後的「歡迎畫面」應該主動說明「你可能剛才看到警告，那是因為我們是內部工具，已經安全」，降低焦慮。文案已寫入 `04-first-run.md`。
3. **快捷鍵衝突（tray 砍除 + 第四輪 R4-6 重整後）**
最小快捷鍵集：⌘, (Settings)、⌘W（關閉＝結束）、⌘Q（結束）、⌘1~4（切換主區塊，⌘4 即前往 Workspace）、⌘Shift+R（重新整理裝置）、⌘U（上傳模型）。
**R4-6 變更**：
- `⌘R` → **`⌘Shift+R`**（避免與 WebView 的 reload 衝突）
- **取消 `⌘Shift+W`**（與 macOS 內建「關閉所有視窗」衝突；⌘4 已涵蓋前往 Workspace）
- 原 `⌘0 顯示主視窗（從 tray）` 已於第三輪隨 tray 移除。
4. **[第三輪新增] Mock 模式切換入口的去留**
砍掉 tray 後，原本 tray 選單提供的「一鍵切換 Mock ↔ Real」捷徑消失。目前 Mock 切換入口剩下：
- Settings > 硬體（主要入口）
- Devices 頁面右上角的「真實 / Mock」pill 切換
- First-Run Step 2（僅首次）
Design 認為這樣夠用（切換頻率不高），但若未來使用者抱怨「找不到切換入口」，可考慮在 Dashboard 的 Quick Start 區加一個二級行動。**目前不改**。
---
**下一步：**
- PM / Architect 交叉 review 本規格第三輪修訂版
- 三方確認後進入 Prototype 階段（HTML/CSS 原型，後續迭代處理）

108
local-tool/.autoflow/03-design/spec/01-information-architecture.md Normal file
View File

@ -0,0 +1,108 @@
# 01 — 資訊架構（IA）
## 1.1 IA 總覽
```
visionA-local
│
├─ [1] Dashboard ⌘1 — 首頁，快速開始 + 單機狀態
│
├─ [2] Models ⌘2 — 模型庫（上傳、切換、比對 .nef）
│ ├─ Model List
│ ├─ Model Detail (drawer / modal)
│ ├─ Upload Dialog
│ └─ Comparison Dialog
│
├─ [3] Devices ⌘3 — 實體 Kneron USB 裝置清單
│ ├─ Device List (grid)
│ ├─ Device Detail (drawer)
│ ├─ Connection Log
│ └─ [韌體燒錄已砍，不保留]
│
├─ [4] Workspace ⌘4 — 推論工作區（核心操作頁）
│ ├─ 無裝置時：Empty State（引導接上裝置或切到 Mock）
│ ├─ 裝置選擇器（top bar）
│ ├─ Camera Feed + Overlay
│ ├─ Inference Panel（模型、參數、結果）
│ └─ Batch Image / Video Upload 分頁
│
└─ Settings ⌘, — 設定（分頁式，4 分頁）
├─ 一般（語言、啟動行為、資料目錄、主題唯讀顯示）
├─ 硬體（執行模式 Real/Mock、USB 權限、Port 設定）
├─ 模型（預置模型開關、自訂模型路徑）
└─ 進階（日誌、重置、關於）
```
## 1.2 主導航
| # | 項目 | 圖示 | 路由（內部） | 快捷鍵 | 預設頁面 |
|---|------|------|------------|-------|---------|
| 1 | Dashboard | `LayoutDashboard` | `/` | ⌘1 | — |
| 2 | Models | `Box` | `/models` | ⌘2 | — |
| 3 | Devices | `Cpu` | `/devices` | ⌘3 | — |
| 4 | Workspace | `Play` | `/workspace` | ⌘4 | 最近使用的裝置；無則 empty state |
| — | Settings | `Settings` | `/settings` | ⌘, | 一般分頁 |
**Settings 與 4 個主區塊視覺分離**：Settings 放在 sidebar 最下方（靠底對齊），並用 divider 與主導航區隔。
## 1.3 Sidebar 結構
```
┌─────────────────┐
│ [logo] visionA │ ← logo 區（32px 高）
│ -local │
├─────────────────┤
│ ⊞ Dashboard │ ← 主導航（48px per item，含 icon + label）
│ ▣ Models │
│ ▣ Devices │
│ ▶ Workspace │
│ │
│ ... │
│ (spacer) │
│ │
├─────────────────┤
│ ● Server: Idle │ ← Server 狀態（唯讀，常駐）
│ localhost:3721│
├─────────────────┤
│ ⚙ Settings │
└─────────────────┘
```
- **寬度**：展開 240px / 收合 64px
- **預設狀態**：展開
- **收合時**：只顯示 icon，hover 時用 tooltip 顯示 label
- **沒有漢堡按鈕**：桌面版 sidebar 固定，不提供折疊（減少決策疲勞）；最小視窗寬度 960px 保證 sidebar 不會擠壓
## 1.4 Header（Top Bar）
```
┌────────────────────────────────────────────────────────────┐
│ [當前頁標題] [Mock badge (if mock)] [連線狀態] [?] │
└────────────────────────────────────────────────────────────┘
```
- **高度**：56px
- **內容**：
- 左：當前頁面標題（h1）
- 右：
- Mock 模式時，顯示黃色 `Mock` badge（hover 有 tooltip 說明）
- Server 連線狀態小燈（綠/黃/紅）
- 幫助按鈕（打開 Help drawer）
- **無麵包屑**：IA 扁平，不需要
- **無全域搜尋**：local 版資料量小，個別頁面內建過濾即可
## 1.5 路由與 Deep Link 策略
- **內部路由**：沿用原 Next.js 檔案系統路由，但**所有 URL 對使用者隱藏**（無 URL bar）
- **不支援外部 deep link**：因為是桌面 app，不會有「別人把連結傳給我」的情境
- **App 內跳轉**：macOS 原生 menu bar 的快速動作（如「新增裝置掃描」「上傳模型」）會跳轉到對應頁面＋開啟對應 modal
- **路由歷史**：保留瀏覽歷史，以支援 App 選單的「前進／後退」（或快捷鍵 ⌘[ / ⌘]）
## 1.6 導航決策理由
| 決策 | 理由 |
|------|------|
| 不放 Workspace 到 Devices 子頁 | Workspace 是高頻核心動作，放 sidebar 一級可降低點擊數；原專案把它藏在 `/devices/[id]/workspace` 的二層路徑太深 |
| Settings 獨立於 4 大區 | Settings 不是日常導航目標，放底部＋icon only 可讓焦點集中在主功能 |
| 取消全域搜尋 | 本地資料量（模型數 < 50、裝置數 < 10），逐頁過濾即可 |
| 取消麵包屑 | IA 只有兩層，不需要 |

109
local-tool/.autoflow/03-design/spec/02-pages-diff.md Normal file
View File

@ -0,0 +1,109 @@
# 02 — 頁面與元件變更對照
對照原 `/Users/jimchen/Innovedus/edge-ai-platform/edge-ai-platform/frontend` 盤點結果。
## 2.1 頁面層級
| 原路由 | 決定 | visionA-local 對應 | 說明 |
|--------|------|---------------------|------|
| `/`（Dashboard） | ✅ **保留但重新設計** | `/` | 原為叢集總覽，改為「快速開始 + 單機狀態」 |
| `/models` | ✅ 保留 | `/models` | 移除 cluster 相關欄位 |
| `/devices` | ✅ 保留 | `/devices` | 移除 cluster 分組、flash 按鈕 |
| `/clusters` | ❌ **整個刪除** | — | 決策已定 |
| `/workspace/[deviceId]` | ✅ 保留 | `/workspace?device=...` 或 `/workspace/[deviceId]` | 新增裝置選擇器 top bar |
| `/workspace/cluster` | ❌ **整個刪除** | — | |
| `/settings` | ✅ **保留但重構** | `/settings/[tab]` | 從長捲頁改為分頁式 |
## 2.2 元件目錄
### 保留（全數）
| 原目錄 | 元件 | 備註 |
|--------|------|------|
| `components/camera/` | camera-feed、camera-controls、camera-overlay、source-selector、camera-inference-view、batch-image-thumbnails | 全保留 |
| `components/devices/` | device-card、device-list、device-health-card、device-connection-log、device-status | 移除 flash-dialog、flash-progress |
| `components/models/` | model-card、model-grid、model-filters、model-upload-dialog、model-detail、model-comparison-dialog | 全保留 |
| `components/inference/` | inference-panel、classification-result、confidence-slider、performance-metrics、video-progress | 全保留 |
| `components/dashboard/` | stat-card、activity-timeline、connected-devices-list | 拿掉 cluster 欄位 |
| `components/layout/` | sidebar、header、connection-status、help-button | 改寫，見 §2.3 |
| `components/ui/` | shadcn 元件組 | 全保留 |
| onboarding-dialog.tsx、guided-tour.tsx | 強化（見 04-first-run） |
| server-log-viewer.tsx、server-status-dashboard.tsx | 移至 Settings > 進階 |
| theme-sync.tsx、lang-sync.tsx、store-hydration.tsx | 全保留 |
### 刪除
| 原目錄／檔案 | 原因 |
|------------|------|
| `components/cluster/`（全目錄） | Cluster 功能砍掉 |
| `components/devices/flash-dialog.tsx`、`flash-progress.tsx` | 韌體燒錄 Q9 決策砍掉 |
| `components/relay-token-sync.tsx` | Relay 功能砍掉 |
| `app/clusters/`（全目錄） | 對應頁面砍掉 |
| `app/workspace/cluster/`（全目錄） | 同上 |
### 修改
| 元件 | 修改內容 |
|------|---------|
| `layout/sidebar.tsx` | 刪除 clusters 導航項；把 workspace 提升為主導航；logo 字樣改「visionA-local」；底部加 Server 狀態卡 |
| `layout/header.tsx` | 新增 Mock badge 顯示邏輯；刪除 relay mode switcher；連線狀態改為「Server running / idle / error」 |
| `layout/connection-status.tsx` | 語意從「Relay tunnel」改為「Local server」 |
| `dashboard/stat-card.tsx` | 移除 cluster 統計；重新設計 stat 組合（見 03-wireframes） |
| `dashboard/activity-timeline.tsx` | 過濾掉 cluster-related event |
| `app/settings/page.tsx` | 改為分頁 layout |
| `app/page.tsx` | 整頁重寫（見 03-wireframes Dashboard 章） |
## 2.3 Layout 改寫重點
### sidebar.tsx
```tsx
// 移除
- { href: '/clusters', label: 'Clusters', icon: Network }
- <RelayTokenSync />
// 新增
+ { href: '/workspace', label: 'Workspace', icon: Play }
+ <ServerStatusBadge /> // 底部常駐
```
### header.tsx
```tsx
// 移除
- <RelayModeSwitcher />
// 新增
+ {isMockMode && <MockBadge />}
+ <PageTitle /> // 取代原來的 logo-in-header（logo 只在 sidebar 顯示）
```
## 2.4 新元件
| 元件 | 放置位置 | 用途 |
|------|---------|------|
| `FirstRunWizard` | `components/first-run/` | 三步引導流程 |
| `ModeSelector` | `components/first-run/` | 真實/Mock 模式選擇卡 |
| `HardwareDetectionStep` | `components/first-run/` | USB 掃描進度與結果 |
| `MockBadge` | `components/layout/` | Header 右側 Mock 指示 |
| `ServerStatusBadge` | `components/layout/` | Sidebar 底部 server 狀態 |
| `EmptyWorkspace` | `components/workspace/` | 無裝置引導畫面 |
| `SettingsTabs` | `components/settings/` | 分頁 layout |
| `QuickStartCard` | `components/dashboard/` | Dashboard 首屏的 CTA 卡組 |
| `LanguageSwitcher` | `components/settings/` | i18n 切換 |
| `SignatureWarningNotice` | `components/first-run/` | 解釋 Gatekeeper/SmartScreen 警告（疑問 #5） |
## 2.5 被移除元件回收清單
以下程式碼可以從原專案直接刪除（不需要轉移到 local_tool）：
```
components/cluster/**/*
components/relay-token-sync.tsx
components/devices/flash-dialog.tsx
components/devices/flash-progress.tsx
app/clusters/**/*
app/workspace/cluster/**/*
```
提醒：Architect 的 round 1 分析已列出對應的後端刪除清單，請確認 API 層與前端同步刪乾淨。

239
local-tool/.autoflow/03-design/spec/03-wireframes.md Normal file
View File

@ -0,0 +1,239 @@
# 03 — 主要頁面 Wireframe（結構化描述）
以下為文字版 wireframe。所有尺寸以 Desktop 1280×800 為基準，sidebar 固定 240px。
## 3.1 Dashboard（`/`）
**設計意圖**：原本是叢集總覽，local 版改為「快速開始 + 單機狀態」，幫使用者 3 秒內決定下一步動作。
```
┌─ Sidebar ─┬──────────────────────── Content ───────────────────────┐
│ │ Dashboard [Mock?] [●Server] [?] │
│ ├────────────────────────────────────────────────────────┤
│ │ │
│ │ 你好 👋 │
│ │ visionA-local 已準備就緒 │
│ │ │
│ │ ┌─ Quick Start ──────────────────────────────────┐ │
│ │ │ [①接上裝置] [②選擇模型] [③前往 Workspace →] │ │
│ │ │ （步驟卡，已完成的打勾） │ │
│ │ └────────────────────────────────────────────────┘ │
│ │ │
│ │ ┌─ Status ────┐ ┌─ Status ────┐ ┌─ Status ────┐ │
│ │ │ 🔌 已連裝置 │ │ 📦 可用模型 │ │ ⏱ Uptime │ │
│ │ │ 2 │ │ 6 │ │ 00:12:34 │ │
│ │ │ (KL720×1, │ │ (預置 5 + │ │ │ │
│ │ │ KL520×1) │ │ 自訂 1) │ │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │
│ │ ┌─ 最近活動 ────────────────────────────────────┐ │
│ │ │ • 10:42 USB 裝置「KL720-A」已連線 │ │
│ │ │ • 10:41 模型「fd_mask.nef」已載入 │ │
│ │ │ • 10:40 Server 已啟動（localhost:3721） │ │
│ │ │ ... │ │
│ │ └────────────────────────────────────────────────┘ │
│ │ │
└───────────┴────────────────────────────────────────────────────────┘
```
**元件組成：**
- `QuickStartCard`：3 步卡片，根據狀態打勾（狀態來自 `/api/devices` + `/api/models`）
- 3 個 `StatCard`：已連裝置 / 可用模型 / Uptime（原有元件，調整 label）
- `ActivityTimeline`：沿用，過濾掉 cluster 事件
**互動：**
- 點「③前往 Workspace」= 跳到 `/workspace`
- 點 StatCard 上的數字可跳到對應頁
- 最近活動項目可 hover 顯示完整時間戳
**空狀態**：若還沒有任何裝置／模型，步驟卡會顯示引導文字「先接上一顆 Kneron 裝置吧」並附 CTA 到 Devices。
---
## 3.2 Models（`/models`）
**設計意圖**：沿用原設計（model-grid + filters + detail drawer），只移除 cluster 欄位。
```
┌─ Sidebar ─┬────────────────────────── Content ─────────────────────┐
│ │ Models [+ 上傳模型] │
│ ├────────────────────────────────────────────────────────┤
│ │ [搜尋____] [架構▾] [類別▾] [排序▾] 共 6 個模型 │
│ │ │
│ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │
│ │ │ Card │ │ Card │ │ Card │ │ Card │ │
│ │ │ 縮圖 │ │ 縮圖 │ │ 縮圖 │ │ 縮圖 │ │
│ │ │ 名稱 │ │ 名稱 │ │ 名稱 │ │ 名稱 │ │
│ │ │ 類別 │ │ 類別 │ │ 類別 │ │ 類別 │ │
│ │ │ [詳情]│ │ [詳情]│ │ [詳情]│ │ [詳情]│ │
│ │ └──────┘ └──────┘ └──────┘ └──────┘ │
│ │ │
│ │ ┌──────┐ ┌──────┐ │
│ │ │ Card │ │ Card │ │
│ │ └──────┘ └──────┘ │
│ │ │
│ │ [將 .nef 拖放到這裡也可以上傳] ← dropzone 提示 │
└───────────┴────────────────────────────────────────────────────────┘
```
- 拖放區域覆蓋整個 Models 頁面，hover 拖曳時變藍色高亮
- 點 Card 開啟 Detail Drawer（側邊滑出）
- 上傳 Dialog 沿用原 `model-upload-dialog`
**空狀態**：無模型時顯示「還沒有模型，上傳一個 .nef 試試 →」，附大型上傳按鈕與預置模型列表連結。
---
## 3.3 Devices（`/devices`）
```
┌─ Sidebar ─┬────────────────────────── Content ─────────────────────┐
│ │ Devices [🔄 重新掃描] [真實 / Mock]│
│ ├────────────────────────────────────────────────────────┤
│ │ ⓘ 插上 Kneron USB 裝置後自動出現在下方 │
│ │ │
│ │ ┌─ Connected ─────────────────────────────────────┐ │
│ │ │ ┌──────────┐ ┌──────────┐ │ │
│ │ │ │ KL720-A │ │ KL520-B │ │ │
│ │ │ │ 🟢 Ready │ │ 🟢 Ready │ │ │
│ │ │ │ FW 2.1.0 │ │ FW 1.8.3 │ │ │
│ │ │ │ [Workspc]│ │ [Workspc]│ │ │
│ │ │ └──────────┘ └──────────┘ │ │
│ │ └─────────────────────────────────────────────────┘ │
│ │ │
│ │ ┌─ Disconnected History ──────────────────────────┐ │
│ │ │ (過去連接過的裝置，用於顯示連線紀錄) │ │
│ │ └─────────────────────────────────────────────────┘ │
│ │ │
│ │ ⓘ Connection Log (drawer, 點右下角按鈕展開) │
└───────────┴────────────────────────────────────────────────────────┘
```
- 右上角 `真實 / Mock` 是切換 pill，點擊彈出確認對話框（避免誤觸）
- Device Card 點「Workspace」直接跳到 `/workspace?device=<id>`
- 韌體燒錄按鈕**已移除**
- Connection Log drawer 從右側滑出（沿用 `device-connection-log.tsx`）
**空狀態**：
- 真實模式無裝置：顯示大型 empty state — 插圖（USB 接頭）+ 「沒偵測到 Kneron 裝置」+ 排錯清單（重插 USB / 檢查權限 / 切到 Mock 模式）
- Mock 模式：固定顯示 3 顆假裝置，每個都有 `Mock` 小標
---
## 3.4 Workspace（`/workspace`）
**設計意圖**：核心操作頁，左右分欄 — 左邊攝影機畫面＋推論 overlay，右邊控制面板。
```
┌─ Sidebar ─┬────────────────────────── Content ─────────────────────┐
│ │ Workspace [裝置▾ KL720-A] [▣ Live | ▤ Batch | ▧ Video]│
│ ├────────────────────────────────────────────────────────┤
│ │ ┌─────────── Camera Feed ────────────┐ ┌─ Control ──┐ │
│ │ │ │ │ 模型: │ │
│ │ │ │ │ [fd_mask]│ │
│ │ │ [MJPEG + Overlay] │ │ │ │
│ │ │ │ │ Confidence│ │
│ │ │ │ │ ━━━● 0.7 │ │
│ │ │ │ │ │ │
│ │ │ │ │ Source: │ │
│ │ │ │ │ [webcam ▾]│ │
│ │ │ │ │ │ │
│ │ │ │ │ [▶ Start] │ │
│ │ └────────────────────────────────────┘ │ │ │
│ │ ┌── Results Timeline ─────────────────┐ │ Perf: │ │
│ │ │ (bounding boxes / classes list) │ │ FPS: 24 │ │
│ │ └────────────────────────────────────┘ │ Latency: │ │
│ │ │ 180ms │ │
│ │ └────────────┘ │
└───────────┴────────────────────────────────────────────────────────┘
```
- **頂部 Tab**：Live（即時串流）/ Batch（批次圖片）/ Video（影片檔）— 三模式切換
- **裝置選擇器**：top bar 左邊，下拉選單顯示所有已連裝置；只有 1 顆時直接顯示名稱；無裝置時顯示 EmptyWorkspace
- **Camera Feed**：沿用 `camera-feed` + `camera-overlay`
- **Control Panel**：沿用 `inference-panel` + `confidence-slider` + `source-selector`
- **Results Timeline**：底部時間軸，顯示每秒的推論結果摘要
- **Perf 指標說明**：
- `FPS` 顯示目前即時影格率
- `Latency` 指 **MJPEG 端到端延遲**（拍到→瀏覽器顯示），第四輪 R4-2 定案目標：**首次 ≤250ms、穩定後 ≤150ms**。上圖示例 180ms 為「穩定後但略高於理想」的典型值；實際數字會隨硬體與解析度變動。
- 當 Latency > 250ms 時以 `warning` 顏色顯示，使用者可點擊查看瓶頸（未來功能）
**空狀態**（EmptyWorkspace 元件）：
```
┌────────────────────────────────────────────────────┐
│ │
│ 🔌 │
│ │
│ 還沒有可用的裝置 │
│ │
│ 接上一顆 Kneron USB 裝置，或切到 Mock 模式 │
│ 先體驗看看。 │
│ │
│ [前往 Devices] [切到 Mock 模式] │
│ │
└────────────────────────────────────────────────────┘
```
---
## 3.5 Settings（`/settings/[tab]`）
```
┌─ Sidebar ─┬────────────────────────── Content ─────────────────────┐
│ │ Settings │
│ ├────────────────────────────────────────────────────────┤
│ │ ┌── Tabs ──┬── Panel ────────────────────────────────┐│
│ │ │ ● 一般 │ ││
│ │ │ ○ 硬體 │ 語言 [繁中 ▾] ││
│ │ │ ○ 模型 │ ││
│ │ │ ○ 進階 │ 啟動時開啟 [Dashboard ▾] ││
│ │ │ │ ││
│ │ │ │ 資料目錄 ~/Library/Application ││
│ │ │ │ Support/visiona-local/ ││
│ │ │ │ [在 Finder 顯示] ││
│ │ │ │ ││
│ │ │ │ 主題 跟隨系統（目前：深色） ││
│ │ │ │ ⓘ 深色模式自動跟隨系統 ││
│ │ │ │ ││
│ │ └──────────┴──────────────────────────────────────────┘│
└───────────┴────────────────────────────────────────────────────────┘
```
### 分頁內容
**一般**
- 語言（繁中 / English / 跟隨系統）
- 啟動時預設頁（Dashboard / Workspace / 上次開啟的頁）
- 資料目錄（唯讀顯示 + 「在 Finder/Explorer 顯示」按鈕）
- 主題（唯讀顯示「跟隨系統」+ 當前 light/dark 狀態）
**硬體**
- 執行模式（真實硬體 / Mock）— 切換時有確認對話框
- USB 權限狀態（唯讀）
- Server Port（預設 3721，衝突時可改）
- 裝置自動掃描頻率（預設 5 秒）
**模型**
- 預置模型顯示開關（可隱藏內建模型只看自訂）
- 自訂模型路徑（唯讀顯示 + 「新增路徑」）
- 清除模型快取
**進階**
- 開啟日誌 viewer（嵌入 `server-log-viewer`）
- 開啟 Server 狀態（嵌入 `server-status-dashboard`）
- **Server Port** 唯讀顯示（預設 3721，若被占用會自動挑下一個；顯示實際使用的 port + 「複製」按鈕）
- **Python 執行模式**（第四輪新增 UI 入口，對應 Architect `dependency-bundling.md §1.5` 的 `--python-mode` CLI flag）：
```
Python 執行模式 [內嵌 (推薦) ▾]
選項：
• 內嵌 — 使用 App 內建的 python-build-standalone（完全離線）
• 系統 — 使用系統 Python（需自行安裝 KneronPLUS）
• 自動 — 優先內嵌，失敗時退回系統
目前狀態：內嵌 Python 3.11.7（✓ 已就緒）
[重新偵測]
```
切換後**需要重啟 App** 才能生效（顯示 toast 提示）。此區塊資料來源：Architect 需提供 `/api/system/python-mode`（GET 讀目前狀態、POST 切換）。
- 重置所有設定（危險操作，雙重確認）
- 關於 visionA-local（版本、授權、第三方套件、Kneron SDK 版本）
**備註**：原規劃有「外觀」分頁，因為只剩語言一項且主題跟隨系統，合併到「一般」分頁。

233
local-tool/.autoflow/03-design/spec/04-first-run.md Normal file
View File

@ -0,0 +1,233 @@
# 04 — First-Run Experience 詳細流程
## 4.1 觸發條件
- 資料目錄下 `config.json` 的 `firstRunCompleted != true`
- macOS：`~/Library/Application Support/visiona-local/config.json`
- Windows：`%APPDATA%\visiona-local\config.json`
- Linux：`~/.local/share/visiona-local/config.json`
（資料目錄名稱於第四輪 R4-5 統一為全小寫 `visiona-local`，對齊 Bundle ID 與 Linux 慣例。）
- 或使用者從 Settings > 進階 手動觸發「重新顯示歡迎流程」
完成條件：三步流程跑到最後一步 **或** 使用者點任一步驟的「略過」。
## 4.2 流程概覽
```
[啟動 App]
↓
[Step 1] 歡迎畫面 ────→ [略過] ──┐
↓ 繼續 │
[Step 2] 模式選擇 ────→ [略過] ──┤
↓ 繼續 │
[Step 3] 硬體偵測 ────→ [略過] ──┤
↓ 完成 │
↓
[Dashboard]
```
**重點**：每一步右上角都有「略過」，點了直接跳到 Dashboard，不強制走完。
## 4.3 Step 1 — 歡迎畫面
### 佈局
```
┌─────────────────────────────────────────────────────┐
│ [略過 →] │
│ │
│ [visionA logo 128px] │
│ │
│ 歡迎使用 visionA-local │
│ 在你的電腦上跑 Kneron AI 推論 │
│ │
│ ✓ 完全離線 — 不需網路 │
│ ✓ 一鍵安裝 — 所有依賴已內建 │
│ ✓ 支援 Kneron KL520 / KL720 / KL730 │
│ │
│ │
│ ⓘ 剛才你可能看到系統的安全警告——那是因為我們是 │
│ 內部工具、未購買程式碼簽章憑證。是安全的。 │
│ │
│ [讓我開始使用 →] │
│ │
│ 1 / 3 │
└─────────────────────────────────────────────────────┘
```
### 元件與規格
- 視窗尺寸：1024×720（固定，居中）
- Logo：沿用 edge-ai-platform（原檔案 `frontend/public/logo.svg` 或類似）
- 標題：`h1` 32px / font-semibold
- Value prop 清單：3 行，icon + 文字
- **簽章警示說明區塊**：淺色背景卡片，`info` icon，自動顯示（不需偵測）
- CTA：`button.primary size=lg`，footer 顯示「1 / 3」進度
- 右上略過：`ghost button size=sm`
### 互動
- 「讓我開始使用」→ Step 2
- 「略過」→ 跳到 Dashboard，並寫 `firstRunCompleted = true`
- ⌘Q 可立即結束 App
---
## 4.4 Step 2 — 模式選擇
### 佈局
```
┌─────────────────────────────────────────────────────┐
│ [略過 →] │
│ │
│ 選擇執行模式 │
│ 你隨時可以在 Settings 切換 │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ 🔌 │ │ 🧪 │ │
│ │ │ │ │ │
│ │ 真實硬體模式 │ │ Mock 模式 │ │
│ │ (推薦) │ │ │ │
│ │ │ │ │ │
│ │ 連接實體 Kneron │ │ 用預設假資料體驗 │ │
│ │ USB 裝置，跑真實 │ │ 產品功能，不需要 │ │
│ │ AI 推論 │ │ 硬體 │ │
│ │ │ │ │ │
│ │ [●] 選取 │ │ [○] 選取 │ │
│ └──────────────────┘ └──────────────────┘ │
│ │
│ │
│ [← 返回] [繼續 →] │
│ │
│ 2 / 3 │
└─────────────────────────────────────────────────────┘
```
### 規格
- 兩張 `card.selectable`，240×320，圓角 12px
- **預設選取：真實硬體模式**（依決策 Q8）
- 選中狀態：border 2px `color.primary`，背景 `color.primary.subtle`
- 「推薦」badge 顯示在真實硬體卡片右上角
- 點整張卡片 = 選取（不需要精準點 radio button）
### 互動
- 「繼續」→ 如選真實模式進 Step 3；如選 Mock 則跳過 Step 3 直接進 Dashboard 並顯示 Mock badge
- 「返回」→ Step 1
- 鍵盤：← → 切換選取；Enter 繼續
---
## 4.5 Step 3 — 硬體偵測（僅真實模式）
### Phase 1：掃描中
```
┌─────────────────────────────────────────────────────┐
│ [略過 →] │
│ │
│ 偵測 Kneron 裝置 │
│ │
│ ⟳ │
│ 正在掃描 USB 裝置... │
│ │
│ [■■■■■■□□□□] 60% │
│ │
│ │
│ │
│ 3 / 3 │
└─────────────────────────────────────────────────────┘
```
### Phase 2A：偵測成功
```
┌─────────────────────────────────────────────────────┐
│ │
│ ✓ 偵測到 2 顆 Kneron 裝置 │
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ 🟢 KL720-A │ │ 🟢 KL520-B │ │
│ │ FW 2.1.0 │ │ FW 1.8.3 │ │
│ └──────────────┘ └──────────────┘ │
│ │
│ │
│ [前往 Dashboard] [前往 Workspace →] │
│ │
└─────────────────────────────────────────────────────┘
```
### Phase 2B：偵測失敗（無裝置）
```
┌─────────────────────────────────────────────────────┐
│ │
│ ⚠ 沒有偵測到 Kneron 裝置 │
│ │
│ 可能的原因： │
│ • 裝置還沒接上 USB │
│ • USB 線只能供電不能傳輸 (試換一條) │
│ • macOS: 第一次連接需要允許權限 │
│ • Windows: 需要安裝 WinUSB driver │
│ • Linux: 需要 libusb + udev rules │
│ │
│ [🔄 重新掃描] [使用 Mock 模式] │
│ [繼續到 Dashboard] │
│ │
└─────────────────────────────────────────────────────┘
```
### 規格
- Phase 1 進度條：基於後端 `/api/devices/scan` 的回報進度；超過 10 秒超時切到 Phase 2B
- Phase 2A：最多顯示 4 顆裝置卡；超過則顯示「+N」
- Phase 2B：每個排錯項目可點擊展開詳細說明（平台自動偵測顯示對應項）
### 互動
- Phase 1「略過」→ 直接 Dashboard（不寫 Mock flag）
- Phase 2A「前往 Workspace」→ 自動選中第一顆裝置進入 workspace
- Phase 2B「使用 Mock 模式」→ 寫 Mock flag + 進 Dashboard
- Phase 2B「繼續到 Dashboard」→ 維持真實模式（使用者待會再接裝置）
---
## 4.6 完成後的狀態
- 寫入資料目錄下的 `config.json`（macOS 為 `~/Library/Application Support/visiona-local/config.json`，其他平台見 4.1）：
```json
{
"firstRunCompleted": true,
"mode": "real" | "mock",
"completedAt": "2026-04-11T10:00:00Z"
}
```
- 跳轉 Dashboard
- 如果是 Mock 模式，Header 立即顯示黃色 `Mock` badge
## 4.7 i18n 重點文案（需翻譯）
| Key | 繁中 | English |
|-----|------|---------|
| `firstRun.welcome.title` | 歡迎使用 visionA-local | Welcome to visionA-local |
| `firstRun.welcome.subtitle` | 在你的電腦上跑 Kneron AI 推論 | Run Kneron AI inference on your computer |
| `firstRun.welcome.signatureNotice` | 剛才你可能看到系統的安全警告——那是因為我們是內部工具、未購買程式碼簽章憑證。是安全的。 | You may have seen a system security warning — that's because we're an internal tool without a code-signing certificate. It's safe. |
| `firstRun.mode.title` | 選擇執行模式 | Choose your mode |
| `firstRun.mode.real.title` | 真實硬體模式 | Real Hardware |
| `firstRun.mode.mock.title` | Mock 模式 | Mock Mode |
| `firstRun.hardware.scanning` | 正在掃描 USB 裝置... | Scanning USB devices... |
| `firstRun.hardware.notFound` | 沒有偵測到 Kneron 裝置 | No Kneron devices found |
| `common.skip` | 略過 | Skip |
| `common.continue` | 繼續 | Continue |
| `common.back` | 返回 | Back |
## 4.8 無障礙
- 每一步 focus 預設落在主 CTA
- Tab 順序：[略過] → [主 CTA] → [次要 CTA] → [返回]
- 進度指示用 `aria-label="第 X 步，共 3 步"` 而非只靠視覺
- 每一步提供 `role="region"` + `aria-labelledby`
- 鍵盤：← → 在 Step 2 切卡、Enter 繼續、Esc 略過

176
local-tool/.autoflow/03-design/spec/06-cross-platform.md Normal file
View File

@ -0,0 +1,176 @@
# 06 — 跨平台 UX 差異處理
原則：**視覺層統一、互動層遵循平台慣例。**
## 6.1 Window Chrome（視窗標題列）
| 平台 | 策略 | 理由 |
|------|------|------|
| **macOS** | frameless + 顯示 traffic lights（紅綠黃）於左上 | 最原生的感覺；Wails 支援 `TitleBar: { Hide: true }` + 保留 traffic lights |
| **Windows** | 標準 title bar（系統提供） | 不自畫 close/minimize，避免 DPI / 深色模式坑 |
| **Linux** | 標準 title bar（GTK/Qt） | 同上，讓 WM 決定 |
**標題列內容**：App 名稱 `visionA-local`（所有平台統一）。macOS 的 frameless 沒有標題列文字，改把 page title 放在 header 區塊裡即可（見 03-wireframes 的 Header）。
**最小化 / 最大化行為**：全平台一致 — 都能最小化、最大化、調整視窗大小。最小視窗尺寸 **960×640**（保證 sidebar + content 不擠壓）。
## 6.2 快捷鍵
### 修飾鍵對照
| 動作 | macOS | Windows / Linux |
|------|-------|----------------|
| Settings | ⌘ , | Ctrl + , |
| 結束 | ⌘ Q | Ctrl + Q（或 Alt + F4） |
| 關閉視窗（＝結束程式） | ⌘ W | Ctrl + W |
| 切換主區塊（Dashboard/Models/Devices/Workspace） | ⌘ 1–4 | Ctrl + 1–4 |
| 重新整理裝置 | ⌘ Shift + R | Ctrl + Shift + R |
| 上傳模型 | ⌘ U | Ctrl + U |
**⌘W 語意**：因為決策 Q7 為「關閉視窗 = 結束程式」、且決策 Q-A 砍掉 tray，⌘W 與 ⌘Q 行為一致（關閉唯一主視窗即結束 App）。
**第四輪 R4-6 決策變更**：
- **`⌘R` → `⌘Shift+R`**：原本 `⌘R` 會與 WebView 內建的「重新載入頁面」衝突（使用者一按可能誤觸前端整頁 reload），改為 `⌘Shift+R` 作為「重新掃描裝置」的明確動作，避免與瀏覽器反射行為打架。
- **取消原 `⌘Shift+W 前往 Workspace`**：此組合與 macOS 內建「關閉所有視窗」衝突，且 `⌘4` 已涵蓋「切到 Workspace」的需求，移除避免語意重疊。
**實作方式**：所有快捷鍵定義在 Wails 的原生 menu API，由 OS 派送；**不要**在前端用 `keydown` 監聽（會與輸入框衝突且跨平台不一致）。
**衝突避免**：
- 不佔用 ⌘ X/C/V/A/Z（輸入操作）
- 不佔用 ⌘ F（應該給頁面內搜尋用）
### 原生 App 選單（macOS 獨有）
macOS 需要一個原生 menu bar（因為無 window menu）：
```
visionA-local | File | Edit | View | Devices | Help
```
- **visionA-local**：About、Preferences (⌘,)、Services、Hide、Quit
- **File**：新增裝置掃描、上傳模型、匯出結果
- **Edit**：Undo / Redo / Cut / Copy / Paste（標準 macOS）
- **View**：切到 Dashboard/Models/Devices/Workspace (⌘1-4)、重新載入
- **Devices**：重新掃描、切換模式、連線紀錄
- **Help**：說明文件、關於 visionA-local、回報問題（開外部瀏覽器）
Windows/Linux 不做原生 menu bar（使用者會覺得多餘），改放在 Settings / 頁面內。
## 6.3 檔案對話框
| 場景 | 實作 |
|------|------|
| 上傳 `.nef` 模型 | Wails `runtime.OpenFileDialog`，filter `*.nef` |
| 選擇影片檔 | Wails `runtime.OpenFileDialog`，filter `*.mp4,*.mov,*.avi` |
| 選擇圖片批次 | Wails `runtime.OpenMultipleFilesDialog`，filter `image/*` |
| 匯出結果 | Wails `runtime.SaveFileDialog` |
| 「在 Finder/Explorer 顯示」 | 平台指令：`open` (mac) / `explorer /select,` (win) / `xdg-open` (linux) |
**禁止**：自畫 file picker、用 HTML `<input type=file>`（桌面 app 應該用原生）。
**拖放**：支援 drag-and-drop 到整個 Models / Workspace 頁面，由前端處理 drop event，Wails 會傳 file path 給 Go 端。
## 6.4 通知（第四輪 R4-8 定案）
**策略原則**：
- **App 內 toast** 處理一般資訊、裝置連/斷等前景事件（使用者必然在看著主視窗，不必打擾 OS 通知中心）
- **OS 原生通知** 只用於「App 可能不在前景、且必須立刻知道」的嚴重事件（主要是 Server 崩潰）
| 場景 | 通知方式 | 說明 |
|------|---------|------|
| 裝置連接成功 | **App 內 toast**（success） | 關閉 = 結束程式，使用者必然在主視窗前，不需要 OS 通知 |
| 裝置斷線 | **App 內 toast**（warning） | 同上 |
| 模型上傳完成 | App 內 toast（success） | — |
| 模型載入失敗 | App 內 toast（destructive） | — |
| **Server 崩潰 / 自動重啟** | **OS 原生通知**（嚴重） | 崩潰時前端可能也沒了，唯有 OS 通知可靠 |
| 推論結果（使用者要求時） | App 內 toast / timeline 更新 | — |
| 一般資訊（設定已儲存等） | App 內 toast | — |
**實作方式**（shell out，Wails 原生通知 API 有限）：
- **macOS**：`osascript -e 'display notification "訊息" with title "visionA-local"'`
- **Windows**：PowerShell `New-BurntToastNotification -Text "訊息"`（需內建 BurntToast 模組，若沒有則退回 msg box）
- **Linux**：`notify-send "visionA-local" "訊息"`
**需 Architect**在後端提供統一封裝，前端只需呼叫 `/api/notify` 或透過 Wails Go↔JS bridge 觸發。
## 6.9 Single-instance（單例）行為
**情境**：使用者二次雙擊 app 圖示、或從 Dock/Start menu 再次啟動 visiona-local，但 App 已在執行。
**策略**（與 Architect `tray-and-lifecycle.md §2.3` 對齊）：**靜默 raise，不彈 toast、不彈對話框**。
| 動作 | 預期行為 |
|------|---------|
| 第二個程序啟動 | 偵測到 lock file → 呼叫既有程序的 `/ipc/raise` → 既有程序 `WindowShow(ctx)` 把主視窗帶到最前並聚焦 → 第二個程序立即退出（exit 0） |
| 視覺回饋 | **無 toast、無對話框**。使用者看到主視窗被帶到前景即可（這本身就是最直觀的回饋） |
| Dock click（macOS） | 由 Cocoa 自動處理，無需介入 |
| `/ipc/raise` 失敗（例如 IPC port 讀不到） | **顯示 error modal**「無法喚起既有的 visiona-local 視窗，請手動切換」+「確認」按鈕 → 第二個程序退出。**絕對不覆寫 lock 另開新視窗**（會出現兩個視窗，體驗極差） |
**設計理由**：
- 彈 toast「已有另一個 visionA-local 在執行中」是**冗餘資訊**——使用者會看到視窗浮起來，不需要再被告知一次
- 但 raise 失敗的錯誤 modal 必要，否則使用者會以為 app 壞了而反覆雙擊
**與 i18n 的互動**：error modal 的文案走 `errors:singleInstance.raiseFailed`，需要中英兩版。
## 6.5 字型
| 平台 | 字型 |
|------|------|
| macOS | `-apple-system, "SF Pro Text", "PingFang TC"` |
| Windows | `"Segoe UI", "Microsoft JhengHei"` |
| Linux | `"Inter", "Noto Sans TC", "Ubuntu"` |
CSS font-family 一字串包辦：
```css
font-family:
-apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang TC",
"Microsoft JhengHei", "Noto Sans TC", Inter, Ubuntu,
Roboto, sans-serif;
```
等寬字型（log viewer）：
```css
font-family:
ui-monospace, SFMono-Regular, "SF Mono", Menlo,
Consolas, "Cascadia Mono", monospace;
```
## 6.6 Tray icon 資產
~~見 `05-tray.md`。~~
**已於第三輪決策 Q-A 砍除 tray**（`05-tray.md` 刪檔）。本版不做 tray，App 只透過主視窗與原生 menu bar（僅 macOS）互動。
## 6.7 資料目錄位置
| 平台 | 路徑 |
|------|------|
| macOS | `~/Library/Application Support/visiona-local/` |
| Windows | `%APPDATA%\visiona-local\` |
| Linux | `~/.local/share/visiona-local/` |
**UI 顯示**：Settings > 一般 統一顯示為「資料目錄：[完整路徑]」並附「在 Finder/Explorer 顯示」按鈕，使用者不需要記平台差異。
**第三輪決策 Q-E1** 採 OS 慣例路徑；**第四輪 R4-5** 進一步決定目錄名稱**全小寫**（`visiona-local` 而非 `visionA-local`），理由：
- 對齊 Bundle ID `com.innovedus.visiona-local`
- 符合 Linux 檔案系統慣例（case-sensitive，且習慣全小寫）
- 避免 macOS/Windows（case-insensitive）與 Linux 產生不一致
- App 顯示名稱「visionA-local」不受影響，僅檔案系統層路徑全小寫
## 6.8 深色模式
**統一方案（第四輪定案）**：**純 CSS `prefers-color-scheme` media query + Tailwind `dark:` variant**，**不需要 Go/Wails 在系統主題變更時 emit event 給前端**。
| 平台 | 偵測方式 |
|------|---------|
| macOS | WebView 自動支援 `prefers-color-scheme`（Cocoa → WKWebView 會在系統切換 light/dark 時自動更新 media query 結果） |
| Windows 10/11 | WebView2（Edge Chromium）原生支援 `prefers-color-scheme` |
| Linux | WebKit2GTK 支援 `prefers-color-scheme`（需 GTK 系統主題正確設定） |
**實作簡化理由**：
- 三平台 WebView 都已原生支援 `prefers-color-scheme` 的即時切換（使用者在系統設定切 light/dark 的瞬間，CSS media query 就會重新 match，前端 re-render 即可）
- **不需要** Wails Go 端監聽系統主題事件再 emit 到前端（原本規劃這樣做是為了 fallback，但實測多餘）
- 前端只要用 `@media (prefers-color-scheme: dark) { ... }` 或 Tailwind `dark:` variant，無需 JS 介入
**不提供手動切換**（決策 Q15）。Settings > 一般 只顯示唯讀的「主題：跟隨系統（目前：深色／淺色）」，其中「目前」狀態用 `window.matchMedia('(prefers-color-scheme: dark)').matches` 讀取。

245
local-tool/.autoflow/03-design/spec/07-design-tokens.md Normal file
View File

@ -0,0 +1,245 @@
# 07 — Design Tokens
## 7.1 策略
**完全沿用 edge-ai-platform 的 tokens**（來源：`frontend/src/app/globals.css`），僅補 desktop 專用項目。理由：
- 原專案採 shadcn + oklch 中性色盤，已經過調教
- Logo 沿用（決策 Q14），色系一致
- 減少 local 版的設計負擔，聚焦桌面 app 獨有課題
所有 token 來源以下列註記標示：
- **[沿用]** = 直接從 edge-ai-platform 抄過來，不改
- **[新增]** = visionA-local 補的 desktop 專用 token
- **[微調]** = 沿用但數值略改（需說明原因）
## 7.2 Reference Tokens（原始值）
### Colors — Light Mode [沿用]
| Token | Value (oklch) | 對應原專案變數 |
|-------|---------------|---------------|
| `color.background` | `oklch(1 0 0)` | `--background` |
| `color.foreground` | `oklch(0.145 0 0)` | `--foreground` |
| `color.card` | `oklch(1 0 0)` | `--card` |
| `color.card-foreground` | `oklch(0.145 0 0)` | `--card-foreground` |
| `color.popover` | `oklch(1 0 0)` | `--popover` |
| `color.primary` | `oklch(0.205 0 0)` | `--primary` |
| `color.primary-foreground` | `oklch(0.985 0 0)` | `--primary-foreground` |
| `color.secondary` | `oklch(0.97 0 0)` | `--secondary` |
| `color.muted` | `oklch(0.97 0 0)` | `--muted` |
| `color.muted-foreground` | `oklch(0.556 0 0)` | `--muted-foreground` |
| `color.accent` | `oklch(0.97 0 0)` | `--accent` |
| `color.destructive` | `oklch(0.577 0.245 27.325)` | `--destructive` |
| `color.border` | `oklch(0.922 0 0)` | `--border` |
| `color.input` | `oklch(0.922 0 0)` | `--input` |
| `color.ring` | `oklch(0.708 0 0)` | `--ring` |
### Colors — Dark Mode [沿用]
| Token | Value (oklch) |
|-------|---------------|
| `color.background` | `oklch(0.145 0 0)` |
| `color.foreground` | `oklch(0.985 0 0)` |
| `color.card` | `oklch(0.205 0 0)` |
| `color.primary` | `oklch(0.922 0 0)` |
| `color.primary-foreground` | `oklch(0.205 0 0)` |
| `color.secondary` | `oklch(0.269 0 0)` |
| `color.muted` | `oklch(0.269 0 0)` |
| `color.muted-foreground` | `oklch(0.708 0 0)` |
| `color.destructive` | `oklch(0.704 0.191 22.216)` |
| `color.border` | `oklch(1 0 0 / 10%)` |
| `color.input` | `oklch(1 0 0 / 15%)` |
| `color.ring` | `oklch(0.556 0 0)` |
### Semantic 擴充 [新增]
以下 semantic token 在原專案沒有明確定義，local 版補齊供狀態顯示用：
| Token | Light | Dark | 用途 |
|-------|-------|------|------|
| `color.success` | `oklch(0.65 0.17 145)` | `oklch(0.75 0.17 145)` | 裝置 Ready、推論成功 |
| `color.warning` | `oklch(0.75 0.18 85)` | `oklch(0.80 0.18 85)` | Mock badge、警告訊息 |
| `color.info` | `oklch(0.60 0.15 240)` | `oklch(0.70 0.15 240)` | 資訊提示 |
| `color.mock-badge.bg` | `oklch(0.88 0.15 85)` | `oklch(0.35 0.15 85)` | Mock 模式 badge 背景 |
| `color.mock-badge.fg` | `oklch(0.30 0.18 85)` | `oklch(0.92 0.12 85)` | Mock 模式 badge 文字 |
### Typography [沿用 + 新增]
| Token | Value | 備註 |
|-------|-------|------|
| `font.family.sans` | 見 `06-cross-platform §6.5` | 跨平台 system font stack |
| `font.family.mono` | 見 `06-cross-platform §6.5` | Log viewer |
| `font.size.xs` | `12px` | [沿用] |
| `font.size.sm` | `13px` | [微調] 桌面 app 密度略高於 web，body 從 14 改 13 |
| `font.size.base` | `14px` | [微調] 原 16，桌面常用 14 |
| `font.size.lg` | `16px` | [沿用] |
| `font.size.xl` | `18px` | [沿用] |
| `font.size.2xl` | `22px` | [沿用] |
| `font.size.3xl` | `28px` | [沿用] |
| `font.size.4xl` | `32px` | First-Run welcome |
| `font.weight.regular` | `400` | |
| `font.weight.medium` | `500` | |
| `font.weight.semibold` | `600` | |
| `font.weight.bold` | `700` | |
| `font.line-height.tight` | `1.2` | |
| `font.line-height.normal` | `1.5` | |
| `font.line-height.relaxed` | `1.75` | |
### Spacing [沿用 — tailwind 4 預設]
| Token | Value |
|-------|-------|
| `space.0` | `0` |
| `space.1` | `4px` |
| `space.2` | `8px` |
| `space.3` | `12px` |
| `space.4` | `16px` |
| `space.5` | `20px` |
| `space.6` | `24px` |
| `space.8` | `32px` |
| `space.10` | `40px` |
| `space.12` | `48px` |
| `space.16` | `64px` |
### Radius [沿用]
| Token | Value | 對應原變數 |
|-------|-------|-----------|
| `radius.sm` | `calc(var(--radius) - 4px)` = `6px` | `--radius-sm` |
| `radius.md` | `calc(var(--radius) - 2px)` = `8px` | `--radius-md` |
| `radius.lg` | `var(--radius)` = `10px` | `--radius-lg` |
| `radius.xl` | `calc(var(--radius) + 4px)` = `14px` | `--radius-xl` |
| `radius.2xl` | `calc(var(--radius) + 8px)` = `18px` | `--radius-2xl` |
| `radius.full` | `9999px` | 圓形 avatar、pill |
基礎 `--radius = 0.625rem (10px)`。
### Elevation [新增]
桌面 app 需要比 web 更清晰的 z-depth：
| Token | Light shadow | Dark shadow | 用途 |
|-------|-------------|-------------|------|
| `elevation.0` | `none` | `none` | Flat |
| `elevation.1` | `0 1px 2px rgba(0,0,0,0.06)` | `0 1px 2px rgba(0,0,0,0.4)` | Card |
| `elevation.2` | `0 2px 4px rgba(0,0,0,0.08)` | `0 2px 4px rgba(0,0,0,0.5)` | Hover card |
| `elevation.3` | `0 4px 12px rgba(0,0,0,0.10)` | `0 4px 12px rgba(0,0,0,0.55)` | Dropdown、popover |
| `elevation.4` | `0 8px 24px rgba(0,0,0,0.15)` | `0 8px 24px rgba(0,0,0,0.65)` | Modal、drawer |
### Motion [新增]
| Token | Value | 用途 |
|-------|-------|------|
| `motion.duration.instant` | `100ms` | Micro-feedback |
| `motion.duration.fast` | `150ms` | Button hover、tab switch |
| `motion.duration.normal` | `250ms` | Modal open、drawer slide |
| `motion.duration.slow` | `400ms` | Page transition |
| `motion.easing.standard` | `cubic-bezier(0.4, 0, 0.2, 1)` | 預設 |
| `motion.easing.decelerate` | `cubic-bezier(0, 0, 0.2, 1)` | 進入動畫 |
| `motion.easing.accelerate` | `cubic-bezier(0.4, 0, 1, 1)` | 離開動畫 |
遵守 `prefers-reduced-motion`：所有 duration > `instant` 都要在使用者開啟 reduced motion 時改為 `0ms` 或 `instant`。
## 7.3 Component Tokens（重點元件）
### Sidebar
| Token | Value |
|-------|-------|
| `sidebar.width.expanded` | `240px` |
| `sidebar.width.collapsed` | `64px` |
| `sidebar.background` | `color.card` |
| `sidebar.border` | `1px solid color.border`（右邊） |
| `sidebar.item.height` | `44px` |
| `sidebar.item.padding` | `space.3 space.4` |
| `sidebar.item.radius` | `radius.md` |
| `sidebar.item.active.bg` | `color.primary` |
| `sidebar.item.active.fg` | `color.primary-foreground` |
| `sidebar.item.hover.bg` | `color.accent` |
### Header
| Token | Value |
|-------|-------|
| `header.height` | `56px` |
| `header.background` | `color.background` |
| `header.border` | `1px solid color.border`（下邊） |
| `header.padding` | `space.4 space.6` |
### Card
| Token | Value |
|-------|-------|
| `card.background` | `color.card` |
| `card.border` | `1px solid color.border` |
| `card.radius` | `radius.lg` |
| `card.padding` | `space.5` |
| `card.shadow` | `elevation.1` |
| `card.hover.shadow` | `elevation.2` |
### Button
| Size | Height | Padding | Font size | Radius |
|------|--------|---------|-----------|--------|
| `sm` | `32px` | `space.2 space.3` | `font.size.sm` | `radius.md` |
| `md` | `40px` | `space.2 space.4` | `font.size.base` | `radius.md` |
| `lg` | `48px` | `space.3 space.6` | `font.size.lg` | `radius.lg` |
Variants：`primary`、`secondary`、`ghost`、`destructive`、`outline`（沿用 shadcn 定義）。
### Mock Badge [新增]
| Token | Value |
|-------|-------|
| `badge.mock.bg` | `color.mock-badge.bg` |
| `badge.mock.fg` | `color.mock-badge.fg` |
| `badge.mock.padding` | `space.1 space.2` |
| `badge.mock.radius` | `radius.full` |
| `badge.mock.font-size` | `font.size.xs` |
| `badge.mock.font-weight` | `font.weight.semibold` |
| `badge.mock.border` | `1px solid currentColor` |
## 7.4 與原專案 tokens 的差異摘要
| 項目 | 改動 | 原因 |
|------|------|------|
| body font size | 16 → 14 | 桌面 app 資訊密度要求 |
| 新增 `color.success/warning/info` | — | 原專案沒有明確 semantic color |
| 新增 `color.mock-badge.*` | — | Mock 模式專用視覺 |
| 新增 `elevation.*` | — | 原專案 shadow 只用 tailwind 預設 |
| 新增 `motion.*` | — | 統一動畫語言 |
| 其他 | 完全沿用 | shadcn 架構已足夠 |
## 7.5 Token 落地檔案建議
```
frontend/
├─ src/styles/tokens.css ← 所有 CSS variables
├─ src/styles/globals.css ← import tokens.css
└─ tailwind.config.ts ← extend theme 引用 tokens
```
沿用原專案的 CSS variable 命名（`--primary` 等），不做全面改名，以減少沿用原元件的改動成本。
## 7.6 深色模式切換（第四輪定案）
深色模式的切換**完全靠 CSS `prefers-color-scheme` media query**，**不需要 JS / Wails emit event**。三平台 WebView（macOS WKWebView、Windows WebView2、Linux WebKit2GTK）皆原生支援系統主題即時同步。
實作方式：
```css
/* tokens.css */
:root {
--background: oklch(1 0 0);
/* ...其他 light tokens */
}
@media (prefers-color-scheme: dark) {
:root {
--background: oklch(0.145 0 0);
/* ...其他 dark tokens */
}
}
```
或用 Tailwind `dark:` variant（需設定 `darkMode: 'media'` 而非 `'class'`）。
細節見 `06-cross-platform.md §6.8`。

254
local-tool/.autoflow/03-design/spec/08-states.md Normal file
View File

@ -0,0 +1,254 @@
# 08 — 錯誤狀態與空狀態設計方向
## 8.1 錯誤狀態分級
| 級別 | 範例情境 | 視覺語彙 | UX 回應 |
|------|---------|---------|--------|
| **Critical** | Server 啟動失敗、崩潰 | 全螢幕錯誤頁 + 紅色 | 提供重啟、查看日誌、回報問題 |
| **Error** | 模型載入失敗、USB 連線中斷 | Toast (destructive) + 頁面 inline error | 提供重試、排錯提示 |
| **Warning** | Mock 模式運行中、未簽章警告 | Badge / Banner (warning) | 持續顯示，資訊性質 |
| **Info** | 操作成功、模型已切換 | Toast (success/info) | 3 秒自動消失 |
## 8.2 全域錯誤頁（Critical）
當 Server 無法啟動或崩潰，整個前端顯示：
```
┌──────────────────────────────────────────────┐
│ │
│ ⚠ │
│ │
│ Server 無法啟動 │
│ │
│ 錯誤原因：Port 3721 已被其他程式佔用 │
│ │
│ [重新啟動 Server] [更改 Port] │
│ [查看日誌] [回報問題] │
│ │
│ 技術資訊 ▾ (點擊展開 stacktrace) │
│ │
└──────────────────────────────────────────────┘
```
**規格**：
- 置中佈局，最大寬度 560px
- 主標題 `font.size.3xl / semibold`
- 錯誤原因用純文字（友善語氣，非 raw error）
- 技術資訊預設收合，展開後顯示 monospace 的 raw error log
- CTA 按鈕橫排，主要動作用 `primary`
**常見錯誤 + 對應文案**：
| 錯誤類型 | 友善描述 | 建議動作 |
|---------|---------|---------|
| Port 衝突 | Port {port} 已被其他程式佔用 | 更改 Port / 關閉佔用程式 |
| Python venv 建立失敗 | 無法建立 Python 環境，可能缺少系統套件 | 查看日誌 / 重新安裝 |
| KneronPLUS 載入失敗 | 無法載入 Kneron SDK | 檢查裝置 / 切到 Mock 模式 |
| 磁碟空間不足 | 磁碟空間不足，無法啟動 | 清理磁碟 |
| 未知錯誤 | Server 發生未預期錯誤 | 重啟 / 查看日誌 / 回報 |
## 8.3 Inline Error（Error level）
當頁面部分區塊載入失敗：
```
┌─ Models ─────────────────────────┐
│ │
│ ⚠ │
│ 無法載入模型清單 │
│ 可能是 server 暫時無法回應 │
│ │
│ [重試] │
│ │
└──────────────────────────────────┘
```
**規格**：置中於所在區塊，icon 48px，提供單一主要動作（重試）。
## 8.4 Toast 規格
```
位置：右上角（距邊 16px）
寬度：固定 360px（行動裝置尺寸下改全寬 - 32px）
高度：自適應（最低 56px）
堆疊：多個 toast 垂直堆疊，間隔 8px
最多同時顯示：4 個（超過的排隊）
```
**Variants**：
| Variant | 背景 | 前景 | icon | 預設停留 |
|---------|------|------|------|---------|
| `success` | `color.success` (8% opacity) | `color.success` | ✓ | 3s |
| `info` | `color.info` (8% opacity) | `color.info` | ⓘ | 3s |
| `warning` | `color.warning` (10% opacity) | `color.warning` | ⚠ | 5s |
| `destructive` | `color.destructive` (10% opacity) | `color.destructive` | ⊗ | 持續（需手動關） |
**結構**：
```
┌─────────────────────────────────────┐
│ [icon] 主要訊息 ✕ │
│ 次要說明（可選） │
│ [動作]（可選） │
└─────────────────────────────────────┘
```
**動畫**：
- 進入：slide-in-right + fade-in，`motion.duration.normal` + `motion.easing.decelerate`
- 離開：fade-out，`motion.duration.fast`
## 8.5 空狀態（Empty States）
所有空狀態遵循統一結構：**Icon + 標題 + 次要描述 + 主要 CTA (+ 次要 CTA)**
### 通用樣板
```
┌──────────────────────────────────────┐
│ │
│ [icon 64px] │
│ │
│ [標題 — 說明沒有什麼] │
│ [次要描述 — 為什麼沒有、該做什麼] │
│ │
│ [主要 CTA] [次要 CTA] │
│ │
└──────────────────────────────────────┘
```
### 空狀態清單
| 頁面 | 情境 | Icon | 標題 | 描述 | 主 CTA | 次 CTA |
|------|------|------|------|------|-------|-------|
| Models | 無任何模型 | 📦 | 還沒有模型 | 上傳一個 .nef 檔案開始使用，或啟用預置模型 | 上傳模型 | 啟用預置模型 |
| Devices (Real) | 無裝置 | 🔌 | 沒有偵測到 Kneron 裝置 | 接上 USB 裝置後會自動顯示 | 重新掃描 | 切到 Mock 模式 |
| Devices (Mock) | 永遠有 3 顆假裝置 | — | — | — | — | — |
| Workspace | 無裝置 | ▶ | 還沒有可用的裝置 | 先到 Devices 接上裝置，或切到 Mock 模式 | 前往 Devices | 切到 Mock |
| Workspace > Batch | 無上傳圖片 | 🖼 | 還沒有圖片 | 拖放圖片檔到此處，或點選上傳 | 上傳圖片 | — |
| Workspace > Video | 無上傳影片 | 🎞 | 還沒有影片 | 拖放影片檔開始推論 | 上傳影片 | — |
| Dashboard > Activity | 無活動紀錄 | 🕒 | 還沒有任何活動 | 開始使用後，這裡會顯示最近的事件 | — | — |
| Settings > 模型 > 自訂路徑 | 無自訂路徑 | 📁 | 沒有自訂模型路徑 | 新增資料夾讓 App 自動載入其中的 .nef | 新增路徑 | — |
### 空狀態的「正向語氣」原則
- 不用「沒有」「無」開頭 — 用「還沒有」（暗示「之後會有」）
- 主 CTA 用動詞 —「上傳」「前往」「切換」
- 描述要告訴使用者**為什麼會空** +**怎麼讓它不空**
## 8.6 載入狀態
| 場景 | 方案 |
|------|------|
| 頁面初次載入 | Skeleton（沿用 shadcn skeleton 元件） |
| 清單刷新 | Top bar 細線 progress bar（2px，無確定進度） |
| 按鈕執行中 | Button 內 spinner + 文字改為「...中」 |
| 長時間操作（> 3 秒） | Modal + 進度條 + 可取消按鈕 |
| Mock 模式假進度 | 遵循真實時間，不要故意 fake 慢 |
## 8.7 破壞性操作確認
| 操作 | 確認強度 |
|------|---------|
| 切換 Mock/Real 模式 | Dialog 確認（說明會中斷正在進行的推論） |
| 刪除單一模型 | Dialog 確認（顯示模型名稱） |
| 清除所有快取 | Dialog 確認 |
| 重置所有設定 | 雙重確認（需輸入 `RESET` 字樣） |
| 結束 App（主視窗關閉） | **無確認**（Q7 決策：傳統式，直接結束） |
所有確認對話框使用 `destructive` 按鈕樣式在主動作上，次要動作（取消）用 `ghost`。
## 8.8 Python sidecar 專用狀態（第四輪新增）
**背景**：Architect `tray-and-lifecycle.md §4.3`（或等效章節）規劃 Python sidecar「空閒 N 分鐘自動 kill、崩潰時 Go server 自動重啟最多 3 次」。這些生命週期事件對使用者來說都是**「按下 Start 後 1-3 秒無回應」**的體驗斷裂，必須有明確的前端呈現。
### 8.8.1 自動重啟 loading（崩潰後）
**觸發**：Go server 偵測到 Python sidecar exit code ≠ 0，前端透過 WebSocket 事件 `sidecar.state` 收到 `restarting`。
**呈現**：Workspace 的 Camera Feed 區塊**覆蓋一層半透明 overlay**，顯示：
```
┌──── Camera Feed ────────────────┐
│ │
│ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │
│ ░ ░ │
│ ░ ⟳ ░ │
│ ░ 推論引擎正在重新啟動 ░ │
│ ░ （第 1/3 次） ░ │
│ ░ ░ │
│ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │
│ │
└─────────────────────────────────┘
```
- 背景：`color.background` + 60% opacity 黑色覆蓋
- Spinner：`motion.duration.normal`，不用 progress bar（不知道要多久）
- 文案：「推論引擎正在重新啟動（第 X/3 次）」
- 不阻擋使用者切換到其他頁面（overlay 只蓋在 Camera Feed，Sidebar/Header 仍可互動）
- 重啟成功 → overlay 淡出（300ms）→ 恢復影像串流
- **3 次重啟都失敗** → 進入 8.8.3 的 Critical 錯誤頁
### 8.8.2 空閒被 kill 後的冷啟動（使用者再次按 Start）
**觸發**：使用者閒置超過 Architect 設定的 N 分鐘，sidecar 被 Go server 主動 kill（節省記憶體）。使用者下次按 `[▶ Start]` 時，sidecar 需要 2-3 秒冷啟動。
**呈現**：Start 按鈕進入 loading 狀態 + Camera Feed 顯示 skeleton：
```
[▶ Start] → [⟳ 正在啟動推論引擎...] （按鈕 disabled，aria-busy=true）
Camera Feed 區域：
┌──── Camera Feed ────────────────┐
│ │
│ [Skeleton + 「首次啟動 │
│ 需要 2-3 秒，請稍候」] │
│ │
└─────────────────────────────────┘
```
- Start 按鈕文字即時改為「正在啟動推論引擎...」+ spinner，**不要只靠 disabled** 讓使用者以為當掉
- 預期時間上限 5 秒，超過 → 改顯示「啟動時間較長，請稍候」，10 秒 → 進入錯誤狀態
- 這是**使用者首次按 Start（冷啟動）**或**閒置重啟**時的標準體驗，文案相同
### 8.8.3 Sidecar 3 次重啟失敗（Critical）
**觸發**：Go server 連續重啟 sidecar 3 次都失敗，發送 `sidecar.state = failed`。
**呈現**：Workspace 整區切換為 Critical 錯誤頁（沿用 §8.2 通用全域錯誤頁樣板，但文案與動作為 sidecar-specific）：
```
┌──────────────────────────────────────────────┐
│ │
│ ⚠ │
│ │
│ 推論引擎無法啟動 │
│ │
│ 已嘗試重新啟動 3 次，Python 推論引擎 │
│ 仍無法正常運作。 │
│ │
│ 可能的原因： │
│ • KneronPLUS SDK 與 OS 不相容 │
│ • 內嵌 Python 環境損毀 │
│ • 系統資源不足 │
│ │
│ [手動重試] [切換到系統 Python] │
│ [切到 Mock 模式] [查看 Python 日誌] │
│ │
│ 技術資訊 ▾ (點擊展開 stacktrace) │
│ │
└──────────────────────────────────────────────┘
```
- 「切換到系統 Python」連結到 Settings > 進階的 Python 執行模式（見 `03-wireframes §3.5`）
- 「查看 Python 日誌」開啟 `server-log-viewer` 並 filter 到 sidecar 類別
- OS 原生通知：**同時** shell out 原生通知（因為 Server 崩潰屬 R4-8 定義的嚴重事件），文案「visionA-local：推論引擎無法啟動」
### 8.8.4 與 Architect 的 API 依賴
本節所有呈現都依賴 Architect 提供：
- WebSocket 事件 `sidecar.state`，payload: `{ state: 'starting' | 'running' | 'idle' | 'restarting' | 'failed', attempt?: number }`
- `POST /api/sidecar/restart`（手動重試按鈕）
- `GET /api/sidecar/logs?since=<timestamp>`（日誌 viewer）
**若 Architect 未提供**以上 API/事件，本節狀態無法落地，需在 M2 前與 Architect 對齊。

192
local-tool/.autoflow/03-design/spec/09-accessibility.md Normal file
View File

@ -0,0 +1,192 @@
# 09 — 無障礙（A11y）要求
## 9.0 目標與範圍（第四輪 R4-3 定案）
**目標：盡力而為（best effort），不以 WCAG 2.2 Level AA 為硬性驗收標準。**
原本規劃以「WCAG 2.2 AA 合規」作為硬指標，但第四輪決策 R4-3 將其**從硬目標降級為「盡力而為」**，理由：
- 本產品為**內部工具、工程師族群為主**，非對外公眾服務，無法律合規壓力
- 硬性 AA 驗證（axe serious=0、screen reader 全流程、色彩對比全面實測）會佔用 M1 大量人力，排擠核心功能
- PRD 非功能需求已把 a11y **列入 non-goals**（不做硬性驗證，只列為指引）
**本章角色變更為「a11y 設計指引」**：Design 在元件設計時**參考**本章原則，Frontend 在實作時**盡量**採納，但**不以此作為 code review 或 QA 的 blocker**。
**仍會做的（low cost 的基本盤）**：
- 所有可聚焦元素有 visible focus ring（無額外成本）
- 語意化 HTML（`<button>`、`<nav>`、`<main>`，不用純 `<div>`）
- `<label>` 與 `<input>` 正確關聯
- `aria-label` 給 icon-only button
- 鍵盤可完成核心流程（Tab 順序大致合理即可，不強求完美）
- 尊重 `prefers-reduced-motion`
**不做的（高成本項目，R4-3 後明確排除）**：
- 色彩對比逐一實測（4.5:1、3:1）
- Screen reader 全流程人工驗證（VoiceOver / NVDA）
- axe / Lighthouse 自動掃描作為 CI gate（可跑但不 block）
- Reflow 320px 支援
- ARIA 角色完整覆蓋
- 推論結果的「非視覺呈現」文字清單（原 9.8）
以下各節**作為指引保留**，實作時採納即可；**不列為驗收條件**。
## 9.1 色彩對比
| 元素類型 | 最低對比 | 檢驗方式 |
|---------|---------|---------|
| 正文 body text | 4.5 : 1 | Chrome DevTools contrast checker |
| 大字體（≥18pt 或 ≥14pt bold） | 3 : 1 | 同上 |
| UI 元件（border、icon） | 3 : 1 | 手動檢查 |
| Focus ring | 3 : 1（對周邊背景） | 手動檢查 |
**已知需注意**：
- Dark mode 的 `color.muted-foreground` (oklch 0.708) 對 `color.card` 背景需複測
- Mock badge 的黃底黑字需達 4.5 : 1
## 9.2 觸控／點擊目標
| 元素 | 最小尺寸 |
|------|---------|
| Button / Icon button | 40×40px（桌面 app 可略小於 44，因為用滑鼠） |
| Sidebar item | 44×240px |
| Checkbox / Radio hit area | 32×32px（含 label 區域） |
**桌面 app 例外**：因為主要輸入裝置是滑鼠，可以比 mobile 44×44 稍小，但不能低於 32×32。
## 9.3 鍵盤導航
**所有功能必須可用鍵盤完成**，無 mouse 也能跑完整流程。
### Tab 順序原則
1. Header（幫助按鈕、Mock badge）
2. Sidebar（主導航 1→4，然後 Settings）
3. Content 主區塊（由上到下、由左到右）
4. 頁面內的主 CTA 位置要 Tab-friendly
### 特殊鍵
| 鍵 | 行為 |
|----|------|
| Tab / Shift+Tab | 下一個 / 上一個可聚焦元素 |
| Enter | 啟動按鈕、提交表單 |
| Space | 啟動按鈕、切換 checkbox |
| Esc | 關閉 modal、drawer、tooltip、dropdown menu |
| 方向鍵 | 清單中移動（如 sidebar 項目、model grid） |
| ⌘/Ctrl + K | 保留給未來 command palette（目前不做） |
### Focus Ring
- 所有可聚焦元素必須有可見 focus ring
- 使用 `color.ring` (oklch 0.708 / 0.556)，2px outline + 2px offset
- 不要用 `outline: none` 而不補替代方案
### Skip Link
在 Sidebar 最前面加 `skip to main content` link（預設 `sr-only`，Tab 聚焦時顯示）。
## 9.4 ARIA
### Landmark roles
```html
<aside role="navigation" aria-label="主導航"> <!-- Sidebar -->
<header role="banner"> <!-- Header -->
<main role="main" id="main-content"> <!-- Content -->
```
### 常用 ARIA 屬性
| 場景 | ARIA |
|------|------|
| Sidebar 當前頁 | `aria-current="page"` |
| Tab 群組 | `role="tablist"` / `role="tab"` / `aria-selected` / `aria-controls` |
| Modal 開啟時 | `role="dialog"` / `aria-modal="true"` / `aria-labelledby` |
| Loading 按鈕 | `aria-busy="true"` / `aria-label="載入中"` |
| 禁用按鈕 | `aria-disabled="true"`（不用 `disabled` 屬性以保留可聚焦性） |
| Toast | `role="status"`（success/info）/ `role="alert"`（error） |
| Dropdown | `aria-haspopup="menu"` / `aria-expanded` |
| Mock badge | `role="status"` / `aria-label="目前為 Mock 模式"` |
### 動態內容
Live regions 用 `aria-live`：
| 場景 | `aria-live` |
|------|------------|
| Server 狀態變化 | `polite` |
| 推論結果更新 | `off`（太頻繁會吵） |
| 錯誤訊息 | `assertive` |
| Toast success | `polite` |
## 9.5 圖片與圖示
| 類型 | 標註 |
|------|------|
| 裝飾性圖示 | `aria-hidden="true"` |
| 功能性圖示（icon only button） | `aria-label="動作描述"` |
| 資訊性圖片（logo、插圖） | `alt="..."` |
| 影片 feed（攝影機串流） | `aria-label="即時攝影機畫面"`（無法提供動態描述） |
| 推論結果 overlay（bounding box） | 獨立顯示為清單，不只靠視覺（見 9.8） |
## 9.6 表單
- 所有 input 必須有對應的 `<label>`
- 錯誤訊息用 `aria-describedby` 連結
- 必填欄位用 `aria-required="true"` + 視覺標記 `*`
- 驗證時機：`blur`（失去焦點）+ `submit`
## 9.7 Reduced Motion
偵測 `prefers-reduced-motion: reduce`：
```css
@media (prefers-reduced-motion: reduce) {
*, *::before, *::after {
animation-duration: 0.01ms !important;
transition-duration: 0.01ms !important;
}
}
```
**不要**直接禁用所有動畫 — 有些微小回饋（< 100ms）可以保留，只關閉長動畫與 parallax。
## 9.8 推論結果的非視覺呈現
攝影機串流 + bounding box 對視障使用者幾乎無意義。補償方案：
- Inference panel 同步顯示**文字清單**：「偵測到：人 (信心度 92%)、車 (信心度 85%)」
- 用 `aria-live="polite"` 但節流（每 2 秒更新一次，否則太吵）
- 提供「暫停語音播報」選項
## 9.9 語言與 lang 屬性
- HTML `lang` 屬性隨 i18n 動態切換：`<html lang="zh-TW">` 或 `<html lang="en">`
- 避免混雜未標註語言的文字（如中文頁面中的英文專有名詞用 `<span lang="en">`）
## 9.10 測試與驗證（R4-3 後：不列為硬指標）
> 本節原先定義 Lighthouse a11y ≥ 95、axe 無 critical/serious 的硬指標，**第四輪 R4-3 後改為「建議但非必要」**。
| 工具 | 建議用途（非強制） |
|------|------------------|
| axe DevTools | 開發時期手動自檢常見問題（不納入 CI gate） |
| Lighthouse | 偶爾看一下分數即可（不設最低門檻） |
| 鍵盤測試 | 主要流程用鍵盤跑過一次（核心流程能通即可） |
| Screen reader | **不做**（R4-3 明確排除） |
| 色彩對比 | **不做逐項實測**，依 Design Tokens 的 oklch 色盤視覺合理即可 |
**驗收條件**：無硬性 a11y 驗收條件。若 Frontend 實作時有餘力可追加，不強制。
## 9.11 與 i18n 的互動
中英雙語時注意：
- 英文版某些標籤可能比中文長（如「繼續」vs「Continue」），設計要容錯
- 確認 RTL 不是需求範圍（中英都是 LTR，確認後可放心）
## 9.12 可忽略範圍（需使用者確認）
以下 WCAG 標準因桌面 app 特性可以忽略，列出讓使用者確認：
- **1.4.10 Reflow（320px 寬度可用）** — 桌面 app 最小視窗 960px，不支援 320px
- **2.4.5 Multiple Ways** — 不提供全域搜尋、sitemap（IA 太淺不需要）
- **3.1.4 Abbreviations** — 某些術語（KL720、FPS、.nef）不提供縮寫展開

164
local-tool/.autoflow/03-design/spec/10-i18n.md Normal file
View File

@ -0,0 +1,164 @@
# 10 — i18n 策略
## 10.1 支援語言
| Locale | 顯示名稱 | 備註 |
|--------|---------|------|
| `zh-TW` | 繁體中文 | 主要語言，所有文案以此為準 |
| `en` | English | 次要語言，從繁中翻譯 |
**不支援**：簡體中文、日文、韓文、其他。如有需求另議。
## 10.2 預設策略
**跟隨系統 locale**：
```
系統 locale 偵測流程：
1. 讀取 Wails runtime 提供的系統語言
2. 若為 zh-* (zh-TW, zh-HK, zh-CN) → 使用 zh-TW
3. 其他 → 使用 en
4. 使用者若在 Settings 手動設定，則以手動為準
```
**儲存位置**：資料目錄下 `config.json` 的 `locale` 欄位。各平台資料目錄見 `06-cross-platform.md §6.7`（macOS 為 `~/Library/Application Support/visiona-local/config.json`，第四輪 R4-5 全小寫）。
## 10.3 實作技術
**沿用原 edge-ai-platform 的 i18n 方案**：`react-i18next`（原專案已有 `useTranslation` hook）。
```
frontend/
├─ src/locales/
│ ├─ zh-TW/
│ │ ├─ common.json ← 按鈕、通用詞
│ │ ├─ dashboard.json
│ │ ├─ models.json
│ │ ├─ devices.json
│ │ ├─ workspace.json
│ │ ├─ settings.json
│ │ ├─ first-run.json
│ │ └─ errors.json
│ └─ en/
│ └─ （同上結構）
└─ src/lib/i18n.ts ← i18next 初始化
```
## 10.4 命名慣例
- 命名空間：按頁面或功能區塊（`dashboard`, `models`, `first-run`）
- Key 結構：`namespace:section.key`
- 例：`first-run:welcome.title`、`common:button.continue`
## 10.5 關鍵詞彙統一表
| 繁中 | English | 備註 |
|------|---------|------|
| 裝置 | Device | 不用「設備」 |
| 模型 | Model | — |
| 推論 | Inference | 不用「推理」 |
| 攝影機 | Camera | — |
| 工作區 | Workspace | — |
| 儀表板 | Dashboard | 主區塊直接稱「Dashboard」 |
| 設定 | Settings | 不用「偏好設定」 |
| 真實硬體模式 | Real Hardware | — |
| Mock 模式 | Mock Mode | 中文版也保留 Mock，不翻「模擬」 |
| 連接 | Connect | 動詞 |
| 連線 | Connected | 狀態形容詞 |
| 掃描 | Scan | — |
| 載入 | Load | — |
| 儲存 | Save | 不用「保存」 |
| 刪除 | Delete | — |
| 確定 | OK / Confirm | — |
| 取消 | Cancel | — |
| 關閉 | Close | — |
| 略過 | Skip | — |
## 10.6 特殊狀況
### 數字與單位
- 時間：使用 locale 預設格式（`Intl.DateTimeFormat`）
- 檔案大小：統一用 `KB / MB / GB`（不翻譯）
- 百分比：`92%`（不翻譯）
- FPS、ms 等技術單位：不翻譯
### 日期時間
- 繁中：`2026/04/11 14:30`（ISO 風格）
- English：`Apr 11, 2026, 2:30 PM`
### 複數
英文需要處理單複數：
```json
{
"devices.count_one": "{{count}} device",
"devices.count_other": "{{count}} devices"
}
```
中文不需要處理。
## 10.7 Settings 語言切換 UX
```
┌─ 一般 ────────────────────────┐
│ │
│ 語言 [繁體中文 ▾] │
│ │
│ 選項： │
│ • 跟隨系統（目前：繁中） │
│ • 繁體中文 │
│ • English │
└────────────────────────────────┘
```
**切換行為**：
> ⚠️ **M1 與 M2 差異（與 Architect 對齊）**：**即時切換是 M2 才做**。M1 先以「切換 → 寫入 config.json → 彈 toast 提示『請重啟 App 套用新語言』」的簡化流程上線，避免 M1 就要處理 `react-i18next` 全域 re-render、原生 menu bar 動態重建、錯誤文案快取失效等複雜度。
**M1（簡化版）**：
- 使用者在 Settings > 一般 選擇語言 → 寫入 `config.json` 的 `locale` → 顯示 toast「語言將在下次啟動時套用」+「立即重啟」按鈕
- 「立即重啟」呼叫 Wails Go 端重啟 App
- macOS 原生 menu bar 文字維持**首次啟動時**的 locale
**M2（完整版，即時切換）**：
- 切換後即時生效（不需重啟）
- 所有 UI 文字立即更新（`i18next.changeLanguage()` + React context re-render）
- macOS 原生 menu bar 需動態重建（Wails v2 `menu.Update()`）
- 正在顯示中的 toast／modal／error 文案也要 reload
- 寫入 config.json
## 10.8 原生 menu / OS 通知的 i18n
> 第三輪決策 Q-A 已砍除 tray，本節不再涵蓋 tray menu。
| 項目 | 處理方式 |
|------|---------|
| macOS 原生 menu bar | Wails 啟動時讀取 locale，用對應字串建立 menu；語言切換後**需要重建 menu**（Wails v2 支援 dynamic menu update） |
| OS 通知 | 每次發送時以當前 locale 字串構造 |
| 錯誤對話框 | 同上 |
## 10.9 未翻譯的 fallback
- 某個 key 在 `en` 缺失 → 顯示 `zh-TW` 版本（反之亦然）
- 兩邊都缺 → 顯示 key 本身（開發時容易發現）
- 生產版本 build 時執行 lint：所有頁面使用到的 key 必須在兩個 locale 都存在
## 10.10 文案撰寫原則（繁中）
- 台灣用語：「影片」不用「視頻」、「軟體」不用「軟件」、「程式」不用「程序」
- 語氣：友善但專業（技術工具，不需要太可愛）
- 避免機翻語感：「載入失敗，請再試一次」> 「載入失敗了。請再次嘗試」
- 動詞在前：「儲存變更」> 「將變更儲存」
- 標題用名詞片語：「模型管理」> 「管理你的模型」
- 按鈕用動詞：「上傳」> 「上傳按鈕」
## 10.11 文案撰寫原則（English）
- Sentence case：`Upload model`（非 Title Case `Upload Model`）
- 動詞優先：`Connect device`（主 CTA）
- 簡潔：`Skip`（非 `Click here to skip`）
- 避免縮寫：`Settings`（非 `Pref.`）

113
local-tool/.autoflow/04-architecture/TDD.md Normal file
View File

@ -0,0 +1,113 @@
# 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 | 使用者 | 待確認 |

307
local-tool/.autoflow/04-architecture/api-endpoints.md Normal file
View File

@ -0,0 +1,307 @@
# API Endpoints — visionA-local
> REST + WebSocket 端點清單。來源：`edge-ai-platform/server/internal/api/router.go`
> 決策：保留所有業務 API，砍掉 cluster、relay、tunnel、update 相關。
---
## 1. REST API
### 1.1 /api/system/*（保留，部分精簡）
| Method | Path | 決定 | 備註 |
|--------|------|------|------|
| GET | `/api/system/health` | ✅ 保留 | Wails app 用來確認 server 活著 |
| GET | `/api/system/info` | ✅ 保留 + **擴充** | 顯示版本、OS、uptime、**`actual_port`**（前端依此顯示實際 listen port）、`mode`（mock/real）、`python_mode`（bundled/system） |
| GET | `/api/system/metrics` | ✅ 保留 | CPU / RAM / 裝置數 |
| GET | `/api/system/deps` | ✅ 保留 | 依賴檢查（python / ffmpeg / kneron） |
| POST | `/api/system/restart` | ✅ 保留 | Settings 使用 |
| GET | `/api/system/update-check` | ❌ **刪除** | 使用者決策 Q6 = 不做 auto-update |
| GET | `/api/system/mode` | ➕ **新增** | 回傳當前 inference mode：`{"mode":"mock"\|"real"}` |
| POST | `/api/system/mode` | ➕ **新增** | 切換 Mock ↔ Real，body `{"mode":"mock"\|"real"}`；**不重啟 server**，只切 inference backend（見 `architecture-overview §8`） |
| GET | `/api/system/python-runtime` | ➕ **新增** | 回傳當前 Python 策略：`{"mode":"bundled"\|"system","path":"/.../python3"}` |
| POST | `/api/system/python-runtime` | ➕ **新增** | 切換 Python 策略（下次重啟 server 生效），body `{"mode":"auto"\|"bundled"\|"system"}` |
| POST | `/api/system/port` | ➕ **新增** | 修改 server listen port：body `{"port":3721}`；flow 見 §6 |
### 1.2 /api/models/*（全保留）
| Method | Path | 決定 |
|--------|------|------|
| GET | `/api/models` | ✅ |
| GET | `/api/models/:id` | ✅ |
| POST | `/api/models/upload` | ✅ |
| DELETE | `/api/models/:id` | ✅ |
### 1.3 /api/devices/*（保留核心，砍掉 flash）
| Method | Path | 決定 | 備註 |
|--------|------|------|------|
| GET | `/api/devices` | ✅ | |
| POST | `/api/devices/scan` | ✅ | |
| GET | `/api/devices/:id` | ✅ | |
| POST | `/api/devices/:id/connect` | ✅ | |
| POST | `/api/devices/:id/disconnect` | ✅ | |
| POST | `/api/devices/:id/flash` | ❌ **刪除** | 使用者決策 Q9 = 砍掉韌體燒錄 |
| POST | `/api/devices/:id/inference/start` | ✅ | |
| POST | `/api/devices/:id/inference/stop` | ✅ | |
### 1.4 /api/camera/*（全保留）
| Method | Path | 決定 |
|--------|------|------|
| GET | `/api/camera/list` | ✅ |
| POST | `/api/camera/start` | ✅ |
| POST | `/api/camera/stop` | ✅ |
| GET | `/api/camera/stream` | ✅ |
### 1.5 /api/media/*（全保留，包括 url 與 yt-dlp）
| Method | Path | 決定 | 備註 |
|--------|------|------|------|
| POST | `/api/media/upload/image` | ✅ | |
| POST | `/api/media/upload/video` | ✅ | |
| POST | `/api/media/upload/batch-images` | ✅ | |
| GET | `/api/media/batch-images/:index` | ✅ | |
| POST | `/api/media/url` | ✅ | 使用者決策 Q10 = 保留 yt-dlp |
| POST | `/api/media/seek` | ✅ | |
### 1.6 /api/clusters/*（全砍）
| Method | Path | 決定 |
|--------|------|------|
| GET | `/api/clusters` | ❌ |
| POST | `/api/clusters` | ❌ |
| GET | `/api/clusters/:id` | ❌ |
| DELETE | `/api/clusters/:id` | ❌ |
| POST | `/api/clusters/:id/devices` | ❌ |
| DELETE | `/api/clusters/:id/devices/:deviceId` | ❌ |
| PUT | `/api/clusters/:id/devices/:deviceId/weight` | ❌ |
| POST | `/api/clusters/:id/flash` | ❌ |
| POST | `/api/clusters/:id/inference/start` | ❌ |
| POST | `/api/clusters/:id/inference/stop` | ❌ |
### 1.7 其他（全砍）
| Method | Path | 決定 | 備註 |
|--------|------|------|------|
| GET | `/auth/token` | ❌ | relay token endpoint，local 無需 |
| OPTIONS | `/auth/token` | ❌ | 同上 |
## 2. WebSocket
| Path | 決定 | 備註 |
|------|------|------|
| `/ws/devices/events` | ✅ 保留 | 裝置插拔事件推送 |
| `/ws/devices/:id/flash-progress` | ❌ **刪除** | flash 已砍 |
| `/ws/devices/:id/inference` | ✅ 保留 | 推論結果 streaming |
| `/ws/server-logs` | ✅ 保留 | Settings 頁的即時 log |
| `/ws/clusters/:id/inference` | ❌ **刪除** | cluster 已砍 |
| `/ws/clusters/:id/flash-progress` | ❌ **刪除** | 同上 |
## 3. IPC（visionA-local 內部）
這是 **新增**的，給 single-instance lock 用，詳見 [`tray-and-lifecycle.md`](./tray-and-lifecycle.md)（lifecycle 章節）§2.3：
| Method | Path | 說明 |
|--------|------|------|
| GET | `/ipc/raise` | 讓已存在的 instance 浮到前景 |
| GET | `/ipc/status` | 回傳 server port、版本、pid 等 |
這些 endpoint **不是**由 Go server 提供，而是 Wails app 自己起一個極小的 HTTP listener（bound 到 localhost:random），供同機器的 visionA-local 程序間通訊。Port 號寫在各平台資料目錄下的 `visiona-local.ipc-port`（macOS：`~/Library/Application Support/visiona-local/`；Windows：`%APPDATA%\visiona-local\`；Linux：`~/.local/share/visiona-local/`）。
## 3.1 順序修正提醒
上面把模式 / runtime / port 切換流程放在 §5、拖放代理放在 §6、前端 client 清理放在 §7，原本的 §4 router.go 結構保持不變。
## 4. 新版 `router.go` 簡化後結構
```go
// server/internal/api/router.go
func NewRouter(
modelRepo *model.Repository,
modelStore *model.ModelStore,
deviceMgr *device.Manager,
cameraMgr *camera.Manager,
// ❌ clusterMgr 移除
// ❌ flashSvc 移除
inferenceSvc *inference.Service,
wsHub *ws.Hub,
staticFS http.FileSystem,
logBroadcaster *logger.Broadcaster,
systemHandler *handlers.SystemHandler,
// ❌ relayToken 移除
) *gin.Engine {
r := gin.New()
r.Use(gin.Recovery())
r.Use(broadcasterLogger(logBroadcaster))
r.Use(CORSMiddleware())
modelHandler := handlers.NewModelHandler(modelRepo)
modelUploadHandler := handlers.NewModelUploadHandler(modelRepo, modelStore)
deviceHandler := handlers.NewDeviceHandler(deviceMgr, inferenceSvc, wsHub) // flashSvc 拿掉
cameraHandler := handlers.NewCameraHandler(cameraMgr, deviceMgr, inferenceSvc, wsHub)
api := r.Group("/api")
{
// System
api.GET("/system/health", systemHandler.HealthCheck)
api.GET("/system/info", systemHandler.Info)
api.GET("/system/metrics", systemHandler.Metrics)
api.GET("/system/deps", systemHandler.Deps)
api.POST("/system/restart", systemHandler.Restart)
// ❌ /system/update-check 移除
// Models
api.GET("/models", modelHandler.ListModels)
api.GET("/models/:id", modelHandler.GetModel)
api.POST("/models/upload", modelUploadHandler.UploadModel)
api.DELETE("/models/:id", modelUploadHandler.DeleteModel)
// Devices
api.GET("/devices", deviceHandler.ListDevices)
api.POST("/devices/scan", deviceHandler.ScanDevices)
api.GET("/devices/:id", deviceHandler.GetDevice)
api.POST("/devices/:id/connect", deviceHandler.ConnectDevice)
api.POST("/devices/:id/disconnect", deviceHandler.DisconnectDevice)
// ❌ /devices/:id/flash 移除
api.POST("/devices/:id/inference/start", deviceHandler.StartInference)
api.POST("/devices/:id/inference/stop", deviceHandler.StopInference)
// Camera
api.GET("/camera/list", cameraHandler.ListCameras)
api.POST("/camera/start", cameraHandler.StartPipeline)
api.POST("/camera/stop", cameraHandler.StopPipeline)
api.GET("/camera/stream", cameraHandler.StreamMJPEG)
// Media
api.POST("/media/upload/image", cameraHandler.UploadImage)
api.POST("/media/upload/video", cameraHandler.UploadVideo)
api.POST("/media/upload/batch-images", cameraHandler.UploadBatchImages)
api.GET("/media/batch-images/:index", cameraHandler.GetBatchImageFrame)
api.POST("/media/url", cameraHandler.StartFromURL)
api.POST("/media/seek", cameraHandler.SeekVideo)
// ❌ /clusters/* 全部移除
}
// ❌ /auth/token 移除
// WebSocket
r.GET("/ws/devices/events", ws.DeviceEventsHandler(wsHub, deviceMgr))
// ❌ /ws/devices/:id/flash-progress 移除
r.GET("/ws/devices/:id/inference", ws.InferenceHandler(wsHub, inferenceSvc))
r.GET("/ws/server-logs", ws.ServerLogsHandler(wsHub, logBroadcaster))
// ❌ /ws/clusters/* 全部移除
// Embedded frontend
if staticFS != nil {
fileServer := http.FileServer(staticFS)
r.GET("/_next/*filepath", func(c *gin.Context) { fileServer.ServeHTTP(c.Writer, c.Request) })
r.GET("/favicon.ico", func(c *gin.Context) { fileServer.ServeHTTP(c.Writer, c.Request) })
r.NoRoute(spaFallback(staticFS))
}
return r
}
```
## 5. 模式 / Runtime / Port 切換流程
### 5.1 Mock ↔ Real 模式切換（`POST /api/system/mode`）
不重啟 server，只切 inference backend：
```
前端 POST /api/system/mode {"mode":"real"}
↓
Go server: device.Manager.SetMode("real")
├─ 若原為 mock → spawn Python sidecar → kneron_bridge scan → 回填 registry
└─ 若原為 real → kill Python sidecar → 載入 mock devices
↓
broadcast 200 OK + WebSocket /ws/devices/events push "mode_changed"
↓
前端重新拉 /api/devices 與 /api/system/info
```
所有進行中的 inference session 強制終止，使用者收到 toast：「模式已切換，請重新啟動推論」。
### 5.2 Python Runtime 切換（`POST /api/system/python-runtime`）
切換不即時生效（需重啟 Go server 子行程）：
```
前端 POST /api/system/python-runtime {"mode":"system"}
↓
Go server: 寫入 .installed 的 python.mode 欄位
↓
回應 200 + {"needs_restart": true}
↓
前端顯示「需重啟 server 才會生效，立即重啟？」
→ 使用者同意 → 呼叫 POST /api/system/restart
→ Wails app 接收 → kill 當前 Go server 子行程 → 用新 python mode 重 spawn
```
### 5.3 Port 變更（`POST /api/system/port`）
**Port 修改走「持久化 → 重啟 server 子行程 → Wails WebView 重連」流程**：
```
前端 POST /api/system/port {"port":3722}
↓
Go server 驗證 port 可用（若不可用回 409）
↓
Go server 寫入 config.json 的 port 欄位（持久化到資料目錄）
↓
Go server 回應 200 + {"new_port":3722,"needs_restart":true}
↓
前端通知 Wails app 透過 bind API: runtime.RequestServerRestart(3722)
↓
Wails app:
1. 儲存 pending_new_port=3722 到記憶體
2. kill 當前 Go server 子行程（SIGTERM → 3s timeout → SIGKILL）
3. 用新 port spawn 新的 Go server 子行程
4. waitHealthy(3722, 10s)
5. WebView.Reload("http://127.0.0.1:3722/")
↓
前端重新載入並顯示新 port
```
**失敗回退**：若新 port spawn 失敗，Wails app 用舊 port 重啟，並顯示錯誤 toast。config.json 不回滾（使用者可自行修正）。
### 5.4 Port picking 後顯示實際 port
使用者未指定時走 `pickPort(3721)`，結果可能落在 3722/3723... 前端取得方式：
```
前端啟動 → GET /api/system/info → 取 data.actual_port
前端 Sidebar/Settings → 顯示「Server listening on 127.0.0.1:{actual_port}」
```
## 6. 拖放檔案代理上傳
Wails v2 `OnFileDrop` 回傳絕對路徑，不是 File 物件。前端不能直接 FormData 上傳，必須走 Wails 代理：
```
使用者拖 .nef → Wails WebView 捕獲
↓
Wails Go 端 runtime.OnFileDrop([]string{abs_path})
↓
Wails 透過 Bind API 把路徑陣列 emit 給前端
↓
前端呼叫 window.runtime.UploadFileByPath(path, "/api/models/upload")
↓
Wails Go 端讀檔 → 包成 multipart/form-data → POST http://127.0.0.1:{port}/api/models/upload
↓
Go server 走原本的 upload handler，無需修改
```
詳見 `architecture-overview.md §9`。
## 7. 對應的前端 API client 清理
`frontend/src/lib/api/` 底下需要刪除：
- `clusters.ts`
- `relay.ts`（若存在）
- `update.ts`（若存在）
- `flash.ts`（若獨立檔案）
保留其他所有 API client。

189
local-tool/.autoflow/04-architecture/architect-analysis-round1.md Normal file
View File

@ -0,0 +1,189 @@
# Architect Round 1 — 技術可行性分析與重大決策
> 目的：visionA-local 第一輪技術評估。不寫完整 TDD，只列架構方向、關鍵風險、待決問題。
> 作者：Architect Agent ｜ 日期：2026-04-10
## 1. 整體架構方案
**採用「Wails 殼 + Go Server 子程序 + Python sidecar」三層結構**，而非 single binary。理由：
原 `edge-ai-platform` 已經跑通 `installer/`（Wails）把 `edge-ai-server`（Go binary，內含 go:embed 的 Next.js）作為「payload」解壓到使用者目錄後啟動。這個拆分是**對的**，不該改成單一 binary：
- Go server 本身要長時間持續跑（serve HTTP、WebSocket、管理 USB 裝置），Wails 前端則是 UI 殼；把兩者綁在同一個行程會讓 UI 當掉時連服務也一起掛。
- Python KneronPLUS SDK 必須由獨立 `python3` interpreter 執行，無法塞進 Go binary，註定要用 sidecar（`os/exec` 叫 `scripts/kneron_bridge.py`），Go server 仍是中介。
- Wails 本來就適合做「啟動器 + 控制台」，現有 `installer/app.go` 已有 894 行成熟程式碼、含系統資訊偵測、進度回報、裝置偵測、瀏覽器開啟等——**幾乎可以直接改名沿用**。
**建議架構：**
```
visionA-local.app (Wails 二進位)
├─ 內嵌 payload（go:embed installer/payload/...）
│ ├─ edge-ai-server ← Go binary（含 embedded Next.js）
│ ├─ data/ ← models.json + 預置 .nef (~73MB)
│ └─ scripts/
│ ├─ kneron_bridge.py
│ ├─ requirements.txt
│ ├─ KneronPLUS-*.whl ← 每平台一份 wheel
│ └─ (ffmpeg binary — 新增)
├─ 首次執行 → 解壓到 ~/.visiona-local/
├─ 建立 venv + pip install requirements + KneronPLUS wheel
└─ 啟動 edge-ai-server 子行程 → 開啟內嵌 WebView 指向 http://127.0.0.1:3721
```
Wails 殼同時扮演：首次安裝精靈、Tray/常駐、啟動/停止 server、查看 log。第二次執行直接 detect 到已安裝、跳過解壓。
## 2. 依賴內嵌策略（關鍵）
### 2.1 Python Runtime
**結論：不要內嵌 Python runtime，改為「偵測 + 自動安裝系統 Python」。**
| 平台 | 策略 |
|------|------|
| macOS | 首選：使用者系統已有的 `python3`（macOS 12+ 幾乎都有）。無則呼叫 Homebrew 安裝（現有程式碼已有 `brew install python@3.12` 流程） |
| Windows | 首選：`winget install Python.Python.3.12`。備援：從 python.org 下載 embedded zip |
| Ubuntu | `apt-get install python3 python3-venv python3-pip`（需 sudo polkit 提權） |
**不採用 python-build-standalone / PyInstaller 的原因：**
- KneronPLUS wheel 綁定 `pyusb` + 原生 libusb，用 embedded Python 時 site-packages 的 C extension 常踩到 ABI 問題
- 每平台都內嵌完整 Python 會讓安裝檔大約 +40MB，且升級 Python 需要重發整包
- 現有 `installer/app.go` 的 `setupPythonVenv()` 邏輯已在 macOS/Windows/Linux 跑通，包含 linux 缺 `ensurepip` 的 fallback
**代價：** 使用者需要能連網做一次 `pip install`。如需完全離線，第二階段可改為 bundle wheels + `pip install --no-index --find-links`（requirements.txt 只有 numpy / opencv-python-headless / pyusb 三個，加上 KneronPLUS 共 ~80MB wheels）。**建議採「離線 wheel」路線**——完全符合「一鍵安裝不需連網」的要求。
### 2.2 KneronPLUS SDK
**結論：每平台打包對應的 wheel，透過 `pip install` 解壓到 venv。原 `installer/wheels/` 已有三平台的 wheel（共 3.9MB）。**
| 平台 | wheel 狀態 | 原生函式庫 | 注意事項 |
|------|-----------|-----------|---------|
| macOS | `KneronPLUS-2.0.0-*.whl`（含 `.dylib`） | kp/lib/*.dylib | 需要 **ad-hoc codesign**（已有程式碼）否則 Gatekeeper 擋 |
| Linux | `KneronPLUS-2.0.0 / 3.1.2-*.whl`（含 `.so`） | kp/lib/*.so | 需要 libusb-1.0（`apt-get install libusb-1.0-0`）+ udev rule 讓非 root 使用者能存取 USB |
| Windows | `KneronPLUS-3.1.2-*.whl`（含 `.dll`） | kp/lib/*.dll + libusb-1.0.dll | 需要安裝 WinUSB driver（已有 `installer/drivers/kneron_winusb.inf`）— **這一步可能需要使用者手動同意 UAC** |
**USB driver 是風險點：** Windows 必須裝 WinUSB driver 才能讓 libusb 存取裝置，現有程式碼透過 `pnputil` 或類似方式自動安裝，會彈 UAC。Linux 需要寫入 `/etc/udev/rules.d/99-kneron.rules` 也要 sudo。macOS 完全不需要 driver（IOUSB 直接用）。**這點要在 PRD 裡寫成「首次啟動需管理員權限」。**
### 2.3 ffmpeg
**結論：內嵌靜態 binary，不要走 brew/winget。**
| 平台 | 來源 | 大小 | 授權 |
|------|------|------|------|
| macOS (Intel + ARM) | evermeet.cx 的 static build，或 BtbN GitHub Release | ~40MB | LGPL build（**不要用 GPL 版**，避免產品須開源） |
| Windows | gyan.dev 或 BtbN 的 essentials_build | ~50MB | LGPL |
| Linux | johnvansickle.com 或 BtbN static build | ~50MB | LGPL |
**做法：** 在 `installer/payload/ffmpeg/{platform}/ffmpeg` 放靜態檔，解壓後 Go server 用絕對路徑呼叫，不依賴 PATH。原 `stepInstallFfmpeg()` 是 fallback 去系統 PATH 找，新版應改為**一律用內嵌版**確保可重現。
**必須使用 LGPL build 而非 GPL build**——否則整個產品就被 GPL 感染。授權聲明要寫在 About 頁。
### 2.4 預置模型 .nef
**結論：放在 payload 中一起解壓到 `~/.visiona-local/data/nef/`，不塞進 Go binary。**
現狀 nef 總量 **73MB**。理由：
- go:embed 會把 73MB 直接吃進 Go binary，link 時記憶體吃緊、IDE debug 變慢
- 解壓後使用者可手動管理、刪除、增加自訂模型（符合既有 `custom-models` 流程）
- 沿用現有 `stepExtractData` 的做法
## 3. 打包輸出格式
| 平台 | 格式 | 簽章 |
|------|------|------|
| **macOS** | `.app` 內包 Universal Binary（arm64 + amd64 用 `lipo` 合併）→ 再包成 `.dmg` | **強烈建議做 Developer ID + notarization**；否則使用者第一次開啟要右鍵 → 開啟。Wails 支援 `wails build -platform darwin/universal`。Notarization 需要 Apple Developer 帳號（$99/年） |
| **Windows** | `.exe`（NSIS / Inno Setup 都可，推薦 **Inno Setup**，UI 較現代） | **Authenticode 簽章**否則 SmartScreen 會狂擋新下載。EV 憑證 $300-500/年 |
| **Ubuntu** | **`.AppImage`（首選）+ `.deb`（次選）** | 無強制簽章 |
**為何選 AppImage：** 單檔、不需安裝、不需 sudo、攜帶性最高，最符合「像一般 app」的體驗。`.deb` 需要 `apt install`、需要 sudo、只能跑 Debian 系；AppImage 跨所有 glibc ≥2.28 發行版。`.snap` / Flatpak 需要發到 store，發行流程重。
**Universal Binary 是否做？** 建議做。現在 M1/M2 使用者已經是主流，若只發 Intel 版，M 系 Mac 要走 Rosetta，效能不穩（KneronPLUS dylib 如果是 x86_64-only 更糟）。需先確認 KneronPLUS macOS wheel 是否支援 arm64——**這是風險點 R3**。
## 4. 預估安裝檔大小（壓縮後）
| 平台 | Wails shell | Go server | Next.js embed | Python wheels | ffmpeg | NEF 模型 | WinUSB driver | 合計 |
|------|------------|-----------|--------------|---------------|--------|---------|--------------|------|
| macOS (Universal) | ~12MB | ~25MB (x2 架構 ~50MB) | ~5MB | ~40MB | ~35MB | ~73MB | - | **~215MB** |
| Windows | ~10MB | ~20MB | ~5MB | ~40MB | ~45MB | ~73MB | ~1MB | **~195MB** |
| Ubuntu (AppImage) | ~12MB | ~20MB | ~5MB | ~40MB | ~45MB | ~73MB | - | **~195MB** |
以上為**壓縮後**大小。主要體積來自 ffmpeg + Python wheels + 預置模型。若要瘦身：可將 .nef 改為首次啟動時線上下載（-73MB），但違反「完全離線一鍵安裝」原則。建議接受 ~200MB。
## 5. 既有程式碼取用策略
| 目錄／檔案 | 策略 | 說明 |
|-----------|------|------|
| `installer/` | **直接複製改名** | 改為 `visiona-local/`，`app.go` 刪除 relay/dashboard 欄位，其餘流程沿用 |
| `installer/wheels/` | **直接複製** | 三平台 KneronPLUS wheel |
| `installer/drivers/` | **直接複製** | WinUSB driver 檔案 |
| `server/main.go` | **改寫** | 刪除 cluster / tunnel / relay-token / gitea-url 相關參數與初始化 |
| `server/internal/api/` | **改寫** | 刪除 cluster、tunnel handler 與 route |
| `server/internal/camera` `device` `model` `inference` `flash` `config` `deps` | **直接複製** | 核心業務邏輯全保留 |
| `server/internal/cluster` | ❌ **刪除** | |
| `server/internal/tunnel` | ❌ **刪除** | |
| `server/cmd/relay-server` | ❌ **刪除** | |
| `server/tray/` | **直接複製** | 保留 macOS tray + Windows `--gui` web controller |
| `server/scripts/` | **直接複製** | kneron_bridge.py + firmware update |
| `server/data/` | **直接複製** | models.json + 預置 nef |
| `server/web/` + `frontend/` | **改寫** | 移除 relay 模式切換、cluster 管理 UI |
| `docker/` `scripts/deploy-*` | ❌ **刪除** | 不需要部署腳本 |
| `tools/` | 視情況 | 多數是開發腳本 |
## 6. 要砍掉的程式碼清單（具體路徑）
```
server/internal/cluster/ ← 整包刪
server/internal/tunnel/ ← 整包刪
server/cmd/relay-server/ ← 整包刪
server/pkg/hwid/ ← relay token 用的，可刪
docker/ ← 整包刪
scripts/deploy-aws.sh
scripts/deploy-ec2.sh
frontend/app/.../cluster/ ← 前端 cluster 頁面（待 Design Agent 確認）
frontend/app/.../relay/ ← 前端 relay 模式切換 UI
```
`server/main.go` 需移除的 import 與初始化：
- `internal/cluster`, `internal/tunnel`, `pkg/hwid`
- `cfg.RelayURL / RelayToken / GiteaURL` 相關 flag
- `tunnelClient.Start()`、`clusterMgr`、`relayWebURL()` 等
- `config.go` 中的 `RelayURL / RelayToken / TrayMode`（tray 保留）`GUIMode`、`GiteaURL` 砍掉
## 7. 重大技術風險（Top 5）
| # | 風險 | 可能性 | 影響 | 緩解 |
|---|------|-------|------|------|
| **R1** | **KneronPLUS Linux wheel 只有特定 glibc/ABI，無法在所有 Ubuntu 跑** | 高 | 高 | 先實測 Ubuntu 22.04/24.04 x64，若不過則限定支援版本；訴求 AppImage 內帶 libusb |
| **R2** | **Windows WinUSB driver 安裝需要 UAC，使用者拒絕就裝不起來** | 中 | 高 | 首次啟動明確說明；提供「手動安裝 driver」的後援流程 |
| **R3** | **KneronPLUS macOS wheel 可能只有 x86_64**（M 系 Mac 要走 Rosetta，dylib 會抗議） | 中 | 高 | 第二輪前必須驗證：`lipo -info` 檢查 .dylib 架構；若只有 x86_64，Universal Binary 就沒意義 |
| **R4** | **離線 wheel 安裝在沒有 pip 的 Python 環境會炸**（macOS 系統 Python 有 pip，但 Ubuntu 沒有 `python3-venv` 是常態） | 中 | 中 | 已有 `installPython3Venv()` fallback，但需要 sudo；考慮改為引導使用者手動裝 |
| **R5** | **預置 .nef 模型授權可能限制重新發布** | 低 | 中 | 請 PM 確認 Kneron 預置模型的 re-distribution license |
## 8. 需要 PM / Design 回答的問題
**給 PM：**
1. 目標使用者是「開發者 / ML 工程師」還是「一般使用者」？影響 UI 的技術密度（要不要顯示 log、要不要 advanced mode）
2. 是否必須支援**完全離線**一鍵安裝？還是可以在首次啟動時連網下載 wheels？影響 R4 緩解方案
3. 預置模型清單要保留哪些？現狀 KL520/KL720 各有 5-6 個，73MB；可否精簡到 30MB？
4. 是否支援**多裝置連接**（一台電腦插兩顆 Kneron dongle）？影響裝置列表 UI
5. 要不要保留**韌體更新**功能（`update_kl720_firmware.py`）？
**給 Design：**
1. Wails 殼的 UI 要走「安裝精靈風格」還是「Dashboard 風格」？原 installer 是精靈式，但 local 版應該常駐後是 Dashboard
2. 需要 Dark Mode 嗎？
3. 首次安裝流程的進度條樣式（現有是 0-100% 橫條，可否保留？）
4. 系統列（Tray）菜單要放哪些項目？至少：開啟儀表板 / 啟動/停止 / 結束
## 9. 需要使用者確認的問題
1. **Apple 簽章與 notarization**：是否有 Apple Developer 帳號？沒有就只能 ad-hoc sign（使用者第一次要右鍵打開）
2. **Windows Authenticode**：是否願意採購 EV 簽章憑證（~$300/年）？沒有就會被 SmartScreen 警告，但仍可使用
3. **最低 OS 版本**：建議 macOS 12+、Windows 10 (1809)+、Ubuntu 22.04+，可接受？
4. **ARM Linux（Raspberry Pi 之類）**：暫不支援？（KneronPLUS 的 arm64 Linux 支援度不明）
5. **Bundle ID**：`com.innovedus.visiona-local` 可以用嗎？（progress.md 已記錄但標記待確認）
6. **離線 vs 線上安裝**：追求完全離線（~200MB 安裝檔）還是接受首次連網（~120MB 安裝檔）？
7. **預置模型**：是否需要精簡清單？
8. **應用程式名稱顯示**：visionA-local 還是 VisionA Local？品牌字風格？
---
**下一步：** 等待 PM / Design / 使用者對上述問題的回覆。回覆後進入第二輪——產出完整 Design Doc 與 TDD，拆分為模組化檔案（`04-architecture/design-doc.md` 索引 + `api/`、`database.md`、`infra.md` 等子檔）。

159
local-tool/.autoflow/04-architecture/architect-cross-review.md Normal file
View File

@ -0,0 +1,159 @@
# Architect 交叉審閱報告
> 審閱者：Architect Agent
> 日期：2026-04-11
> 審閱對象：PM PRD v1.1、Design Spec v2（第三輪修訂）
> 結論：**整體對齊、無阻斷性衝突**；有 7 項需修正 / 澄清，2 項需使用者或三方裁決。
---
## ✅ 對齊的項目
以下是 PM / Design 的產出與 Architect 架構完全一致、無需調整的部分：
1. **核心功能範圍**：PRD 4.1–4.4 砍除 cluster / relay / tunnel / flash / update / tray 的清單與 Architect 的 `removed-code.md`、`api-endpoints.md` **逐項對齊**，前端 API client 清理清單一致。
2. **生命週期模型**：Design `04-first-run` + Q7 傳統式（關閉視窗 = 結束）與 `tray-and-lifecycle.md` 的 cleanupAndExit 流程一致。
3. **資料目錄路徑**：Design `06-cross-platform §6.7`、PRD `6.6` 的 macOS / Windows / Linux 路徑與 Architect `architecture-overview §4.2`、`tray-and-lifecycle §6` 一致（注意命名小寫問題見下 P-1）。
4. **Settings 4 分頁**（一般 / 硬體 / 模型 / 進階）：API 層已保留 `/api/system/restart`、`/api/devices`、`/api/models`、`/api/system/deps`、`/ws/server-logs`，**完整支援** Settings 各分頁需要的資料來源。
5. **Workspace 升一級**：前端僅需新增 `frontend/src/app/workspace/page.tsx` 作為 top-level 入口，API 層無需任何新增（已沿用 `/api/devices` + `/api/camera` + `/api/media/*`）。
6. **Mock 模式視覺標記**：`deviceMgr.mockMode` 旗標已於原專案存在，Header badge / Sidebar 底部狀態列只需讀取 `/api/system/info` 或新增一個 `mode` 欄位即可，工作量極小。
7. **First-Run 三步流程**：Step 3a 的「自動掃描 USB 10 秒」可直接用 `POST /api/devices/scan` + 前端計時器實作，無需新 API。
---
## ⚠️ 發現的問題
### 對 PM 的問題
- **P-1 🟡 [命名不一致] 資料目錄名稱大小寫**
PRD `nonfunctional §6.6` 與 `user-flows §5.3.2` 使用 `visionA-local`（駝峰），但 Architect `architecture-overview §4.2` 與 `tray-and-lifecycle §6` 使用 `visiona-local`（全小寫）。
**建議**：統一為**全小寫 `visiona-local`**。Linux 路徑慣例為小寫，macOS Bundle ID `com.innovedus.visiona-local` 也是小寫，Windows 大小寫不敏感但統一較好維護。Design `06-cross-platform §6.7` 也混用兩種，需一併修正。
- **P-2 🟡 [時間指標互相矛盾] 「安裝時間 ≤ 3 分鐘」vs「首次推論 ≤ 15 秒」**
PRD `6.1` 寫「安裝時間 ≤ 3 分鐘」但**首次推論時間 ≤ 15 秒**（app 啟動 → Mock 第一幀）。這兩個指標的起點不同：
- 「安裝時間」= 雙擊安裝檔 → Dashboard 顯示
- 「首次推論時間」= app 圖示點擊 → 第一幀
但 PRD 的 TL;DR 和 feature-inventory 都寫「一鍵 3 分鐘安裝好」，會讓讀者誤以為整個 First-Run 包含解壓 wheels + 建 venv + 安裝 KneronPLUS driver 在 3 分鐘內跑完。
**Architect 實測估算**：解壓 python-build-standalone (~90MB) + 建 venv + pip install --no-index (numpy/opencv/KneronPLUS) 在 SSD + 中階 CPU 上約 **90–180 秒**，加上 Wails 冷啟 + WebView 3–5 秒，首次安裝達標但非常緊。Windows 還要 UAC 裝 WinUSB driver 再 +20–40 秒。
**建議**：
1. 把「首次安裝時間」從 ≤ 3 分鐘放寬到**目標 ≤ 3 分鐘、上限 ≤ 5 分鐘**（PRD 目前已有上限 5 分鐘，但 TL;DR 沒提）
2. 在 TL;DR、feature-inventory 補一句「上限 5 分鐘」以免誤導
3. Windows 特別註記「若首次要裝 WinUSB driver，額外 +30 秒」
- **P-3 🟡 [Mock idle RAM 目標過嚴] ≤ 400 MB / 上限 500 MB**
PRD `6.1`：「Mock 模式 idle RAM ≤ 400 MB（目標）/ 500 MB（上限）」，備註「不含 Python sidecar」。
**Architect 實測關切**：Wails (Go + WebView) 常駐 ~150–200 MB，Go server (Gin + embedded Next.js) ~40–60 MB，Next.js 前端在 WebView 執行 ~100–150 MB，**合計約 290–410 MB**。若 Mock 模式啟動 Python sidecar（即便只做 mock），還會再 +60–80 MB。
**建議**：
1. Mock 模式**不要 spawn Python sidecar**（已於 `architecture-overview §6` 記錄），PRD 應明示「Mock 模式下無 Python 程序」
2. 上限放寬到 **600 MB** 或把 Python sidecar 計入；若堅持 500 MB 上限，需要在測試早期驗證並可能砍掉某些 Next.js 功能
3. 明確測量規則：是 RSS 還是 Working Set、macOS Activity Monitor 的「記憶體」欄位（含 compressed）還是 private bytes
- **P-4 🟢 [技術假設需註記] yt-dlp 授權聲明未在 PRD 露出**
PRD `feature-inventory §4.5` 只提「保留 yt-dlp（Q10）」，但沒提 About / Settings 會露出第三方授權聲明。Architect 在 `dependency-bundling §4.4` 註記 yt-dlp 是 Unlicense（public domain），無授權問題，但 `ffmpeg` LGPL **必須**在 About 頁宣告。
**建議**：PRD `feature-inventory` 新增一行「About 頁顯示第三方授權（ffmpeg LGPL、KneronPLUS、yt-dlp Unlicense、python-build-standalone）」，與 Architect R10 呼應。
- **P-5 🟢 [發佈通路假設] 「內部 Gitea Releases / GitHub Releases」尚未確認**
PRD `release-strategy §7.1` 把這當成既定通路，Architect `build-pipeline.md` 也假設 CI 有三平台 runner。但 progress.md 的「未解決問題」明確列出這兩項**尚未確認**。這不是 Architect 的鍋，但 PM 應把這兩項列入 launch-checklist 的「發佈前必須確認」項，與 R9 (Kneron 授權) 一起追蹤。
**建議**：PRD `release-strategy` 或 `risks.md` 新增 R11「發佈通路基礎設施未確認」、R12「CI runner 三平台是否齊備」，與 R9 同等優先級處理。
### 對 Design 的問題
- **D-1 🔴 [嚴重規格衝突] MJPEG 延遲目標 ≤ 100 ms vs ≤ 200 ms**
PRD `6.1`「攝影機串流延遲（capture → UI 顯示）≤ 100 ms，上限 ≤ 200 ms」
Design `03-wireframes §3.4` Workspace panel 寫「Latency: 42ms」作為範例
Architect `TDD §5`「MJPEG 串流延遲 < 200 ms（同機 localhost）」
**三處數字不一致**。實際上：MJPEG over HTTP 在 localhost + webcam 直取（經 ffmpeg pipeline）的端到端延遲（capture → decode → draw）**典型為 80–150 ms**，若加上推論 overlay 再 +20–50 ms。Architect 的 ≤ 200 ms 是保守值，PRD 的目標 ≤ 100 ms **風險高**。
**建議**：
1. PRD 改為「攝影機串流延遲 ≤ 150 ms（目標）/ ≤ 250 ms（上限）」
2. Design wireframe 的 42 ms 範例值應改為 100–120 ms 比較誠實
3. 如果 PM / Design 堅持 100 ms，需要 Architect 評估用 WebCodecs API 或 H.264 + MediaSource 取代 MJPEG，**但這會是大改**
- **D-2 🟡 [Wails API 能力確認] OS 原生通知**
Design `06-cross-platform §6.4` 把 OS 原生通知列為「裝置連接成功、裝置斷線、Server 崩潰」三個情境，並註記「需 Architect 確認實作方案」。
**Architect 確認**：Wails v2 **沒有內建跨平台 notification API**。三個可行方案：
1. **Shell out**（最簡單）：macOS `osascript -e 'display notification'`、Linux `notify-send`、Windows PowerShell `New-BurntToastNotification` — 有 100–300 ms 延遲 + 每次 spawn 程序
2. **第三方 Go 套件**：`github.com/gen2brain/beeep`（跨平台）或 `github.com/go-toast/toast`（Windows 專用）— 更原生但要多帶依賴
3. **純 App 內 toast**（退路）：直接用前端 toast 取代 OS 通知
**建議**：第一版採用**方案 3（App 內 toast）+ 關鍵通知（Server 崩潰）用方案 1 shell out**。Design 規格需修改：裝置連接 / 斷線改成**僅 App 內 toast，不發 OS 通知**（因為使用者此時視窗已在前景），只有 Server 崩潰才發 OS 通知。這可以省掉引入 beeep 套件的風險。
- **D-3 🟡 [快捷鍵 Wails API 確認] ⌘1–4 切主區 + ⌘Shift+W**
Design `06-cross-platform §6.2` 列出完整快捷鍵集，並註記「仍需 Architect 確認 Wails menu API 能吃這些組合」。
**Architect 確認**：
- ✅ Wails v2 的 `menu.AppMenu` 支援 `keys.CmdOrCtrl(keys.Key("1"))` 等常用組合
- ✅ ⌘ W、⌘ Q、⌘ , 是 Wails 預設支援
- ⚠️ **⌘ R 可能與 WebView 的「重新載入頁面」衝突**：Wails WebView 在開發模式預設把 ⌘ R 當成 reload。生產環境需要明確 disable WebView 的 reload shortcut，或改用 ⌘ Shift+R。
- ⚠️ **⌘ Shift+W 前往 Workspace** 與 macOS 內建「關閉所有視窗」快捷鍵衝突，建議改為 ⌘ Shift+K 或 ⌘ 4（已有 ⌘ 4 切換到 Workspace 所以也不需要額外快捷鍵）
**建議**：Design 修改兩處：⌘ R → ⌘ Shift+R（重新整理裝置）、取消 ⌘ Shift+W（因為 ⌘ 4 已有相同功能）
- **D-4 🟡 [Wails 拖放 API] 拖放 .nef / 圖片 / 影片到視窗**
Design `06-cross-platform §6.3` 與 wireframe `3.2 Models` 提到「拖放區域覆蓋整個 Models 頁面」。
**Architect 確認**：Wails v2 支援 `OnFileDrop` callback，能接收 drop 到視窗任意處的檔案路徑陣列。**需要在 `wails.json` 啟用 `DragAndDrop.EnableFileDrop: true`**。前端透過 `runtime.OnFileDrop` 訂閱事件。
**可行但有坑**：
- Wails 的 file drop 回傳的是**絕對路徑字串**，不是 HTML5 File object。前端無法直接用 FormData 上傳，必須改走「把路徑丟給 Wails → Wails 讀檔 → 呼叫 Go server API」這條路
- 這與現有 `frontend/src/lib/api/models.ts`（推測走 `multipart/form-data`）不相容，需要新增一個「由 Wails 代理上傳」的路徑
**建議**：Design 保留拖放需求不變；Architect 需要在 M1 或 M2 新增「Wails 檔案拖放代理層」任務，並在 TDD 新增一節說明。
- **D-5 🟡 [深色模式同步機制未定] Wails → 前端事件**
Design `06-cross-platform §6.8`：「Wails 需要在系統主題變更時 emit event 給前端重新計算」。
**Architect 補充**：Wails v2 `runtime.WindowIsDarkMode()` 可讀取當前主題，但**主動監聽系統主題切換事件**需要：
- macOS：監聽 `NSDistributedNotificationCenter` 的 `AppleInterfaceThemeChangedNotification`
- Windows：監聽 registry `HKCU\SOFTWARE\Microsoft\Windows\CurrentVersion\Themes\Personalize\AppsUseLightTheme` 變化
- Linux：`dbus-monitor` gsettings schema 變化
**Wails v2 目前沒有統一封裝**。最簡方案：前端 CSS 用 `@media (prefers-color-scheme: dark)`，WebView 會**自動**跟隨系統切換，**無需 Wails 中介**。這已經足夠滿足需求。
**建議**：Design 的「Wails 需在系統主題變更時 emit event」可以**刪除**；改寫成「前端 CSS 使用 `prefers-color-scheme` media query，由 WebView 自動處理」。這是一個**降低複雜度**的勝利。
- **D-6 🟢 [無障礙層級與 PRD 不一致]**
Design `spec/09-accessibility.md` 目標為 WCAG 2.2 AA，但 PRD `6.8.3`「無障礙」寫「繼承原專案的 shadcn/Radix 元件無障礙屬性，不做額外無障礙驗證（內部工具，scope 外）」。
**這兩個是矛盾的**：Design 承諾 AA，PRD 明說 scope 外。Architect 立場：實作層面沿用 shadcn/Radix 就能拿到 80% AA，剩下 20% 需要人工驗證，**我建議對齊 PRD 的「不做額外驗證」**，Design 的 09-accessibility.md 改寫為「以 shadcn/Radix 預設為目標，不額外驗證」。
**建議**：由 PM / Design 協調這個衝突。三方需達成共識。
- **D-7 🟢 [i18n hot-reload 可行性]**
Design `10-i18n §10.7`：「切換後即時生效（不需重啟）」。
**Architect 確認**：前端 i18next 的 `i18n.changeLanguage()` 確實能 hot-reload 所有 `useTranslation()` hook 用到的字串。但 **macOS 原生 menu bar** 是在 Wails 啟動時由 Go 端建立的，切換語言後需要呼叫 `runtime.MenuSetApplicationMenu()` 重建 menu（Wails v2 支援），可行但要記得做。
**建議**：Design `10-i18n §10.8` 已正確描述需要「重建 menu」，無需修改；但 Architect `i18n.md §6` 的 M2「動態語系切換：第二版再做」與 Design 的「即時生效」矛盾，**Architect 這邊要改**為 M2 就支援即時切換（工作量增加但不大）。
---
## 📊 關鍵交互可行性矩陣
| 交互 | Design 期望 | Architect 實作成本 | 可行性 |
|------|-----------|------------------|-------|
| **First-Run 三步流程（歡迎 / 模式 / 偵測）** | 每步可略過、進度條、自動掃描 10 秒 | 低（已有 onboarding-dialog 元件沿用） | ✅ 高 |
| **Dashboard Quick Start 3 步卡（打勾狀態）** | 根據 devices/models 狀態自動打勾 | 低（前端 state 計算） | ✅ 高 |
| **Devices 拖放 .nef 上傳** | 拖放整頁覆蓋 | 中（需新增 Wails 檔案拖放代理層） | ✅ 中 |
| **Workspace 即時推論 overlay（MJPEG）** | 延遲 ≤ 100 ms（Design）/ ≤ 200 ms（Architect） | 中（MJPEG 極限 ~80-150 ms） | ⚠️ **需協調** |
| **OS 原生通知（裝置連 / 斷 / 崩潰）** | 三情境都發 OS 通知 | 中（需 shell out 或引入 beeep） | ⚠️ **降級建議**：只 Server 崩潰發 OS 通知，其他改用 App 內 toast |
| **深色模式自動跟隨系統** | Wails emit event | 低（CSS `prefers-color-scheme` 就夠） | ✅ 高（實作可簡化） |
| **⌘1–4 切主區 + ⌘ ,、⌘ W、⌘ Q** | Wails menu API | 低 | ✅ 高 |
| **⌘ R 重新整理裝置** | Wails menu API | 中（與 WebView reload 衝突） | ⚠️ **改用 ⌘ Shift+R** |
| **i18n 即時切換（含原生 menu）** | 不重啟 | 中（Wails 支援 dynamic menu rebuild） | ✅ 中 |
| **Settings 4 分頁 / Workspace 升一級** | 沿用 shadcn tabs + 新增 sidebar 項 | 低 | ✅ 高 |
| **Mock 模式永久 badge + 切換確認對話框** | Header badge + Dialog | 低 | ✅ 高 |
| **macOS 原生 menu bar（visionA-local / File / Edit / View / Devices / Help）** | 完整 menu bar | 中（Wails 支援但要逐項定義） | ✅ 中 |
---
## ❓ 需要使用者或三方討論的問題
1. **MJPEG 延遲目標（D-1 + P-2 相關）**
PRD ≤ 100 ms 的目標與實作極限衝突。三方需決定：
- **選項 A**：接受放寬到 ≤ 150 / 250 ms（Architect 建議）
- **選項 B**：堅持 100 ms → 改用 WebCodecs / MediaSource + H.264，**工作量至少 +2 週**
- **選項 C**：只對「感知延遲」保證（使用者主觀感覺不卡），拿掉量化指標
2. **無障礙 WCAG 2.2 AA 要不要做（D-6）**
Design 承諾 AA、PRD 明說 scope 外。需 PM + Design 對齊到同一立場並更新文件。
---
## 結論
PM PRD v1.1 與 Design Spec 第三輪修訂版整體對齊 Architect 的架構決策，**無阻斷性衝突**。主要問題集中在：
1. **數字級對齊問題**（P-2 安裝時間上限、P-3 Mock idle RAM、D-1 MJPEG 延遲）— 三份文件的量化目標需要統一到實作可達成的範圍
2. **Wails API 能力細節**（D-2 通知、D-3 快捷鍵、D-4 拖放、D-5 深色模式）— Architect 已給出具體方案與降級選項，Design 需配合小修
3. **小範圍命名 / 文件一致性**（P-1 `visionA-local` vs `visiona-local`、P-4 yt-dlp 授權、P-5 發佈通路未確認）
**沒有發現 PM 或 Design 偷偷引入需要大改架構的需求**，也沒有架構層面的隱藏技術陷阱。Architect 對 PM 的功能需求與非功能需求（除 P-2/P-3/D-1 的數字需協調外）均能提供對應技術方案。
建議三方依本報告一起開一次短會對齊數字指標（P-2、P-3、D-1、D-6），Design 依 D-2~D-5 做小修訂即可進入使用者最終確認階段。

379
local-tool/.autoflow/04-architecture/architecture-overview.md Normal file
View File

@ -0,0 +1,379 @@
# Architecture Overview — visionA-local
> 架構總覽、系統分層、程序模型、資料流、目錄結構
---
## 1. 系統分層
```
┌─────────────────────────────────────────────────────────┐
│ Layer 1: 使用者互動層 │
│ - Wails WebView（嵌入 Next.js 前端） │
│ - 原生 file picker / notification │
├─────────────────────────────────────────────────────────┤
│ Layer 2: 應用控制層（visiona-local Wails app binary） │
│ - 生命週期管理（啟動 / 停止 / single-instance） │
│ - Server 子行程管理（spawn / log / kill） │
│ - 首次安裝精靈（解壓 payload、建 venv、Python runtime） │
├─────────────────────────────────────────────────────────┤
│ Layer 3: 業務服務層（visiona-local-server Go binary） │
│ - HTTP REST API（Gin） │
│ - WebSocket Hub │
│ - Device Manager / Camera Manager / Inference Svc │
│ - Model Repository │
│ - Dependency checker │
├─────────────────────────────────────────────────────────┤
│ Layer 4: 硬體橋接層 │
│ - Python sidecar（kneron_bridge.py） │
│ - KneronPLUS SDK（pyusb + libusb + .dylib/.so/.dll） │
│ - ffmpeg（camera pipeline / video transcode） │
│ - yt-dlp（media/url） │
└─────────────────────────────────────────────────────────┘
```
## 2. 程序模型
三個獨立程序，透過 **stdin/stdout JSON-RPC** 與 **localhost HTTP** 通訊：
```
Process 1: visiona-local (Wails app binary, parent；display name 仍為 visionA-local)
│
├─ spawns ──→ Process 2: visiona-local-server (Go binary)
│ │
│ ├─ spawns ──→ Process 3: python3 kneron_bridge.py
│ │ (stdin/stdout JSON-RPC)
│ │
│ └─ spawns (on demand) ──→ ffmpeg / yt-dlp
│
└─ WebView loads ──→ http://127.0.0.1:3721/
```
### 2.1 程序間通訊
| 連結 | 協定 | 用途 |
|------|------|------|
| Wails app ↔ Go server | HTTP（localhost:3721）| 啟動後透過 `/api/system/health` 確認 server 活著；WebView 透過 `file://` → `http://127.0.0.1:3721/` 載入 Next.js |
| Wails app ↔ Go server（控制） | OS signal / exec | 結束時送 SIGTERM；重啟時 `os/exec` spawn 新程序 |
| Go server ↔ Python sidecar | stdin/stdout JSON-RPC | 沿用 `edge-ai-platform` 現有機制 |
| Go server ↔ ffmpeg | stdin/stdout pipe | MJPEG 串流 |
| Go server ↔ yt-dlp | subprocess + stdout | URL 下載 |
| Wails WebView ↔ Go server | HTTP + WebSocket | 前端 fetch / WS 訂閱 |
### 2.2 為何三層而不是 single binary
原 `edge-ai-platform` 已驗證三層模型可行。採用三層的理由：
1. **崩潰隔離**：UI 殼（Wails）崩潰不應殺掉 server，server 崩潰不應殺掉 Python inference loop
2. **Python 必須獨立 interpreter**：KneronPLUS SDK 是 C extension wheel，無法塞進 Go binary
3. **重啟成本低**：Go server 重啟只需 ~1 秒，不影響 Wails app 存活
4. **沿用既有程式碼**：`installer/app.go`（894 行）與 `server/main.go`（305 行）已驗證此模型
5. **可獨立 debug**：開發時可以 `go run main.go` 跑 server，Wails app 不用重編
### 2.3 視窗關閉行為（使用者決策 Q7 = B）
**關閉主視窗 = 結束整個程式**（Wails app → 主動 SIGTERM Go server → Python sidecar 跟著被 reaped）。
這與 Docker Desktop 的「關視窗只是收進 tray」行為**不同**——我們刻意選擇傳統桌面 app 模型。此外使用者決策 Q-A=A3 已砍掉 tray，沒有 tray icon 可以收。
## 3. 資料流（三個代表性情境）
### 3.1 首次啟動
```
使用者雙擊 .app
↓
Wails app 啟動 → 檢查資料目錄下的 .installed 標記
（macOS: ~/Library/Application Support/visiona-local/；Windows: %APPDATA%\visiona-local\；Linux: ~/.local/share/visiona-local/）
↓
（未安裝）→ 進入安裝精靈
├─ 解壓 embed FS → <資料目錄>/{bin, scripts, data}
├─ 偵測 Python runtime（策略 A → B fallback，見 dependency-bundling.md）
├─ 建 venv → pip install --no-index --find-links wheels/
├─ 安裝 KneronPLUS wheel
├─ （Windows）安裝 WinUSB driver → UAC 提示
├─ （Linux）寫入 /etc/udev/rules.d/99-kneron.rules → pkexec 提權
├─ 寫 .installed 標記
└─ 進入主流程
↓
主流程：spawn Go server → 等 /api/system/health 200 → WebView loads localhost:3721
↓
Dashboard 顯示
```
### 3.2 連上 USB 裝置
```
使用者插入 Kneron USB
↓
前端按「掃描」→ POST /api/devices/scan
↓
Go server → spawn python3 kneron_bridge.py scan
↓
Python → kp.scan_devices() → 回傳裝置列表
↓
Go server → WebSocket push /ws/devices/events → 前端更新卡片
↓
使用者按「connect」→ POST /api/devices/:id/connect
↓
Go server → 維持一個持續的 Python sidecar 程序連線
```
### 3.3 關閉應用
```
使用者按視窗關閉 / ⌘Q / Cmd+Q
↓
Wails app → 攔截 close event → 呼叫 cleanupAndExit()
↓
├─ 送 SIGTERM 給 Go server PID
├─ 等 3 秒 graceful shutdown
│ ├─ Go server → shutdownFn() → inferenceSvc.StopAll() / httpServer.Shutdown()
│ └─ Go server → 送 SIGTERM 給 python sidecar PID
├─ 3 秒 timeout → SIGKILL
└─ Wails app exit
```
## 4. 目錄結構（建議）
### 4.1 開發時（source tree）
```
/Users/jimchen/visionA/local-tool/
├── .autoflow/ ← Autoflow 文件（PRD、設計、架構...）
├── .claude/
├── Makefile
├── README.md
├── go.work ← 統一 visiona-local + server 的 go modules
├── visiona-local/ ← Wails app（前身 installer/）
│ ├── main.go
│ ├── app.go
│ ├── embed.go
│ ├── platform_darwin.go
│ ├── platform_linux.go
│ ├── platform_windows.go
│ ├── wails.json
│ ├── frontend/ ← Wails 內部 minimal UI（非業務前端）
│ ├── payload/ ← build 時 stage 的資料
│ │ ├── bin/
│ │ │ └── visiona-local-server
│ │ ├── data/
│ │ │ ├── models.json
│ │ │ └── nef/
│ │ ├── scripts/
│ │ │ ├── kneron_bridge.py
│ │ │ ├── requirements.txt
│ │ │ ├── wheels/ ← python-build-standalone + Kneron wheels
│ │ │ └── ffmpeg
│ │ └── python/ ← 內嵌的 python-build-standalone runtime
│ │ ├── bin/python3
│ │ └── lib/...
│ ├── drivers/ ← Windows WinUSB driver 檔
│ │ └── amd64/
│ └── build/ ← wails build 產物
├── server/ ← Go 業務後端
│ ├── main.go
│ ├── go.mod
│ ├── internal/
│ │ ├── api/
│ │ │ ├── handlers/
│ │ │ ├── ws/
│ │ │ ├── middleware.go
│ │ │ └── router.go
│ │ ├── camera/
│ │ ├── config/
│ │ │ └── config.go
│ │ ├── deps/
│ │ ├── device/
│ │ ├── driver/
│ │ ├── inference/
│ │ └── model/
│ ├── pkg/
│ │ └── logger/
│ ├── data/
│ │ ├── models.json
│ │ └── nef/
│ ├── scripts/
│ │ ├── kneron_bridge.py
│ │ └── requirements.txt
│ └── web/ ← go:embed 前端產物
│ └── out/
├── frontend/ ← Next.js 業務前端
│ ├── src/app/
│ │ ├── page.tsx ← Dashboard
│ │ ├── devices/
│ │ ├── models/
│ │ ├── workspace/
│ │ └── settings/
│ ├── package.json
│ └── next.config.ts
└── dist/ ← 最終發行物
├── visiona-local-v1.0.0-macos-x64.dmg
├── visiona-local-v1.0.0-windows-x64.exe
└── visiona-local-v1.0.0-linux-x64.AppImage
```
### 4.2 安裝後（使用者機器）
**macOS**：
```
/Applications/visiona-local.app/ ← Wails binary + 內嵌 payload（檔名全小寫，對齊 Bundle ID；Info.plist 的 display name 仍為 visionA-local）
~/Library/Application Support/visiona-local/
├── bin/
│ └── visiona-local-server ← 解壓出的 Go binary
├── python/ ← 解壓出的 python-build-standalone
├── venv/ ← 建立的 venv（pip install 進去）
├── data/
│ ├── models.json
│ ├── nef/
│ └── custom-models/ ← 使用者上傳的 .nef
├── scripts/
├── logs/
│ ├── visiona-local.log
│ └── server.log
└── .installed ← 版本標記
```
**Windows**：
```
C:\Program Files\visiona-local\ ← Wails binary + payload（Inno Setup 安裝，檔名全小寫）
%APPDATA%\visiona-local\
├── bin\visiona-local-server.exe
├── python\
├── venv\
├── data\
├── scripts\
├── logs\
└── .installed
```
**Ubuntu**（AppImage）：
```
~/Applications/visiona-local-v1.0.0-x86_64.AppImage ← 使用者自己放的 AppImage（檔名全小寫）
~/.local/share/visiona-local/
├── bin/
├── python/
├── venv/
├── data/
├── scripts/
├── logs/
└── .installed
```
## 5. 核心模組責任表
| 模組 | 位置 | 責任 |
|------|------|------|
| **Wails app** | `visiona-local/` | 生命週期、安裝精靈、WebView |
| **HTTP API** | `server/internal/api/` | REST + WebSocket 路由與 handlers |
| **Device Manager** | `server/internal/device/` | USB 裝置列舉 / 連線 / 狀態 |
| **Camera Manager** | `server/internal/camera/` | webcam 列舉 / MJPEG 串流 / 影片上傳 |
| **Model Repository** | `server/internal/model/` | 預置模型 + 使用者自訂 .nef |
| **Inference Service** | `server/internal/inference/` | 推論 pipeline（對接 Python sidecar） |
| **Python Bridge** | `server/scripts/kneron_bridge.py` | 封裝 KneronPLUS SDK |
| **Logger** | `server/pkg/logger/` | 統一 log + WebSocket broadcaster |
| **Config** | `server/internal/config/` | CLI flags / env vars |
| **Deps Checker** | `server/internal/deps/` | 啟動時檢查 python / ffmpeg 可用性 |
## 6. 非功能性需求對應
| NFR | 對應機制 |
|-----|---------|
| 完全離線 | 依賴全部內嵌（Python runtime、wheels、ffmpeg、yt-dlp、模型）。詳見 `dependency-bundling.md` |
| 啟動 < 5 秒 | Go server 冷啟約 1s；Wails WebView 首次載入 Next.js ~2s；總計 3-4s |
| idle CPU < 5% | **Mock 模式完全不 spawn Python sidecar**（重要：不是「閒置時不跑」，而是「整個 Mock session 期間都不會有 python 程序」，詳見第 7 節）；`inferenceSvc` 只有在 active session 才啟動 worker |
| 單機多裝置 | `device.Registry` 支援多個並存（原專案已有） |
| 跨平台一致 UI | Next.js 前端跨平台一致；三平台皆使用同一份 WebView 內容 |
| 安裝檔 < 500MB | 實測預估 ~300-350MB（見 packaging.md 第 4 節） |
---
## 7. Mock 模式的程序模型（重要）
**Mock 模式（`--mock` 或 Settings 切換）下，Go server 完全不 spawn Python sidecar。** 這是為了守住 Mock idle RAM 上限（≤ 600MB，第四輪決策 R4-4）並避免無謂的 KneronPLUS 載入失敗噪音。
實作要點：
- `device.Manager` 在 `mockMode=true` 時跳過 `kneron_bridge.py` spawn，改由內建假資料 provider 回應 `/api/devices/scan`
- `inference.Service` 在 Mock session 啟動時檢查 `mockMode` 旗標，走 in-process 假推論 pipeline（隨機 bounding box、固定分類結果），不經過 Python
- Camera pipeline（webcam + ffmpeg）仍啟動，因為 ffmpeg 不依賴 Kneron
- Mock ↔ Real 切換時（見第 8 節）才會在必要時 spawn/kill Python sidecar
## 8. Mock ↔ Real 模式切換
使用者可在 Settings > 一般 切換「執行模式」，**不需要重啟整個 app**，只需要切 inference backend：
1. 前端呼叫 `POST /api/system/mode` body `{"mode":"mock"|"real"}`（見 `api-endpoints.md`）
2. Go server `device.Manager.SetMode()`：
- real → mock：kill 既有 Python sidecar + 清空 device registry + 載入 mock devices
- mock → real：spawn Python sidecar + 呼叫 scan → 回填 device registry
3. 所有進行中的 inference session 強制終止，前端收 WebSocket broadcast 後提示「模式已切換，請重新啟動推論」
4. 這個切換僅影響 Go server 的 inference backend，Wails app / server HTTP listener / WebView 都不重啟
## 9. Wails 檔案拖放代理層
Wails v2 的 `OnFileDrop` 回傳**絕對路徑字串陣列**（不是 HTML5 File 物件），與現有 `frontend/src/lib/api/models.ts` 走 `multipart/form-data` 上傳不相容。新增一條「Wails 代理上傳」路徑：
```
使用者拖 .nef 到 Models 頁
↓
Wails WebView 捕獲 drop event → runtime.OnFileDrop callback
↓
Wails app（Go）取得絕對路徑陣列 → 透過 Wails Bind API emit event 給前端
↓
前端收到路徑 → 呼叫 window.runtime.UploadFileByPath(path)
↓
Wails app（Go）讀取檔案 → 包成 multipart → POST http://127.0.0.1:{port}/api/models/upload
↓
Go server 接收（走原本的 upload handler，無需修改）
```
實作位置：
- `visiona-local/file_drop.go`（新寫）
- 前端 `frontend/src/lib/wails/file-drop.ts`（新寫）
- `wails.json` 需設 `"dragAndDrop": {"enableFileDrop": true}`
**這條代理層同時適用於 Models 上傳、Workspace 的影片 / 圖片拖入、批次圖片匯入**。
M1 不做（只做點選上傳），**M2 納入**（前端清理完成後）。
## 10. OS 通知實作
對應第四輪決策 R4-8：
| 情境 | 機制 | 實作 |
|------|------|------|
| 裝置連接 / 斷線 | **App 內 toast**（前端處理） | shadcn `toaster` + WebSocket `/ws/devices/events` 觸發 |
| Server 崩潰 | **原生 OS 通知**（Wails app 處理） | shell out 方式，無需引入第三方 Go 套件 |
**Server 崩潰原生通知實作（shell out）：**
```go
// visiona-local/native_notify.go
func ShowNativeNotification(title, body string) {
switch runtime.GOOS {
case "darwin":
script := fmt.Sprintf(`display notification %q with title %q`, body, title)
exec.Command("osascript", "-e", script).Run()
case "linux":
exec.Command("notify-send", title, body).Run()
case "windows":
// 用 PowerShell + BurntToast 或直接 New-BurntToastNotification
ps := fmt.Sprintf(`New-BurntToastNotification -Text "%s","%s"`, title, body)
exec.Command("powershell", "-NoProfile", "-Command", ps).Run()
}
}
```
**降級策略**：若 shell out 失敗（例如 Linux 無 `notify-send`、Windows 無 BurntToast 模組），退回純前端 toast + logging，不炸 app。
## 11. 舊資料目錄遷移
為了兼容早期開發階段可能殘留的舊命名（例如隱藏資料夾 `~/.visiona-local/` 或舊大寫 `~/Library/Application Support/visionA-local/`），Wails app 啟動時執行一次遷移檢查：
1. 掃描舊路徑：`~/.visiona-local/`、`~/Library/Application Support/visionA-local/`、`%APPDATA%\visionA-local\`、`~/.local/share/visionA-local/`
2. 若存在且新路徑（`visiona-local` 全小寫）不存在 → `os.Rename` 整個目錄
3. 在新路徑寫一個 `.migrated-from` breadcrumb 檔記錄舊路徑與時間戳
4. 若新路徑已存在 → 不動舊的，log 一行 warning 提示使用者手動清理
5. 遷移失敗不擋啟動，只記 log
實作位置：`visiona-local/data_migration.go`（新寫，M2）。

413
local-tool/.autoflow/04-architecture/build-pipeline.md Normal file
View File

@ -0,0 +1,413 @@
# Build Pipeline — visionA-local
> Makefile、build 腳本、CI（選配）、跨平台建置策略。**無簽章。**
---
## 1. Makefile 骨架
```makefile
# visionA-local - Makefile
.PHONY: help dev dev-mock build build-server build-frontend build-embed \
payload payload-macos payload-windows payload-linux \
installer installer-macos installer-windows installer-linux \
clean test lint fmt
VERSION ?= v0.1.0
BUILD_TIME := $(shell date -u +%Y-%m-%dT%H:%M:%SZ)
OS := $(shell uname -s | tr A-Z a-z)
DIST := dist
# ── 幫助 ───────────────────────────────────────────────────
help:
@echo "visionA-local - Available targets:"
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | \
awk 'BEGIN {FS = ":.*?## "}; {printf " \033[36m%-22s\033[0m %s\n", $$1, $$2}'
# ── 開發 ───────────────────────────────────────────────────
dev: ## 開發模式（真實硬體 + 前後端 hot reload）
@$(MAKE) -j2 dev-server dev-frontend
dev-server:
cd server && go run main.go --dev
dev-mock: ## 開發模式（Mock）
@$(MAKE) -j2 dev-mock-server dev-frontend
dev-mock-server:
cd server && go run main.go --dev --mock --mock-devices=3 --mock-camera
dev-frontend:
cd frontend && pnpm dev
# ── Build（單元） ───────────────────────────────────────────
build: build-frontend build-embed build-server ## Build Go server binary (含 embedded Next.js)
build-frontend: ## 編譯 Next.js 靜態檔
cd frontend && pnpm build
build-embed: build-frontend
@rm -rf server/web/out
@mkdir -p server/web/out
cp -r frontend/out/. server/web/out/
build-server:
@mkdir -p $(DIST)
cd server && go build \
-ldflags="-X main.Version=$(VERSION) -X main.BuildTime=$(BUILD_TIME)" \
-o ../$(DIST)/visiona-local-server main.go
# ── Payload 準備 ────────────────────────────────────────────
payload: payload-$(OS) ## 依當前 OS 準備 payload
payload-macos: build ## 準備 macOS 的 Wails payload
@echo "Staging macOS payload..."
@rm -rf visiona-local/payload
@mkdir -p visiona-local/payload/{bin,data/nef/kl520,data/nef/kl720,scripts/wheels,python}
cp $(DIST)/visiona-local-server visiona-local/payload/bin/
cp server/data/models.json visiona-local/payload/data/
cp server/data/nef/kl520/*.nef visiona-local/payload/data/nef/kl520/
cp server/data/nef/kl720/*.nef visiona-local/payload/data/nef/kl720/
cp server/scripts/kneron_bridge.py visiona-local/payload/scripts/
cp server/scripts/requirements.txt visiona-local/payload/scripts/
# Python runtime（python-build-standalone）
cp vendor/python/cpython-3.12-macos-x64.tar.gz visiona-local/payload/python/
# Wheels
cp vendor/wheels/macos-x64/*.whl visiona-local/payload/scripts/wheels/
# ffmpeg (LGPL static)
cp vendor/ffmpeg/macos-x64/ffmpeg visiona-local/payload/bin/
chmod +x visiona-local/payload/bin/ffmpeg
# yt-dlp
cp vendor/yt-dlp/yt-dlp_macos visiona-local/payload/bin/yt-dlp
chmod +x visiona-local/payload/bin/yt-dlp
payload-windows: build
@echo "Staging Windows payload..."
@rm -rf visiona-local/payload
@mkdir -p visiona-local/payload/{bin,data/nef/kl520,data/nef/kl720,scripts/wheels,python,drivers/amd64}
cp $(DIST)/visiona-local-server.exe visiona-local/payload/bin/
cp server/data/models.json visiona-local/payload/data/
cp -r server/data/nef/* visiona-local/payload/data/nef/
cp server/scripts/kneron_bridge.py visiona-local/payload/scripts/
cp server/scripts/requirements.txt visiona-local/payload/scripts/
cp vendor/python/cpython-3.12-windows-x64.tar.gz visiona-local/payload/python/
cp vendor/wheels/windows-x64/*.whl visiona-local/payload/scripts/wheels/
cp vendor/ffmpeg/windows-x64/*.{exe,dll} visiona-local/payload/bin/
cp vendor/yt-dlp/yt-dlp.exe visiona-local/payload/bin/
# WinUSB driver
cp vendor/drivers/kneron_winusb.inf visiona-local/payload/drivers/
cp vendor/drivers/amd64/*.dll visiona-local/payload/drivers/amd64/
cp vendor/drivers/libusb-1.0.dll visiona-local/payload/bin/
payload-linux: build
@echo "Staging Linux payload..."
@rm -rf visiona-local/payload
@mkdir -p visiona-local/payload/{bin,data/nef/kl520,data/nef/kl720,scripts/wheels,python}
cp $(DIST)/visiona-local-server visiona-local/payload/bin/
cp server/data/models.json visiona-local/payload/data/
cp -r server/data/nef/* visiona-local/payload/data/nef/
cp server/scripts/kneron_bridge.py visiona-local/payload/scripts/
cp server/scripts/requirements.txt visiona-local/payload/scripts/
cp vendor/python/cpython-3.12-linux-x64.tar.gz visiona-local/payload/python/
cp vendor/wheels/linux-x64/*.whl visiona-local/payload/scripts/wheels/
cp vendor/ffmpeg/linux-x64/ffmpeg visiona-local/payload/bin/
chmod +x visiona-local/payload/bin/ffmpeg
cp vendor/yt-dlp/yt-dlp visiona-local/payload/bin/
chmod +x visiona-local/payload/bin/yt-dlp
# 內帶 libusb 供 AppImage 使用
cp /usr/lib/x86_64-linux-gnu/libusb-1.0.so.0 visiona-local/payload/bin/
# ── Installer 建置 ──────────────────────────────────────────
installer: installer-$(OS) ## 依當前 OS 建 installer
installer-macos: payload-macos
cd visiona-local && wails build -platform darwin/amd64 -clean
codesign --force --deep --sign - visiona-local/build/bin/visiona-local.app
mkdir -p $(DIST)
dmgbuild -s dmg-config.py "visionA-local" \
$(DIST)/visiona-local-$(VERSION)-macos-x64.dmg
installer-windows: payload-windows
cd visiona-local && wails build -platform windows/amd64 -clean -webview2 embed
mkdir -p $(DIST)
iscc /DVERSION=$(VERSION) visiona-local-installer.iss
installer-linux: payload-linux
cd visiona-local && wails build -platform linux/amd64 -clean
bash scripts/build-appimage.sh $(VERSION)
# ── 測試 / Lint ─────────────────────────────────────────────
test: test-server test-frontend
test-server:
cd server && go test -v ./...
test-frontend:
cd frontend && pnpm test
lint:
cd server && go vet ./...
cd frontend && pnpm lint
fmt:
cd server && go fmt ./...
# ── 清理 ───────────────────────────────────────────────────
clean:
rm -rf $(DIST)
rm -rf frontend/.next frontend/out
rm -rf server/web/out
@mkdir -p server/web/out && touch server/web/out/.gitkeep
rm -rf visiona-local/build visiona-local/payload
@mkdir -p visiona-local/payload && touch visiona-local/payload/.gitkeep
```
---
## 2. Vendor 目錄結構（離線打包依賴）
**關鍵：所有第三方二進位都放進 `vendor/`，由建置腳本首次執行時透過 `make vendor-sync` 下載。一旦下載就 cache，之後 offline build。**
```
/Users/jimchen/visionA/local-tool/vendor/
├── python/ ← python-build-standalone tarballs
│ ├── cpython-3.12-macos-x64.tar.gz
│ ├── cpython-3.12-windows-x64.tar.gz
│ └── cpython-3.12-linux-x64.tar.gz
├── wheels/ ← 預先下載的 Python wheels
│ ├── macos-x64/
│ │ ├── numpy-*.whl
│ │ ├── opencv_python_headless-*.whl
│ │ ├── pyusb-*.whl
│ │ └── KneronPLUS-*.whl
│ ├── windows-x64/
│ └── linux-x64/
├── ffmpeg/ ← LGPL static builds
│ ├── macos-x64/ffmpeg
│ ├── windows-x64/{ffmpeg.exe, *.dll}
│ └── linux-x64/ffmpeg
├── yt-dlp/
│ ├── yt-dlp_macos
│ ├── yt-dlp.exe
│ └── yt-dlp
└── drivers/ ← Windows WinUSB driver
├── kneron_winusb.inf
├── libusb-1.0.dll
└── amd64/
```
### 2.1 `make vendor-sync` 腳本（首次 setup 用）
```bash
#!/usr/bin/env bash
# scripts/vendor-sync.sh - 下載所有第三方依賴到 vendor/
set -e
VENDOR=vendor
mkdir -p $VENDOR/{python,wheels,ffmpeg,yt-dlp,drivers}
# 1. python-build-standalone
PBS_VERSION="20250317"
PBS_PY="3.12.9"
PBS_BASE="https://github.com/astral-sh/python-build-standalone/releases/download/$PBS_VERSION"
curl -L -o $VENDOR/python/cpython-3.12-macos-x64.tar.gz \
"$PBS_BASE/cpython-$PBS_PY+$PBS_VERSION-x86_64-apple-darwin-install_only.tar.gz"
curl -L -o $VENDOR/python/cpython-3.12-windows-x64.tar.gz \
"$PBS_BASE/cpython-$PBS_PY+$PBS_VERSION-x86_64-pc-windows-msvc-install_only.tar.gz"
curl -L -o $VENDOR/python/cpython-3.12-linux-x64.tar.gz \
"$PBS_BASE/cpython-$PBS_PY+$PBS_VERSION-x86_64-unknown-linux-gnu-install_only.tar.gz"
# 2. Python wheels（用每個平台的 Python 預先下載）
# 注意：必須在對應平台上跑 pip download 才能拿到正確的 wheel tag
# 這裡假設使用者已在 macOS 機器上跑過：
# pip download -d vendor/wheels/macos-x64 \
# --platform macosx_11_0_x86_64 --python-version 3.12 --only-binary=:all: \
# numpy opencv-python-headless pyusb
# KneronPLUS wheel 另外手動放進去（從 edge-ai-platform/installer/wheels/ 複製）
cp -n ../edge-ai-platform/installer/wheels/macos/KneronPLUS*.whl $VENDOR/wheels/macos-x64/ 2>/dev/null || true
cp -n ../edge-ai-platform/installer/wheels/linux/KneronPLUS*.whl $VENDOR/wheels/linux-x64/ 2>/dev/null || true
cp -n ../edge-ai-platform/installer/wheels/windows/KneronPLUS*.whl $VENDOR/wheels/windows-x64/ 2>/dev/null || true
# 3. ffmpeg LGPL
FFMPEG_VER="7.1"
# macOS
curl -L -o /tmp/ffmpeg-mac.zip "https://evermeet.cx/ffmpeg/ffmpeg-$FFMPEG_VER.zip"
unzip -o /tmp/ffmpeg-mac.zip -d $VENDOR/ffmpeg/macos-x64/
# Windows（BtbN LGPL build）
curl -L -o /tmp/ffmpeg-win.zip \
"https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-n$FFMPEG_VER-latest-win64-lgpl-shared-$FFMPEG_VER.zip"
# 解壓 ffmpeg.exe 與需要的 DLLs 到 vendor/ffmpeg/windows-x64/
# Linux
curl -L -o /tmp/ffmpeg-linux.tar.xz \
"https://johnvansickle.com/ffmpeg/releases/ffmpeg-release-amd64-static.tar.xz"
tar -xf /tmp/ffmpeg-linux.tar.xz -C /tmp/
cp /tmp/ffmpeg-*-amd64-static/ffmpeg $VENDOR/ffmpeg/linux-x64/
# 4. yt-dlp
YTDLP_BASE="https://github.com/yt-dlp/yt-dlp/releases/latest/download"
curl -L -o $VENDOR/yt-dlp/yt-dlp_macos "$YTDLP_BASE/yt-dlp_macos"
curl -L -o $VENDOR/yt-dlp/yt-dlp.exe "$YTDLP_BASE/yt-dlp.exe"
curl -L -o $VENDOR/yt-dlp/yt-dlp "$YTDLP_BASE/yt-dlp"
chmod +x $VENDOR/yt-dlp/yt-dlp_macos $VENDOR/yt-dlp/yt-dlp
# 5. WinUSB driver（從 edge-ai-platform 複製）
cp -r ../edge-ai-platform/installer/drivers/* $VENDOR/drivers/
echo "✅ Vendor sync complete."
```
**vendor/ 是否進 git？（第三輪使用者決策 Q-D=D2：不進 git）**
- **整個 `vendor/` 目錄加入 `.gitignore`**，不進版本控制
- 所有第三方二進位（Python tarball、ffmpeg、yt-dlp、KneronPLUS wheel、WinUSB driver 等）都由 `make vendor-sync` 從來源下載
- 開發者第一次 clone 後執行 `make vendor-sync` 即可取得完整 vendor tree
- CI 亦在每次 build 前跑 `make vendor-sync`（可加 cache 加速）
- 保留 `vendor/.gitkeep`（或 `vendor/README.md`）讓空目錄存在並說明取得方式
- 優點：repo 保持小；缺點：依賴外部下載來源可用性（由 R8 風險緩解處理 — pbs 下載 URL pin 版本 + 備援 mirror）
**`.gitignore` 片段：**
```gitignore
# 第三方依賴（由 make vendor-sync 下載，不進 git）
/vendor/**
!/vendor/.gitkeep
!/vendor/README.md
# 建置產出
/dist/
/visiona-local/build/
/visiona-local/payload/
```
---
## 3. CI 策略（選配，第一版可純手動）
### 3.1 建議：GitHub Actions matrix build
```yaml
# .github/workflows/release.yml
name: Release
on:
push:
tags:
- 'v*'
jobs:
build-macos:
runs-on: macos-13 # Intel runner (x86_64)
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version: '1.22'
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'pnpm'
cache-dependency-path: 'frontend/pnpm-lock.yaml'
- name: Install Wails
run: go install github.com/wailsapp/wails/v2/cmd/wails@latest
- name: Install dmgbuild
run: pip install dmgbuild
- name: Vendor sync
run: make vendor-sync
- name: Build installer
run: make installer-macos VERSION=${{ github.ref_name }}
- uses: actions/upload-artifact@v4
with:
name: macos-installer
path: dist/*.dmg
build-windows:
runs-on: windows-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
- name: Install Wails
run: go install github.com/wailsapp/wails/v2/cmd/wails@latest
- name: Install Inno Setup
run: choco install innosetup -y
- run: make vendor-sync
- run: make installer-windows VERSION=${{ github.ref_name }}
- uses: actions/upload-artifact@v4
with:
name: windows-installer
path: dist/*.exe
build-linux:
runs-on: ubuntu-22.04
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
- name: Install Wails deps
run: |
sudo apt-get update
sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.1-dev \
libusb-1.0-0-dev
- name: Install Wails
run: go install github.com/wailsapp/wails/v2/cmd/wails@latest
- name: Install appimagetool
run: |
wget https://github.com/AppImage/AppImageKit/releases/download/continuous/appimagetool-x86_64.AppImage
chmod +x appimagetool-x86_64.AppImage
sudo mv appimagetool-x86_64.AppImage /usr/local/bin/appimagetool
- run: make vendor-sync
- run: make installer-linux VERSION=${{ github.ref_name }}
- uses: actions/upload-artifact@v4
with:
name: linux-installer
path: dist/*.AppImage
release:
needs: [build-macos, build-windows, build-linux]
runs-on: ubuntu-latest
steps:
- uses: actions/download-artifact@v4
- uses: softprops/action-gh-release@v2
with:
files: |
macos-installer/*.dmg
windows-installer/*.exe
linux-installer/*.AppImage
```
### 3.2 第一版可以不用 CI
MVP 階段可以**純手動**：
- 在自己的 Mac 上 `make installer-macos`
- 用 UTM / Parallels VM 跑 Windows 11 `make installer-windows`
- 用 Docker / multipass VM 跑 Ubuntu 22.04 `make installer-linux`
CI 可以等 M5 之後再做。
---
## 4. 版本號管理
單一來源：Git tag `v1.0.0` → 透過 Makefile `VERSION` 變數傳入：
- Go binary：`-ldflags "-X main.Version=$(VERSION)"`
- Wails: 讀取 `wails.json` 的 `info.productVersion`
- Installer 檔名：`visiona-local-v1.0.0-*`
**建議版本策略：**
- `v0.x.x`：MVP / alpha
- `v1.0.0`：第一個對內部釋出的穩定版
- 每個 milestone 對應一個 minor（M1→v0.1.0、M2→v0.2.0、M6→v1.0.0）
---
## 5. 開發迭代速度優化
- **dev 模式不用 payload**：`make dev` 直接 `go run` server + `pnpm dev` 前端，不過 Wails app
- **dev 模式用系統 Python**：`--python-mode=system` 避免每次都要解壓內嵌 runtime
- **前端改動不用重 build server**：`go run main.go --dev` 時 `web/out` 不啟用，前端直接連 3000 port

261
local-tool/.autoflow/04-architecture/code-reuse-plan.md Normal file
View File

@ -0,0 +1,261 @@
# Code Reuse Plan — visionA-local
> 從 `/Users/jimchen/Innovedus/edge-ai-platform/edge-ai-platform/` 取用程式碼的完整對照表。
> 三種策略：**直接複製**、**改寫**、**新寫**。
---
## 1. 總體比例（預估）
- **直接複製**：~60% LOC
- **改寫**：~20%
- **新寫**：~20%
- **刪除**：獨立計算，見 [`removed-code.md`](./removed-code.md)
## 2. 目錄層級策略
| From（edge-ai-platform） | To（local_tool） | 策略 | 備註 |
|------------------------|----------------|------|------|
| `server/main.go` | `server/main.go` | **改寫** | 移除 cluster / tunnel / relay / hwid / gitea 邏輯 |
| `server/go.mod` | `server/go.mod` | **改寫** | 移除不再需要的 imports；module name 可改為 `visiona-local` |
| `server/go.sum` | `server/go.sum` | **改寫** | 跟著 go.mod 重新生成 |
| `server/internal/api/router.go` | `server/internal/api/router.go` | **改寫** | 見 [`api-endpoints.md`](./api-endpoints.md) §4 |
| `server/internal/api/middleware.go` | 同路徑 | **直接複製** | |
| `server/internal/api/handlers/` | 同路徑 | **部分複製 / 改寫** | 見下方 §3.1 |
| `server/internal/api/ws/` | 同路徑 | **部分複製 / 改寫** | 見下方 §3.2 |
| `server/internal/api/api_e2e_test.go` | 同路徑 | **改寫** | 刪除 cluster / flash / auth test case |
| `server/internal/camera/` | 同路徑 | **直接複製** | 除了 ffmpeg 路徑查找改為「優先 bundled」，見 §3.4 |
| `server/internal/config/config.go` | 同路徑 | **改寫** | 見 §3.3 |
| `server/internal/deps/` | 同路徑 | **改寫** | 移除 update / relay 相關檢查 |
| `server/internal/device/` | 同路徑 | **直接複製** | 核心裝置管理 |
| `server/internal/driver/` | 同路徑 | **直接複製** | |
| `server/internal/inference/` | 同路徑 | **直接複製** | |
| `server/internal/model/` | 同路徑 | **直接複製** | |
| `server/internal/flash/` | ❌ **刪除** | 使用者決策 Q9 |
| `server/internal/cluster/` | ❌ **刪除** | 使用者決策 |
| `server/internal/tunnel/` | ❌ **刪除** | 使用者決策 |
| `server/internal/update/` | ❌ **刪除** | 使用者決策 Q6 |
| `server/pkg/logger/` | 同路徑 | **直接複製** | |
| `server/pkg/hwid/` | ❌ **刪除** | 只給 relay 用的 |
| `server/cmd/relay-server/` | ❌ **刪除** | 不需要 relay |
| `server/tray/` | ❌ **刪除** | 使用者決策 Q-A=A3：砍掉 tray，省跨平台圖資產與 Wails tray 踩坑 |
| `server/scripts/kneron_bridge.py` | `server/scripts/kneron_bridge.py` | **直接複製** | |
| `server/scripts/requirements.txt` | 同路徑 | **直接複製** | |
| `server/scripts/update_kl720_firmware.py` | ❌ **刪除** | flash 已砍 |
| `server/scripts/firmware/` | ❌ **刪除** | 同上 |
| `server/data/models.json` | 同路徑 | **直接複製** | |
| `server/data/nef/kl520/` | 同路徑 | **直接複製** | 全部預置模型 |
| `server/data/nef/kl720/` | 同路徑 | **直接複製** | |
| `server/web/` | 同路徑（空目錄） | **直接複製** | go:embed 掛載點 |
| `frontend/` | `frontend/` | **改寫** | M1 就要清乾淨：刪除 cluster / relay / tunnel 相關頁面、元件、store、API client，讓 `pnpm build` 通過且 UI 乾淨（使用者決策 Q-C=C2） |
| `installer/` | `visiona-local/` | **改寫（改名 + 精簡）** | 見 §3.5 |
| `installer/wheels/` | `vendor/wheels/` 或 `visiona-local/payload/scripts/wheels/` | **直接複製** | KneronPLUS wheel |
| `installer/drivers/` | `vendor/drivers/` 或 `visiona-local/payload/drivers/` | **直接複製** | Windows WinUSB |
| `installer/payload/` | `visiona-local/payload/` | **結構沿用，內容重建** | 由 Makefile payload target 重新 stage |
| `Makefile` | `Makefile` | **改寫** | 見 [`build-pipeline.md`](./build-pipeline.md) |
| `docker/` | ❌ **刪除** | |
| `scripts/deploy-*.sh` | ❌ **刪除** | |
| `scripts/kneron_detect.py` | `server/scripts/kneron_detect.py` | **直接複製** | installer 裝置偵測用 |
| `tools/` | 視檔案決定 | **多數刪除** | 只保留開發相關的 script |
| `docs/` | ❌ **刪除**（之後重寫） | | |
## 3. 需要改寫的檔案細節
### 3.1 `server/internal/api/handlers/`
| 檔案 | 策略 | 動作 |
|------|-----|-----|
| `system_handler.go` | 改寫 | 移除 `CheckUpdate`、`giteaURL` 參數；刪除 `update-check` handler |
| `model_handler.go` | 直接複製 | |
| `model_upload_handler.go` | 直接複製 | |
| `device_handler.go` | 改寫 | 移除 `FlashDevice` handler 與 `flashSvc` 注入 |
| `camera_handler.go` | 直接複製 | 但 `StartFromURL` 內部的 yt-dlp 路徑查找改為 bundled（見 §3.4） |
| `cluster_handler.go` | ❌ 刪除 | |
### 3.2 `server/internal/api/ws/`
| 檔案 | 策略 |
|------|-----|
| `hub.go` | 直接複製 |
| `device_events.go` | 直接複製 |
| `server_logs.go` | 直接複製 |
| `inference.go` | 直接複製 |
| `flash_progress.go` | ❌ 刪除 |
| `cluster_*.go` | ❌ 刪除 |
### 3.3 `server/internal/config/config.go` 改寫版
```go
package config
import (
"flag"
"fmt"
"os"
"path/filepath"
)
type Config struct {
Port int
Host string
MockMode bool
MockCamera bool
MockDeviceCount int
LogLevel string
DevMode bool
PythonBin string // 新增：由 Wails app 傳入
ScriptsDir string // 新增
DataDir string // 新增
// ❌ 以下全部移除：
// RelayURL, RelayToken, GUIMode, GiteaURL
}
func Load() *Config {
cfg := &Config{}
flag.IntVar(&cfg.Port, "port", 3721, "Server port")
flag.StringVar(&cfg.Host, "host", "127.0.0.1", "Server host (always localhost)")
flag.BoolVar(&cfg.MockMode, "mock", false, "Enable mock device driver")
flag.BoolVar(&cfg.MockCamera, "mock-camera", false, "Enable mock camera")
flag.IntVar(&cfg.MockDeviceCount, "mock-devices", 1, "Number of mock devices")
flag.StringVar(&cfg.LogLevel, "log-level", "info", "Log level")
flag.BoolVar(&cfg.DevMode, "dev", false, "Dev mode")
flag.StringVar(&cfg.PythonBin, "python", "", "Path to python3 interpreter")
flag.StringVar(&cfg.ScriptsDir, "scripts-dir", "", "Path to scripts directory")
flag.StringVar(&cfg.DataDir, "data-dir", "", "Path to data directory")
flag.Parse()
// 合理 default（dev 模式）
if cfg.ScriptsDir == "" {
cfg.ScriptsDir = filepath.Join(".", "scripts")
}
if cfg.DataDir == "" {
cfg.DataDir = filepath.Join(".", "data")
}
return cfg
}
func (c *Config) Addr() string {
return fmt.Sprintf("%s:%d", c.Host, c.Port)
}
```
### 3.4 ffmpeg / yt-dlp 路徑查找
新增 `server/internal/camera/binaries.go`：
```go
package camera
import (
"os"
"path/filepath"
"runtime"
)
// FfmpegBinary returns the ffmpeg binary to use, preferring bundled over PATH.
func FfmpegBinary() string {
if p := os.Getenv("VISIONA_FFMPEG"); p != "" {
return p
}
if p := bundled("ffmpeg"); p != "" {
return p
}
return "ffmpeg" // PATH fallback
}
func YtDlpBinary() string {
if p := os.Getenv("VISIONA_YTDLP"); p != "" {
return p
}
if p := bundled("yt-dlp"); p != "" {
return p
}
return "yt-dlp"
}
func bundled(name string) string {
exe, err := os.Executable()
if err != nil {
return ""
}
dir := filepath.Dir(exe)
candidate := filepath.Join(dir, name)
if runtime.GOOS == "windows" {
candidate += ".exe"
}
if _, err := os.Stat(candidate); err == nil {
return candidate
}
return ""
}
```
### 3.5 `installer/app.go` → `visiona-local/app.go` 改寫
原 894 行，改寫要點：
**移除的欄位 / 函式**：
- `relayURL`, `relayToken`, `dashboardURL`
- `GetDashboardURL`, `GenerateToken`, `OpenBrowser` 中任何跟 relay 有關的邏輯
- `stepInstallUSBDriver` 需要保留，但只給 Windows 用（flash driver 已砍但 WinUSB 還需要）
- `stepInstallFfmpeg` **改寫**：不去系統 PATH 找，而是從 payload/bin 解壓 bundled ffmpeg
**新增的欄位 / 函式**：
- `pythonMode`（`bundled` / `system` / `auto`）
- `stepSetupPythonStandalone`（解壓內嵌 python-build-standalone）
- `stepSetupPythonSystem`（fallback 到系統 python，沿用舊的 `setupPythonVenv` 邏輯）
- `stepInstallWheelsOffline`（用 `pip install --no-index --find-links`）
- `i18n` translator 注入
- `launchServer` / `stopServer` / `watchServer`（見 [`tray-and-lifecycle.md`](./tray-and-lifecycle.md) §4）
- `single-instance lock`
**保留（幾乎不動）**：
- `GetSystemInfo`, `BrowseDirectory`, `ValidatePath`
- `stepCreateDir`, `stepExtractBinary`, `stepExtractData`, `stepExtractScripts`
- `DetectHardware`, `parseDetectOutput`
- `extractFile`, `extractDir`
- Platform-specific 檔案（`platform_darwin.go` / `platform_linux.go` / `platform_windows.go`）
## 4. 新寫的程式碼
完全新寫的檔案：
### 4.1 Wails app 側
```
visiona-local/
├── python_runtime.go ← python-build-standalone 解壓 + 版本偵測
├── server_launcher.go ← spawn / stop / watch Go server
├── lifecycle.go ← single-instance lock、port picking、cleanup
├── ipc.go ← /ipc/raise 小型 HTTP listener
├── i18n.go ← Translator + locales embed
└── locales/
├── en.json
└── zh-TW.json
```
### 4.2 Build / CI
```
scripts/
├── vendor-sync.sh ← 下載 python-build-standalone、ffmpeg、yt-dlp 到 vendor/
├── build-appimage.sh ← Linux AppImage 打包腳本
├── check-i18n.sh ← 檢查 i18n key 一致性
└── smoke-test.sh ← 安裝後 smoke test
visiona-local-installer.iss ← Inno Setup 腳本
dmg-config.py ← macOS dmgbuild 設定
.github/workflows/release.yml ← CI（選配）
```
## 5. 搬家步驟（建議執行順序）
1. **建立骨架**：`mkdir -p local_tool/{server,frontend,visiona-local,vendor,scripts,dist}`
2. **複製 server core**：`cp -r edge-ai-platform/server/{internal/{api,camera,config,deps,device,driver,inference,model},pkg/logger,scripts,data,web} local_tool/server/`
3. **跳過要刪的 package**：不要複製 `cluster`、`tunnel`、`flash`、`update`、`pkg/hwid`、`cmd/relay-server`、`tray`（使用者決策 Q-A：砍 tray）
4. **改寫 `main.go` + `config.go` + `router.go`**（見上方 §3）
5. **改寫 go.mod**：`go mod init visiona-local/server` → `go mod tidy`（會自動清掉 unused imports）
6. **驗證 `go build ./...` 通過**
7. **複製 frontend**：`cp -r edge-ai-platform/frontend local_tool/frontend`
8. **清理前端 cluster / relay / tunnel UI**（使用者決策 Q-C=C2：M1 就要清乾淨，不留到 M2）：刪除 `src/app/clusters/`、`src/app/workspace/cluster/`、`src/components/cluster/`、`src/components/relay-token-sync.tsx`、`src/lib/api/clusters.ts`、`src/lib/api/tunnel.ts`（若有）、`src/lib/api/update.ts`（若有），修改 `sidebar.tsx` 移除 Clusters 導航項、`page.tsx` 移除 cluster stat、`settings/page.tsx` 移除 relay / cluster 區塊。最後驗證 `pnpm build` 通過且 UI 乾淨。
9. **複製 installer**：`cp -r edge-ai-platform/installer local_tool/visiona-local`，改 `main.go` 的 app 名稱與 bundle ID
10. **先跑 M1-12**：全新機器上 installer 能裝起來並跑通 Mock 模式

392
local-tool/.autoflow/04-architecture/dependency-bundling.md Normal file
View File

@ -0,0 +1,392 @@
# Dependency Bundling — visionA-local
> 所有外部依賴的內嵌策略：Python runtime、KneronPLUS、ffmpeg、yt-dlp、預置模型。
> 核心目標：**完全離線、零外部依賴、一鍵安裝。**
---
## 1. Python Runtime（雙策略）
### 1.1 總策略
**主策略 A（預設）：內嵌 [python-build-standalone](https://github.com/astral-sh/python-build-standalone)。**
**備策略 B（fallback）：偵測系統 `python3`。**
這是使用者明確決策（Q1 = A 且保留 B）：正常使用者永遠走 A，但保留 B 作為：
- 開發模式（`--dev` flag，不用解壓內嵌 runtime，加快迭代）
- Runtime 壞掉時的救援（例如內嵌 runtime 因為 anti-virus 誤殺被刪）
- 某些特殊環境下策略 A 不可用時的退路
### 1.2 python-build-standalone 版本選擇
| 項目 | 選擇 |
|------|------|
| Python 版本 | **3.12.x**（最新穩定、KneronPLUS wheel 在 3.12 上有 ABI 支援） |
| 變體（flavor） | `install_only` 版本（不含 build tools，檔案較小） |
| 平台 tarball | `cpython-3.12.x-{arch}-{os}-install_only.tar.gz` |
**各平台下載 URL 模式：**
- macOS x64：`cpython-3.12.x-x86_64-apple-darwin-install_only.tar.gz`（~30MB 壓縮 / ~90MB 解壓）
- Windows x64：`cpython-3.12.x-x86_64-pc-windows-msvc-install_only.tar.gz`（~30MB / ~90MB）
- Linux x64：`cpython-3.12.x-x86_64-unknown-linux-gnu-install_only.tar.gz`（~30MB / ~100MB）
下載後存放到 `visiona-local/payload/python/<os>/` 目錄，build 時透過 `go:embed` 塞進 Wails binary。
### 1.3 策略 A：內嵌解壓流程
```go
// visiona-local/python_runtime.go (新寫)
// 首次啟動時執行
func (inst *Installer) stepSetupPythonStandalone(config InstallConfig) error {
// 1. 解壓內嵌的 python tarball → ~/Library/Application Support/visiona-local/python/
pythonDir := filepath.Join(config.InstallDir, "python")
if err := inst.extractTarGz("payload/python/darwin/python-3.12.tar.gz", pythonDir); err != nil {
// 解壓失敗 → 嘗試策略 B
inst.logger.Warn("Bundled Python extract failed: %v, falling back to system python3", err)
return inst.stepSetupPythonSystem(config)
}
// 2. 驗證 python3 可執行
pythonBin := filepath.Join(pythonDir, "bin", "python3") // Linux/mac
if runtime.GOOS == "windows" {
pythonBin = filepath.Join(pythonDir, "python.exe")
}
if _, err := exec.Command(pythonBin, "--version").Output(); err != nil {
inst.logger.Warn("Bundled Python unusable: %v, falling back", err)
return inst.stepSetupPythonSystem(config)
}
// 3. 建立 venv（使用內嵌 python）
venvDir := filepath.Join(config.InstallDir, "venv")
if err := exec.Command(pythonBin, "-m", "venv", venvDir).Run(); err != nil {
return fmt.Errorf("create venv failed: %w", err)
}
// 4. 離線安裝 wheels
return inst.installWheelsOffline(venvDir, config)
}
```
### 1.4 策略 B：系統 Python fallback
```go
func (inst *Installer) stepSetupPythonSystem(config InstallConfig) error {
// 沿用 edge-ai-platform 現有 findPython3() 邏輯
pythonBin, err := findPython3()
if err != nil {
return fmt.Errorf("no usable python3 found: %w (請安裝 Python 3.12+ 或重新安裝 visionA-local)", err)
}
// 建 venv + 離線安裝 wheels
venvDir := filepath.Join(config.InstallDir, "venv")
if err := exec.Command(pythonBin, "-m", "venv", venvDir).Run(); err != nil {
return err
}
return inst.installWheelsOffline(venvDir, config)
}
```
### 1.5 切換機制
**決策樹（首次安裝時執行一次）：**
```
start
↓
啟動旗標 --python-mode=auto|bundled|system (default: auto)
↓
是 auto？
├─ Yes → 嘗試 stepSetupPythonStandalone
│ 成功 → 記錄 python.mode=bundled 到 .installed
│ 失敗 → 嘗試 stepSetupPythonSystem
│ 成功 → 記錄 python.mode=system 到 .installed
│ 失敗 → 顯示錯誤，安裝中止
├─ bundled → 只嘗試 stepSetupPythonStandalone
└─ system → 只嘗試 stepSetupPythonSystem
```
**執行階段（每次啟動 server 時）：**
Go server 啟動時透過 `--python-path` flag 告訴 `kneron_bridge.py` 該用哪個 python interpreter。Wails app 從 `.installed` 讀出 `python.mode`，對應到 `venv/bin/python3` 路徑傳給 server：
```
Wails app → reads .installed → python.mode=bundled
→ spawns: visiona-local-server --python=/Users/.../venv/bin/python3
--scripts=/Users/.../scripts
```
### 1.6 需要的依賴清單
`scripts/requirements.txt`（沿用 edge-ai-platform 現有內容）：
```
numpy>=1.26,<2.0
opencv-python-headless>=4.9
pyusb>=1.2.1
# KneronPLUS wheel 單獨透過 --find-links 安裝，不列在 requirements.txt
```
**Mock 模式提示**：Mock 模式下 Go server **完全不 spawn** Python sidecar，`requirements.txt` 裡的 wheel 也不會被使用，但仍必須在首次安裝時完整裝進 venv（否則切到 Real 模式會失敗）。Mock 模式省的是 runtime 記憶體，不是安裝時間。
**離線安裝指令：**
```bash
pip install --no-index --find-links /path/to/wheels/ \
-r requirements.txt \
KneronPLUS
```
### 1.7 Wheels 內嵌結構
```
visiona-local/payload/scripts/wheels/
├── common/ ← 跨平台 pure-python
│ └── (無，opencv/numpy 都是 platform-specific)
├── macos-x64/
│ ├── numpy-1.26.4-cp312-cp312-macosx_10_9_x86_64.whl
│ ├── opencv_python_headless-4.9.0-cp312-cp312-macosx_10_13_x86_64.whl
│ ├── pyusb-1.2.1-py3-none-any.whl
│ └── KneronPLUS-2.0.0-cp312-cp312-macosx_11_0_x86_64.whl
├── windows-x64/
│ ├── numpy-1.26.4-cp312-cp312-win_amd64.whl
│ ├── opencv_python_headless-4.9.0-cp312-cp312-win_amd64.whl
│ ├── pyusb-1.2.1-py3-none-any.whl
│ └── KneronPLUS-3.1.2-cp312-cp312-win_amd64.whl
└── linux-x64/
├── numpy-1.26.4-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
├── opencv_python_headless-4.9.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
├── pyusb-1.2.1-py3-none-any.whl
└── KneronPLUS-3.1.2-cp312-cp312-manylinux2014_x86_64.whl
```
build 時只把**對應目標平台**的 wheel 塞進該平台的 payload，避免浪費空間。
---
## 2. KneronPLUS SDK
### 2.1 來源
原專案 `installer/wheels/` 已有三平台 wheel（共 ~3.9MB）：
| 平台 | 檔案 | 原生函式庫 | 備註 |
|------|------|-----------|------|
| macOS | `KneronPLUS-2.0.0-cp39-abi3-macosx_11_0_x86_64.whl` | `.dylib` | **只有 x86_64**，Apple Silicon 走 Rosetta |
| Linux | `KneronPLUS-3.1.2-cp39-abi3-manylinux_2_17_x86_64.whl` | `.so` | 需要 libusb-1.0 |
| Windows | `KneronPLUS-3.1.2-cp39-abi3-win_amd64.whl` | `.dll` | 需要 WinUSB driver |
**abi3 是好消息**：wheel 對 CPython 版本有 forward compatibility，不用每升 Python 就換 wheel。但我們仍建議 pin Python 3.12。
### 2.2 各平台特殊處理
#### macOS
- wheel 內的 `.dylib` 需要 **ad-hoc codesign**（`codesign --force --deep --sign - <path>`），否則 Gatekeeper 擋
- 這步在 `installer/app.go` 已有實作，沿用
- 首次啟動時可能跳 Gatekeeper 警告（因為沒有正式簽章），需要使用者**右鍵 → 開啟**（文件寫清楚）
#### Linux
- 需要 `libusb-1.0.so.0`。Ubuntu 22.04/24.04 **預設不安裝**，但是：
- 方法 A：`apt-get install libusb-1.0-0`（需 sudo）
- 方法 B（推薦）：**AppImage 內帶 libusb**，透過 `LD_LIBRARY_PATH` 指向 AppImage 內部
- 需要 udev rule 讓非 root 使用者存取 USB：
```
# /etc/udev/rules.d/99-kneron.rules
SUBSYSTEM=="usb", ATTRS{idVendor}=="3231", MODE="0666"
```
首次啟動時透過 `pkexec cp` 寫入（會跳 GUI 提權對話框），使用者拒絕就提示「需要 sudo 手動安裝，或用 sudo 跑一次 visionA-local」
#### Windows
- 需要安裝 **WinUSB driver**（把 Kneron USB 裝置綁定到 WinUSB driver interface）
- 原專案 `installer/drivers/kneron_winusb.inf` + `amd64/WdfCoInstaller01011.dll` + `winusbcoinstaller2.dll` 已有
- 透過 `pnputil /add-driver <inf> /install` 安裝，會彈 UAC
- 另外需要把 `libusb-1.0.dll` 放到 venv 的 `Scripts/` 或 `DLLs/` 目錄（沿用原專案做法）
### 2.3 安裝階段
在 `stepInstallKneronPlus` 步驟：
1. pip 離線安裝 wheel（解壓 .dylib/.so/.dll 到 venv/site-packages）
2. （macOS）對 `.dylib` 做 ad-hoc sign
3. （Linux）寫 udev rule
4. （Windows）呼叫 `pnputil` 安裝 WinUSB driver + 複製 libusb-1.0.dll
---
## 3. ffmpeg
### 3.1 策略
**內嵌 LGPL static build，不依賴系統 ffmpeg / brew / winget。**
**為何 LGPL 不 GPL**：GPL build 會感染整個產品授權。LGPL 允許商業使用，只要提供 LGPL 部分的 source 或 link。
### 3.2 各平台來源
| 平台 | 來源 | 檔名 | 大小 |
|------|------|------|------|
| macOS x64 | [evermeet.cx](https://evermeet.cx/ffmpeg/) LGPL static build | `ffmpeg` | ~35MB |
| Windows x64 | [BtbN/FFmpeg-Builds](https://github.com/BtbN/FFmpeg-Builds) `ffmpeg-n6.1-latest-win64-lgpl-shared-6.1.zip` 的 `ffmpeg.exe`（需連同幾個 DLL） | `ffmpeg.exe` + DLLs | ~45MB |
| Linux x64 | [johnvansickle.com](https://johnvansickle.com/ffmpeg/) LGPL static build | `ffmpeg` | ~40MB |
### 3.3 內嵌結構
```
visiona-local/payload/bin/
├── ffmpeg ← macOS / Linux（單檔 static）
├── ffmpeg.exe ← Windows
└── (Windows 需要的 DLLs, e.g. avcodec-61.dll, avformat-61.dll)
```
### 3.4 Go server 使用方式
現有 `server/internal/camera/` 透過 `exec.Command("ffmpeg", ...)` 呼叫。新版改為：
```go
// server/internal/camera/ffmpeg.go
func ffmpegBinary() string {
// 先查環境變數（dev 模式可 override）
if p := os.Getenv("VISIONA_FFMPEG"); p != "" {
return p
}
// 生產模式：從 installDir/bin 找
exe, _ := os.Executable()
dir := filepath.Dir(exe) // 這個 exe 是 visiona-local-server
bundled := filepath.Join(dir, "ffmpeg")
if runtime.GOOS == "windows" {
bundled += ".exe"
}
if _, err := os.Stat(bundled); err == nil {
return bundled
}
// fallback：PATH
return "ffmpeg"
}
```
### 3.5 授權聲明
需要在 Settings → About 頁顯示：
```
此產品包含以 LGPLv2.1+ 授權的 FFmpeg。
- FFmpeg source: https://ffmpeg.org
- LGPL license: https://www.gnu.org/licenses/lgpl-2.1.html
- Build provided by BtbN/FFmpeg-Builds (Windows/Linux) / evermeet.cx (macOS)
```
---
## 4. yt-dlp（使用者決策 Q10 = A，保留）
### 4.1 為何保留
`/api/media/url` endpoint 讓使用者可以丟 YouTube 或其他影片網址進來做離線推論，這對 demo 場景有價值（例如「拿 YouTube 影片跑物件偵測」），使用者明確要求保留。
### 4.2 內嵌方式
yt-dlp 有 **standalone executable**（自帶 Python runtime，不需要系統 Python），這是為離線部署設計的：
| 平台 | 檔案 | 來源 |
|------|------|------|
| macOS | `yt-dlp_macos` | [yt-dlp release](https://github.com/yt-dlp/yt-dlp/releases) |
| Linux | `yt-dlp` | 同上 |
| Windows | `yt-dlp.exe` | 同上 |
大小約 8-15MB per platform。放到 `visiona-local/payload/bin/yt-dlp{.exe}` 內嵌。
**注意：** 使用 standalone 版本而不是 `pip install yt-dlp`，因為我們想與主 venv 解耦，避免 yt-dlp 的依賴與 KneronPLUS 衝突。
### 4.3 Go server 使用方式
沿用 `exec.Command` 模式，path 查找與 ffmpeg 相同：先查 `VISIONA_YTDLP` 環境變數，再查同目錄 `bin/`。
### 4.4 授權與風險
- yt-dlp 是 Unlicense（public domain），無授權問題
- 風險：yt-dlp 對不同網站的相容性會隨時間腐敗，但對內部工具可接受（使用者自己升級也可以）
- 不做 auto-update yt-dlp（Q6 = 不做 auto-update）
---
## 5. 預置模型 .nef（使用者決策 Q5 = 全打包）
### 5.1 現狀
`edge-ai-platform/server/data/nef/` 總量 ~73MB，分布：
- `kl520/`：5-6 個 .nef（影像分類、物件偵測、臉辨）
- `kl720/`：5-6 個 .nef（同上但 KL720 版本）
### 5.2 策略
**全部打包**，不精簡。原因：
1. 使用者明確決策 Q5 = 全打包
2. 符合「完全離線、開箱即用」原則
3. ~73MB 相對於總安裝檔 ~300MB 不算大
4. 首次 demo 情境需要「看到最多示範」
> **授權待 Kneron 確認**：第四輪決策 R4-1 維持「不主動詢問、發佈前 gate」。若屆時確認不允許 re-distribute → 觸發 Plan B（見 [`plan-b-online-download.md`](./plan-b-online-download.md)）。
### 5.3 打包路徑
```
visiona-local/payload/data/nef/
├── kl520/
│ ├── classification_mobilenetv2.nef
│ ├── detection_yolov5s.nef
│ └── ...
└── kl720/
├── classification_resnet50.nef
└── ...
```
首次執行時解壓到 `~/Library/Application Support/visiona-local/data/nef/`（或對應平台路徑）。使用者上傳的自訂模型放在 `data/custom-models/`，兩者分開管理。
### 5.4 go:embed vs payload
**選 payload（解壓式），不選 go:embed。** 原因：
1. go:embed 73MB 進 Go binary 會讓 link 時間與記憶體暴漲
2. 解壓後使用者可以手動替換、刪除、增加
3. `installer/embed.go` 已有 payload 模式可沿用
---
## 6. 內嵌大小預估
### 6.1 未壓縮（Wails binary 解開後）
| 項目 | macOS x64 | Windows x64 | Linux x64 |
|------|----------|-------------|-----------|
| Wails binary（Go + WebView） | ~15MB | ~12MB | ~14MB |
| visiona-local-server（含 embedded Next.js） | ~30MB | ~30MB | ~30MB |
| python-build-standalone | ~90MB | ~90MB | ~100MB |
| Python wheels（numpy + opencv + pyusb + KneronPLUS） | ~50MB | ~50MB | ~55MB |
| ffmpeg | ~35MB | ~45MB | ~40MB |
| yt-dlp | ~10MB | ~12MB | ~10MB |
| 預置 .nef 模型 | 73MB | 73MB | 73MB |
| WinUSB driver | - | ~1MB | - |
| **合計（未壓縮）** | **~303MB** | **~313MB** | **~322MB** |
### 6.2 壓縮後（.dmg / .exe / .AppImage）
Wails payload 用 tar.gz 或 zstd 壓縮，預估壓縮率 60-65%：
| 平台 | 最終安裝檔大小 |
|------|--------------|
| macOS .dmg | **~195MB** |
| Windows .exe（Inno Setup） | **~205MB** |
| Linux .AppImage | **~210MB** |
符合 PRD 的「單平台 < 500MB」目標。
---
## 7. 依賴內嵌檢查清單（給 Build Pipeline）
每次 release build 時必須驗證：
- [ ] `python/<os>/python3 --version` 可執行
- [ ] `wheels/<os>/` 中所有 .whl 存在且對應正確的 cp312 + 平台 tag
- [ ] `bin/ffmpeg` 存在，`ffmpeg -version` 可執行，且**版本字串中有 "LGPL"**（不可是 GPL）
- [ ] `bin/yt-dlp` 存在，`yt-dlp --version` 可執行
- [ ] `data/nef/kl520/*.nef` 與 `data/nef/kl720/*.nef` 與 `data/models.json` 一致
- [ ] （Windows）`drivers/kneron_winusb.inf` + `amd64/*.dll` 存在
- [ ] 安裝檔大小 < 500MB

150
local-tool/.autoflow/04-architecture/design-doc.md Normal file
View File

@ -0,0 +1,150 @@
# 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 | 使用者 | 待確認 |

307
local-tool/.autoflow/04-architecture/i18n.md Normal file
View File

@ -0,0 +1,307 @@
# i18n — visionA-local 多語系
> 支援語言：**繁體中文（台灣）+ 英文**（使用者決策 Q13）
> 預設：跟隨系統語系；找不到對應時 fallback 英文
---
## 1. 涵蓋範圍
| 層 | 是否要 i18n | 方式 |
|----|-----------|------|
| Next.js 業務前端 | ✅ 必要 | i18next / next-intl |
| Wails app（安裝精靈、錯誤對話框） | ✅ 必要 | Go 端 i18n map |
| Go server log 訊息 | ❌ 英文固定 | 給開發者看，不翻譯 |
| API 錯誤訊息（JSON response） | ⚠️ 看情境 | code + message 英文；前端用 code 轉成對應語系 |
| README / 說明文件 | ⚠️ | 英文優先，第二版補中文 |
## 2. 前端 i18n（Next.js）
### 2.1 原專案現況
edge-ai-platform 的 `frontend/` 已經有 `useTranslation` hook（見 Design round 1），沿用即可。推測是用 `react-i18next` 或 `next-intl`。**M2 階段**拆分時一併確認並整合。
### 2.2 檔案結構
```
frontend/src/locales/
├── en/
│ ├── common.json
│ ├── dashboard.json
│ ├── devices.json
│ ├── models.json
│ ├── workspace.json
│ ├── settings.json
│ └── errors.json
└── zh-TW/
├── common.json
├── dashboard.json
├── devices.json
├── models.json
├── workspace.json
├── settings.json
└── errors.json
```
### 2.3 語系切換
- Settings 頁新增「語言」下拉：跟隨系統 / 中文 / English
- 使用者選擇後存進 `localStorage.locale`
- 下次啟動讀取此值；無值時讀 `navigator.language`
- 跟隨系統模式下，`zh-*` 全歸到 `zh-TW`，其他歸 `en`
### 2.4 關鍵字決策（避免翻譯混亂）
| 英文 | 繁中 | 備註 |
|------|------|------|
| Device | 裝置 | 不用「設備」 |
| Model | 模型 | |
| Inference | 推論 | 不用「推理」 |
| Workspace | 工作區 | |
| Mock mode | 模擬模式 | |
| Dashboard | 儀表板 | |
| Classification | 分類 | |
| Detection | 偵測 | 不用「檢測」 |
| Face recognition | 臉部辨識 | |
| Settings | 設定 | |
| Upload | 上傳 | |
| Flash | 燒錄 | （已砍，但文案保留供未來重開） |
---
## 3. Wails app i18n
> Tray 已砍（第三輪使用者決策 Q-A=A3），本節僅涵蓋安裝精靈與錯誤對話框。
### 3.1 為何獨立做
Wails app 是 Go，在 Go server 還沒啟動前就需要顯示文字（安裝精靈、錯誤對話框）。不能依賴前端 i18n。
### 3.2 實作
```go
// visiona-local/i18n.go
package main
import (
"embed"
"encoding/json"
"strings"
"golang.org/x/text/language"
)
//go:embed locales/*.json
var localesFS embed.FS
type Translator struct {
current language.Tag
messages map[language.Tag]map[string]string
}
func NewTranslator(preferred string) *Translator {
t := &Translator{
messages: make(map[language.Tag]map[string]string),
}
t.load("en")
t.load("zh-TW")
t.setLocale(preferred)
return t
}
func (t *Translator) load(code string) {
data, _ := localesFS.ReadFile("locales/" + code + ".json")
var m map[string]string
json.Unmarshal(data, &m)
tag, _ := language.Parse(code)
t.messages[tag] = m
}
func (t *Translator) setLocale(preferred string) {
if preferred == "" || preferred == "system" {
preferred = detectSystemLocale()
}
if strings.HasPrefix(preferred, "zh") {
t.current = language.TraditionalChinese
} else {
t.current = language.English
}
}
func (t *Translator) T(key string) string {
if msg, ok := t.messages[t.current][key]; ok {
return msg
}
// fallback to English
if msg, ok := t.messages[language.English][key]; ok {
return msg
}
return key // last resort
}
```
### 3.3 檔案
```
visiona-local/locales/
├── en.json
└── zh-TW.json
```
### 3.4 關鍵 key 清單（給安裝精靈）
```json
// en.json
{
"installer.welcome.title": "Welcome to visionA-local",
"installer.welcome.subtitle": "Kneron KL520/KL720 local development tool",
"installer.step.creating_dir": "Creating install directory",
"installer.step.extract_binary": "Extracting server binary",
"installer.step.extract_data": "Extracting model files",
"installer.step.setup_python": "Setting up Python runtime",
"installer.step.install_wheels": "Installing Python packages",
"installer.step.install_driver": "Installing USB device driver",
"installer.step.verify": "Verifying installation",
"installer.error.no_python": "Python 3.12 is required but not found on your system.",
"installer.error.driver_failed": "USB driver installation failed. You may need to allow the UAC prompt.",
"error.already_running": "visionA-local is already running.",
"error.port_in_use": "Port {port} is in use.",
"error.server_unhealthy": "Server did not respond in time."
}
```
```json
// zh-TW.json
{
"installer.welcome.title": "歡迎使用 visionA-local",
"installer.welcome.subtitle": "Kneron KL520/KL720 本機開發工具",
"installer.step.creating_dir": "建立安裝目錄",
"installer.step.extract_binary": "解壓伺服器程式",
"installer.step.extract_data": "解壓模型檔案",
"installer.step.setup_python": "設定 Python 執行環境",
"installer.step.install_wheels": "安裝 Python 套件",
"installer.step.install_driver": "安裝 USB 裝置驅動",
"installer.step.verify": "驗證安裝",
"installer.error.no_python": "找不到 Python 3.12。請安裝後重試，或使用內建 Python 模式。",
"installer.error.driver_failed": "USB 驅動安裝失敗，請確認已同意系統權限提示。",
"error.already_running": "visionA-local 已在執行中。",
"error.port_in_use": "連接埠 {port} 已被佔用。",
"error.server_unhealthy": "伺服器未在預期時間內回應。"
}
```
### 3.5 參數化
簡單字串替換 `{key}` → `strings.Replace`，不做複數形 / 性別等進階 i18n（不值得）。
---
## 4. 系統語系偵測
### 4.1 各平台 API
| 平台 | Go 偵測方式 |
|------|-----------|
| macOS | `defaults read -g AppleLocale` |
| Windows | `GetUserDefaultLocaleName` via golang.org/x/sys |
| Linux | 環境變數 `$LANG` / `$LC_MESSAGES` |
### 4.2 實作
```go
func detectSystemLocale() string {
// 1. 先查 env（跨平台通用）
for _, env := range []string{"LC_ALL", "LC_MESSAGES", "LANG"} {
if v := os.Getenv(env); v != "" {
return normalizeLocale(v)
}
}
// 2. 各平台特殊查詢
switch runtime.GOOS {
case "darwin":
out, _ := exec.Command("defaults", "read", "-g", "AppleLocale").Output()
return normalizeLocale(strings.TrimSpace(string(out)))
case "windows":
// GetUserDefaultLocaleName via syscall
return getWindowsLocale()
}
return "en"
}
func normalizeLocale(s string) string {
// "zh_TW.UTF-8" → "zh-TW"
s = strings.Split(s, ".")[0]
s = strings.Replace(s, "_", "-", -1)
if strings.HasPrefix(strings.ToLower(s), "zh") {
return "zh-TW"
}
return "en"
}
```
---
## 5. 翻譯流程與維護
### 5.1 新增字串的流程
1. 在 code 中使用 `t.T("some.new.key")`
2. 在 `en.json` 加上 key
3. 在 `zh-TW.json` 加上對應翻譯
4. lint 腳本檢查所有 key 在兩邊都存在（`scripts/check-i18n.sh`）
### 5.2 lint 腳本（建議加進 CI）
```bash
#!/usr/bin/env bash
# scripts/check-i18n.sh
set -e
for dir in frontend/src/locales visiona-local/locales; do
en_keys=$(jq -r 'keys[]' "$dir/en.json" | sort)
zh_keys=$(jq -r 'keys[]' "$dir/zh-TW.json" | sort)
diff <(echo "$en_keys") <(echo "$zh_keys") || {
echo "❌ i18n keys out of sync in $dir"
exit 1
}
done
echo "✅ i18n keys are in sync"
```
---
## 6. 第一版範圍（M2 階段實作）
**M2 先做**：
- [x] 英文 + 繁中 locale 檔建立
- [x] Wails app 端 i18n loader（安裝精靈 + 錯誤對話框）
- [x] 前端整合現有 i18n（沿用 edge-ai-platform 的 hook）
- [x] Settings 頁加入語言下拉
- [x] 切換語言後**需重啟 app 才生效**（首版妥協）
**首版策略**：切換語言 → 顯示「已儲存，重啟後生效」→ 使用者手動關閉再開。這樣可以避開：
- Next.js WebView 內的 i18n hot-reload 需要重跑所有 `useTranslation` hook
- Wails 原生 menu bar 需要 `runtime.MenuSetApplicationMenu()` 重建
- 安裝精靈與錯誤對話框已經是 one-shot，重啟沒成本
**M2 以後才做**：
- **動態語系切換（即時生效，不需重啟）**：對應 Design 規格 `10-i18n §10.7`，前端走 `i18n.changeLanguage()`、Wails 端 emit 事件重建 menu
- API error code 對照表 — 先讓前端直接顯示英文
- 複數形處理
### 6.1 Wails 原生 menu 快捷鍵清單（第四輪修訂）
對應第四輪決策 R4-6（⌘R → ⌘Shift+R、取消 ⌘Shift+W）：
| 功能 | 快捷鍵 | Wails menu API |
|------|-------|---------------|
| 前往 Dashboard | ⌘1 / Ctrl+1 | `keys.CmdOrCtrl("1")` |
| 前往 Devices | ⌘2 / Ctrl+2 | `keys.CmdOrCtrl("2")` |
| 前往 Models | ⌘3 / Ctrl+3 | `keys.CmdOrCtrl("3")` |
| 前往 Workspace | ⌘4 / Ctrl+4 | `keys.CmdOrCtrl("4")` |
| 設定 | ⌘, / Ctrl+, | `keys.CmdOrCtrl(",")` |
| 重新整理裝置 | **⌘Shift+R / Ctrl+Shift+R** | `keys.Combo("r", keys.CmdOrCtrlKey, keys.ShiftKey)` ｜ 避開 WebView 內建 ⌘R reload |
| 結束 | ⌘Q / Ctrl+Q | `keys.CmdOrCtrl("q")` |
| ~~切到 Workspace~~ | ~~⌘Shift+W~~ | **已移除**：與 macOS 「關閉所有視窗」衝突，且 ⌘4 已有相同功能 |
**生產模式必須 disable WebView 預設的 ⌘R reload**（`wails.json` 或 `app.go` Assets middleware 攔截）。

309
local-tool/.autoflow/04-architecture/packaging.md Normal file
View File

@ -0,0 +1,309 @@
# Packaging — visionA-local
> macOS .dmg、Windows Inno Setup .exe、Linux AppImage 的具體打包流程。
> **無任何程式碼簽章**（使用者決策 Q2 = C）。
---
## 1. 總覽：三平台產出物
| 平台 | 格式 | 簽章 | 大小（預估） |
|------|------|------|------------|
| macOS 14/15 x86_64 | `visiona-local-v{ver}-macos-x64.dmg` 內含 `.app` | ad-hoc（`codesign -s -`） | ~195MB |
| Windows 10/11 x64 | `visiona-local-v{ver}-windows-x64.exe`（Inno Setup installer） | **無** | ~205MB |
| Ubuntu 22.04/24.04 x64 | `visiona-local-v{ver}-linux-x64.AppImage` | 無 | ~210MB |
## 2. macOS：.app + .dmg
### 2.1 建置流程
```bash
# 1. 準備 payload
make payload-macos # 把 python + wheels + ffmpeg + models 塞到 visiona-local/payload/
# 2. Wails 編譯
cd visiona-local && wails build -platform darwin/amd64 -clean
# 3. ad-hoc sign
codesign --force --deep --sign - build/bin/visiona-local.app
# 4. 驗證簽章
codesign -dv --verbose=4 build/bin/visiona-local.app
# 5. 打包成 dmg
dmgbuild -s dmg-config.py "visionA-local" dist/visiona-local-v${VERSION}-macos-x64.dmg # 顯示標題沿用產品名 visionA-local
```
### 2.2 `wails.json` 關鍵設定
```json
{
"name": "visiona-local",
"outputfilename": "visiona-local",
"frontend:install": "echo skip",
"frontend:build": "echo skip",
"info": {
"companyName": "Innovedus",
"productName": "visionA-local",
"productVersion": "1.0.0",
"copyright": "© 2026 Innovedus",
"comments": "Kneron KL520/KL720 本地開發工具"
},
"nsisType": "multiple",
"appid": "com.innovedus.visiona-local"
}
```
### 2.3 Info.plist 關鍵項
- `CFBundleIdentifier = com.innovedus.visiona-local`
- `CFBundleExecutable = visiona-local`（binary 全小寫；`CFBundleName` / `CFBundleDisplayName` 仍為 `visionA-local` 作為顯示名）
- `NSHighResolutionCapable = true`
- `LSMinimumSystemVersion = 14.0`
- `NSCameraUsageDescription = visionA-local 需要存取攝影機以執行 AI 推論展示`
- `NSAppleEventsUsageDescription = visionA-local 需要使用 AppleScript 開啟瀏覽器`
- **不需要** `NSAppTransportSecurity` 因為只用 localhost
### 2.4 dmgbuild 設定檔（`dmg-config.py`）
```python
# dmg-config.py
format = 'UDBZ' # bzip2 壓縮，壓縮率好
size = '400M'
files = ['build/bin/visiona-local.app']
symlinks = {'Applications': '/Applications'}
badge_icon = 'build/icon.icns'
icon_locations = {
'visiona-local.app': (150, 200),
'Applications': (450, 200),
}
window_rect = ((200, 200), (600, 400))
background = 'build/dmg-background.png'
```
### 2.5 首次啟動：Gatekeeper workaround
**因為沒有 notarization，使用者第一次打開 .app 會跳警告：**
> "visionA-local" can't be opened because it is from an unidentified developer.
**解法（必須寫進 README 與首次啟動說明頁）：**
1. 在 Finder 中對 `visiona-local.app` **按右鍵 → 開啟**
2. 在警告對話框按「開啟」
3. 之後可以正常雙擊開啟
或命令列：`xattr -d com.apple.quarantine /Applications/visiona-local.app`
## 3. Windows：Inno Setup .exe
### 3.1 為何選 Inno Setup 而不是 NSIS / MSI
- **UI 現代化**：Inno Setup 6 的預設樣式比 NSIS 好看
- **腳本簡單**：Pascal-like DSL，比 NSIS 的 MakeNSIS 好維護
- **安裝 driver 方便**：內建 `DriverInstall` 流程支援 pnputil
- **不用 MSI**：MSI 需要 WiX 工具鏈與 signing 才順，我們不簽章，Inno Setup 更簡單
### 3.2 建置流程
```bash
# 1. 準備 payload
make payload-windows
# 2. Wails 編譯
cd visiona-local && wails build -platform windows/amd64 -clean
# 3. 執行 Inno Setup Compiler
iscc visiona-local-installer.iss
# 產物：dist/visiona-local-v{ver}-windows-x64.exe
```
### 3.3 `visiona-local-installer.iss` 骨架
```pascal
[Setup]
AppId={{A7F3E891-4B2C-4D5E-9F1A-8B3C2D1E0F9A}
AppName=visionA-local
AppVersion=1.0.0
AppPublisher=Innovedus
AppPublisherURL=https://innovedus.com
DefaultDirName={autopf}\visiona-local
DefaultGroupName=visiona-local
OutputDir=..\dist
OutputBaseFilename=visiona-local-v1.0.0-windows-x64
SetupIconFile=assets\icon.ico
Compression=lzma2/ultra64
SolidCompression=yes
WizardStyle=modern
PrivilegesRequired=admin
ArchitecturesInstallIn64BitMode=x64
MinVersion=10.0.17763
[Files]
Source: "visiona-local\build\bin\visiona-local.exe"; DestDir: "{app}"; Flags: ignoreversion
Source: "visiona-local\payload\*"; DestDir: "{app}\payload"; Flags: ignoreversion recursesubdirs
[Icons]
Name: "{group}\visionA-local"; Filename: "{app}\visiona-local.exe"
Name: "{autodesktop}\visionA-local"; Filename: "{app}\visiona-local.exe"; Tasks: desktopicon
[Tasks]
Name: "desktopicon"; Description: "建立桌面捷徑"; GroupDescription: "附加選項："
[Run]
; 安裝 WinUSB driver
Filename: "{sys}\pnputil.exe"; \
Parameters: "/add-driver ""{app}\payload\drivers\kneron_winusb.inf"" /install"; \
StatusMsg: "正在安裝 Kneron USB driver..."; \
Flags: runhidden waituntilterminated
; 啟動 app
Filename: "{app}\visiona-local.exe"; \
Description: "啟動 visionA-local"; \
Flags: postinstall nowait skipifsilent
[UninstallDelete]
Type: filesandordirs; Name: "{localappdata}\visiona-local"
```
### 3.4 SmartScreen 警告處理
**沒有 Authenticode 簽章，Windows SmartScreen 會擋：**
> Windows protected your PC — Microsoft Defender SmartScreen prevented an unrecognized app from starting.
**解法（寫進安裝說明）：**
1. 點「更多資訊」
2. 點「仍要執行」
使用者第一次下載後會遇到這個警告，執行過一次之後 Windows 會記住。這是可接受的摩擦成本（使用者決策）。
## 4. Linux：AppImage
### 4.1 為何選 AppImage 而不是 .deb / snap / flatpak
- **單檔可攜**：一個 `.AppImage` 檔案，雙擊即跑，不需安裝
- **跨發行版**：只要 glibc >= 2.28（Ubuntu 18.04+）就能跑
- **不需 sudo**（正常情境下）
- **符合「像一般 app」的體驗**
`.deb` 需要 apt install + sudo；snap / flatpak 需要發到 store 或有 runtime 依賴，不適合內部工具分發。
### 4.2 建置流程
```bash
# 1. 準備 payload
make payload-linux
# 2. Wails 編譯
cd visiona-local && wails build -platform linux/amd64 -clean
# 3. 建立 AppDir
rm -rf AppDir && mkdir -p AppDir/usr/bin AppDir/usr/lib
cp build/bin/visiona-local AppDir/usr/bin/
cp -r payload AppDir/usr/bin/payload
# 4. 複製 libusb 到 AppDir（避免依賴系統 libusb）
cp /usr/lib/x86_64-linux-gnu/libusb-1.0.so.0 AppDir/usr/lib/
# 5. 寫入 .desktop 與 AppRun
cat > AppDir/visiona-local.desktop <<EOF
[Desktop Entry]
Type=Application
Name=visionA-local
Exec=visiona-local
Icon=visiona-local
Categories=Development;
EOF
cat > AppDir/AppRun <<'EOF'
#!/bin/bash
HERE="$(dirname "$(readlink -f "$0")")"
export LD_LIBRARY_PATH="$HERE/usr/lib:${LD_LIBRARY_PATH}"
exec "$HERE/usr/bin/visiona-local" "$@"
EOF
chmod +x AppDir/AppRun
cp assets/icon.png AppDir/visiona-local.png
# 6. 用 appimagetool 打包
ARCH=x86_64 appimagetool AppDir dist/visiona-local-v${VERSION}-linux-x64.AppImage
```
### 4.3 首次執行需要的權限
因為要寫入 `/etc/udev/rules.d/99-kneron.rules` 讓非 root 使用者存取 USB：
**首次執行時跳 pkexec 提權對話框（GNOME 預設可用），執行：**
```bash
pkexec cp ~/.local/share/visiona-local/scripts/99-kneron.rules /etc/udev/rules.d/
pkexec udevadm control --reload-rules
pkexec udevadm trigger
```
使用者拒絕或系統沒有 pkexec（例如 minimal server 安裝）：顯示錯誤訊息提示手動執行 `sudo ./install-udev.sh`，內附的 script 由我們提供。
### 4.4 AppImage 的已知限制
- **沒有 .desktop integration**：使用者要自己放到 `~/Applications/` 或用 `appimaged`
- **第一次解壓慢**：AppImage 是 squashfs，第一次啟動會把內容 mount 到 `/tmp/.mount_*/`
## 5. 圖示與品牌資產
### 5.1 檔案清單
| 平台 | 檔案 | 尺寸 |
|------|------|------|
| macOS | `visiona-local.icns` | 512×512 @1x + @2x |
| Windows | `visiona-local.ico` | 16, 32, 48, 64, 128, 256 |
| Linux | `visiona-local.png` | 256×256 |
> Tray 圖示已移除（第三輪使用者決策 Q-A=A3：砍 tray）。
### 5.2 來源
使用者決策 Q14：**先沿用 edge-ai-platform 既有視覺（字母 E）**，品牌換名但圖示暫時不動。
從 `edge-ai-platform/installer/frontend/src-tauri/icons/` 直接複製（`server/tray/assets/` 不再使用）。
## 6. 首次啟動警告匯總（使用者要看到的文件）
必須在以下位置寫清楚：
1. `README.md`（GitHub / Gitea 發布頁）
2. 下載頁（Gitea Release 描述）
3. 首次啟動歡迎頁（如果有的話，可跳過）
**內容模板：**
```markdown
## 首次啟動提示
visionA-local 是內部工具，**沒有 Apple / Microsoft 的程式碼簽章**。
首次執行時作業系統可能會顯示警告，這是正常的。
### macOS
在 Finder 中找到 `visiona-local.app`，**按右鍵 → 開啟**，在彈出對話框中選「開啟」。
之後可以正常雙擊開啟。
### Windows
執行安裝檔時若看到 "Windows 已保護您的電腦" 警告：
點「更多資訊」→「仍要執行」。
### Linux
AppImage 預設沒有執行權限：
```
chmod +x visiona-local-v1.0.0-linux-x64.AppImage
./visiona-local-v1.0.0-linux-x64.AppImage
```
```
## 7. 發布流程
| 步驟 | 負責 | 工具 |
|------|------|------|
| 1. Tag release | 開發者 | `git tag v1.0.0 && git push --tags` |
| 2. CI build macOS | GitHub Actions / local | `make installer-macos` |
| 3. CI build Windows | GitHub Actions / local | `make installer-windows` |
| 4. CI build Linux | GitHub Actions / Docker | `make installer-linux` |
| 5. 上傳到 Gitea Release | 開發者 | `gh release create` 或手動 |
| 6. 更新 `latest.json`（如果未來做 auto-update） | - | 目前不做 |
**不建置 universal / multi-arch**，只有 x64。

165
local-tool/.autoflow/04-architecture/plan-b-online-download.md Normal file
View File

@ -0,0 +1,165 @@
# Plan B：預置模型線上下載（R9 Contingency）
> 這份文件是 **R9 .nef re-distribution 授權** 的 contingency 方案。
> 使用時機：發佈前 PM 與 Kneron 確認結果為「不允許將 .nef 內嵌於另一產品 re-distribution」。
> **目前不啟用**，只在 R9 被否決時才觸發；本文件不影響 M1–M6 開發計畫。
---
## 1. 觸發條件
以下任一條件成立即觸發 Plan B：
- M6（首次公開 release 前）PM 或使用者從 Kneron 官方 / OEM 窗口收到「不允許 re-distribute 預置 .nef」的書面回覆
- 發佈流程中任何時點發現授權問題
- Innovedus 法務自行判斷風險過高要求下架內嵌模型
**不觸發的情況**：任何「尚未確認」的狀態（與現行第四輪 R4-1 決策一致，維持內嵌不主動詢問）。
## 2. 目標
用最小改動把預置 .nef 從「內嵌打包」改為「首次啟動線上下載」，**保留原本所有功能與使用體驗，僅犧牲「完全離線」承諾**。
**不重做**：
- 使用者自訂上傳的 .nef（`data/custom-models/`）繼續走既有上傳流程
- Python runtime / KneronPLUS SDK / ffmpeg / yt-dlp 繼續內嵌（授權可重發布）
**改動範圍**：只有預置 .nef（`server/data/nef/`，~73MB）
## 3. 架構修改
### 3.1 移除 payload 中的 .nef
```diff
visiona-local/payload/
├── bin/
├── python/
├── scripts/
- └── data/
- ├── models.json
- └── nef/
- ├── kl520/*.nef
- └── kl720/*.nef
+ └── data/
+ └── models.json ← 保留 metadata，nef 目錄留空
```
安裝檔大小降為 ~225MB（macOS）/ ~235MB（Windows）/ ~240MB（Linux）。
### 3.2 新增下載邏輯
**位置**：`visiona-local/model_download.go`（新寫）
**觸發點**：`.installed` 寫入後、首次 `launchServer()` 之前，插入一個「模型下載」精靈步驟。
```go
// 流程
func (inst *Installer) stepDownloadPresetModels(config InstallConfig) error {
// 1. 讀 models.json → 取得清單
manifest := loadBundledManifest()
// 2. 檢查本地 data/nef/ 下哪些已存在
missing := diffMissing(manifest, config.InstallDir)
// 3. 全數存在 → 跳過
if len(missing) == 0 {
return nil
}
// 4. 顯示下載進度 UI（Wails app 內建）
inst.showProgress("下載預置模型...", len(missing))
// 5. 逐檔下載 + 驗證 sha256
for _, m := range missing {
if err := downloadWithResume(m.URL, m.LocalPath, m.SHA256); err != nil {
return fmt.Errorf("模型下載失敗：%w", err)
}
inst.incrementProgress()
}
return nil
}
```
### 3.3 manifest 格式
`payload/data/models.json`（擴充原有格式）：
```json
{
"version": "1.0.0",
"base_url": "https://releases.innovedus.com/visiona-local/models/v1.0.0/",
"models": [
{
"id": "kl520-classification-mobilenetv2",
"device": "kl520",
"task": "classification",
"file": "kl520/classification_mobilenetv2.nef",
"size_bytes": 6234521,
"sha256": "abc123...",
"url_path": "kl520/classification_mobilenetv2.nef"
},
...
]
}
```
**sha256 欄位必填**：防止下載中間被竄改或損毀。
### 3.4 下載來源
三選一（M6 前決定）：
| 選項 | 優點 | 缺點 |
|------|------|------|
| A. Innovedus 內部 Gitea Releases | 管理簡單、已有通路（若 R11 通過） | 對外需要 VPN |
| B. AWS S3 + CloudFront | 速度快、全球 CDN | 需管 IAM / Bucket |
| C. GitHub Releases（若 repo 公開） | 免費 + 自帶 CDN | 需公開 repo |
**預設建議 B（S3 + CloudFront）**，與 R11 發佈通路解耦（安裝檔仍可放 Gitea，模型走 S3）。
### 3.5 斷線處理
- **下載中斷** → `downloadWithResume` 支援 HTTP Range，下次啟動繼續
- **全部下載失敗** → 不擋安裝完成，但主 UI 顯示 warning：「預置模型未下載，部分示範功能無法使用」；使用者可在 Settings > 模型 手動點「重新下載預置模型」
- **完全離線環境** → 提供離線包下載頁（使用者自己 scp .nef 到 `data/nef/`），首次啟動偵測到檔案存在則跳過下載
## 4. 安全與驗證
- sha256 驗證每個下載檔
- HTTPS only（不接受 HTTP）
- 下載失敗自動 retry 3 次，指數退避（2s / 5s / 10s）
- 下載時顯示進度條（總大小 ~73MB，10Mbps 連線約 60 秒）
## 5. 使用者體驗影響
| 項目 | 原方案（內嵌） | Plan B（線上下載） |
|------|--------------|------------------|
| 完全離線 | ✅ | ❌（首次需要網路） |
| 首次安裝時間 | 3–5 分鐘 | 3–5 分鐘 + 下載時間（約 60–180 秒） |
| 後續啟動 | 同 | 同（一次下載後本地使用） |
| 使用者須知 | 無 | 首次啟動需要網路、之後離線可用 |
## 6. 估工
| 任務 | 規模 |
|------|------|
| model_download.go 新寫 | M（~300 行） |
| 安裝精靈新增「下載模型」步驟 | S |
| manifest 格式與 CDN 結構 | S |
| 離線包下載頁與文件 | S |
| 測試三平台 + 斷線恢復 | M |
| 總計 | **~1 週工程師時間** |
## 7. 觸發後的行動清單
- [ ] 確認 Kneron 回覆書面紀錄
- [ ] 決定下載來源（A/B/C）並建置
- [ ] 實作 `model_download.go`
- [ ] 修改安裝精靈 UI
- [ ] 修改 payload 打包腳本移除 nef
- [ ] 建立離線包下載頁
- [ ] 更新 PRD NFR「完全離線」章節加上註記
- [ ] 更新 packaging 文件與安裝檔大小估算
- [ ] 三平台測試
- [ ] 法務複核 About 頁模型授權聲明

203
local-tool/.autoflow/04-architecture/removed-code.md Normal file
View File

@ -0,0 +1,203 @@
# Removed Code — visionA-local
> 要從 edge-ai-platform 砍掉、不搬進 local_tool 的目錄 / 檔案 / import 清單。
---
## 1. 整包刪除的目錄
| 目錄 | 原因 |
|------|-----|
| `server/internal/cluster/` | 使用者決策：砍掉 cluster |
| `server/internal/tunnel/` | 使用者決策：砍掉 relay / tunnel |
| `server/internal/update/` | 使用者決策 Q6：不做 auto-update |
| `server/internal/flash/` | 使用者決策 Q9：砍掉韌體燒錄 |
| `server/cmd/relay-server/` | 不需要 relay server |
| `server/pkg/hwid/` | 只被 relay token 生成用 |
| `server/tray/` | 使用者決策 Q-A=A3：砍掉 tray，省跨平台圖資產與 Wails tray 踩坑 |
| `server/scripts/firmware/` | flash 已砍 |
| `docker/` | 不需要 deploy |
| `scripts/deploy-aws.sh` | 不需要 deploy |
| `scripts/deploy-ec2.sh` | 同上 |
| `scripts/deploy-*.sh` | 同上 |
| `docs/` | 舊文件不 relevant，重新寫 |
| `installer/frontend/` 中 cluster / relay 相關畫面 | Wails installer 的 UI 不需要 cluster 設定 |
## 2. 檔案層級刪除
| 檔案 | 原因 |
|------|-----|
| `server/scripts/update_kl720_firmware.py` | flash 已砍 |
| `server/internal/api/handlers/cluster_handler.go` | cluster 已砍 |
| `server/internal/api/handlers/flash_handler.go`（若獨立） | flash 已砍 |
| `server/internal/api/ws/flash_progress.go` | flash 已砍 |
| `server/internal/api/ws/cluster_*.go` | cluster 已砍 |
| `frontend/src/app/clusters/` | cluster 頁面 |
| `frontend/src/app/workspace/cluster/` | 同上 |
| `frontend/src/components/cluster/` | cluster 元件 |
| `frontend/src/lib/api/clusters.ts` | API client |
| `frontend/src/components/relay-token-sync.tsx` | relay 專用 |
| `frontend/src/lib/api/update.ts`（若有） | update 已砍 |
## 3. `server/main.go` 要刪除的 import
```go
// ❌ 刪除這些 import：
"edge-ai-platform/internal/cluster"
"edge-ai-platform/internal/flash"
"edge-ai-platform/internal/tunnel"
"edge-ai-platform/pkg/hwid"
```
## 4. `server/main.go` 要刪除的變數 / 邏輯
```go
// ❌ 刪除這些：
var tunnelClient *tunnel.Client
clusterMgr := cluster.NewManager(deviceMgr)
flashSvc := flash.NewService(deviceMgr, modelRepo)
// 刪除整段 relay token 生成：
relayToken := cfg.RelayToken
if cfg.RelayURL != "" && relayToken == "" {
relayToken = hwid.Generate()
...
}
// 刪除 tunnel 啟動：
if cfg.RelayURL != "" {
tunnelClient = tunnel.NewClient(...)
tunnelClient.Start()
...
if relayHTTP := relayWebURL(...); ...
}
// 刪除 shutdownFn 裡的 tunnelClient.Stop()
// 刪除 relayWebURL 整個函式
// 刪除 openBrowser 整個函式（不需要，WebView 由 Wails 管）
// systemHandler 的 giteaURL 參數移除：
systemHandler := handlers.NewSystemHandler(Version, BuildTime, restartFn) // 移除 cfg.GiteaURL
// router.NewRouter 的呼叫：
r := api.NewRouter(
modelRepo, modelStore, deviceMgr, cameraMgr,
// ❌ clusterMgr 移除
// ❌ flashSvc 移除
inferenceSvc, wsHub, staticFS, logBroadcaster, systemHandler,
// ❌ relayToken 移除
)
```
## 5. `server/internal/config/config.go` 要刪除的欄位
見 [`code-reuse-plan.md`](./code-reuse-plan.md) §3.3 的完整改寫版。精簡列表：
```go
// ❌ 刪除：
RelayURL string
RelayToken string
GUIMode bool
GiteaURL string
// ❌ 刪除對應的 flag.StringVar / flag.BoolVar 呼叫
```
## 6. `server/internal/api/router.go` 要刪除的內容
見 [`api-endpoints.md`](./api-endpoints.md) §4 的新版完整程式碼。精簡列表：
- `clusterMgr`, `flashSvc`, `relayToken` 三個參數
- `clusterHandler` 初始化
- 所有 `/api/clusters/*` routes
- `/auth/token` endpoint + OPTIONS
- 所有 `/ws/clusters/*` routes
- `/ws/devices/:id/flash-progress`
## 7. `frontend/` 要清理的內容
**M1 階段就要清乾淨**（使用者決策 Q-C=C2：不接受「M1 先不清前端」的先前建議；必須一次到位，UI 必須乾淨）：
### 7.1 刪除的目錄
- `src/app/clusters/`
- `src/app/workspace/cluster/`（若存在）
- `src/components/cluster/`
### 7.2 刪除的檔案
- `src/components/relay-token-sync.tsx`
- `src/lib/api/clusters.ts`
- `src/lib/api/tunnel.ts`（若有）
- `src/lib/api/update.ts`（若有）
- `src/stores/cluster-store.ts`（若有）
### 7.3 修改的檔案
- `src/components/layout/sidebar.tsx` — 移除 "Clusters" 導航項
- `src/app/page.tsx`（Dashboard） — 移除 cluster stat card / cluster activity
- `src/app/settings/page.tsx` — 移除 relay 模式切換、cluster 設定區塊
- 各 `.tsx` 中任何對 `clusterStore` / `clusters` API 的 import 與使用
## 8. `installer/app.go`（改寫為 `visiona-local/app.go`）要刪除的內容
```go
// ❌ 刪除的欄位與函式：
- InstallConfig 中的 relay / dashboard 相關欄位
- GenerateToken（沒有 token 需求）
- GetDashboardURL 中的 relay 邏輯
- LaunchServer 的 relay flag 組裝
- runInstall 中跟 relay 有關的 step
// ✅ 保留但改寫：
- stepInstallFfmpeg → 改為從 payload 解壓 bundled ffmpeg，不依賴系統 PATH
- stepInstallUSBDriver → 只在 Windows 執行
- stepSetupPython → 分裂為 bundled / system 兩條路徑
```
## 9. `Makefile` 要刪除的 target
```makefile
# ❌ 刪除：
build-relay
deploy-frontend
deploy-frontend-setup
deploy-ec2
# 刪除 PHONY 列表中對應的項目
```
## 10. `go.mod` 要移除的依賴
執行 `go mod tidy` 後自動移除：
- 原本為 cluster / relay / tunnel / flash / update 引入的 library
- 若 `hwid` 引用了 `machineid` 類的套件，也會自動移除
不需要手動編輯 go.mod。
## 11. 清理後的 sanity check
完成上述刪除後，執行：
```bash
# Go 編譯測試
cd server && go build ./... && go vet ./...
# 前端編譯測試
cd frontend && pnpm build
# grep 確認沒有殘留的 import
grep -rn "cluster" server/ --include="*.go" | grep -v "_test.go"
grep -rn "tunnel" server/ --include="*.go"
grep -rn "relay" server/ --include="*.go"
grep -rn "hwid" server/ --include="*.go"
grep -rn "flash" server/ --include="*.go" # 注意：可能還有「flash 燈號」等無關字眼
grep -rn "GiteaURL" server/ --include="*.go"
# 應該全部沒有匹配（或只剩無關字眼）
```
## 12. 清理階段的風險
- **隱性耦合**：某些 handler 可能透過 router 參數傳遞 `clusterMgr`，移除後要確認所有 call site
- **前端 build 炸掉**：M1 就要清乾淨（Q-C=C2），必須仔細處理 sidebar、store imports、cross-component references，建議先 grep `cluster|relay|tunnel` 全掃一次再動手
- **test 依賴**：`api_e2e_test.go` 裡可能有 cluster / flash / auth test case，要一併刪
- **i18n 殘留**：被刪除的功能對應的 i18n key 也要清（不影響功能但佔空間）

225
local-tool/.autoflow/04-architecture/risks-and-mitigations.md Normal file
View File

@ -0,0 +1,225 @@
# Risks & Mitigations — visionA-local
> 重大技術風險總覽與緩解計畫。
> 優先級：P0 = 會擋住發布、P1 = 嚴重影響使用者體驗、P2 = 可接受但需監控
---
## R1：KneronPLUS Linux wheel 的 glibc 相容性
- **優先級：P0**
- **可能性：高**
- **影響：高**
- **描述：** KneronPLUS-3.1.2 Linux wheel 內的 `.so` 綁定特定 glibc 版本（manylinux2014 = glibc 2.17+）。Ubuntu 22.04 是 glibc 2.35、Ubuntu 24.04 是 glibc 2.39，理論上沒問題，但 `.so` 還依賴 libusb-1.0 的 ABI，若系統 libusb 版本太舊或太新都可能炸。
- **緩解：**
1. AppImage 內帶 `libusb-1.0.so.0`，透過 `LD_LIBRARY_PATH` 優先載入，避免依賴系統 libusb
2. M1 階段就在 Ubuntu 22.04 + 24.04 實測，若不過則降級為只支援其中一版
3. 提供明確錯誤訊息：「你的 Linux 發行版 libusb 版本不相容，請安裝 libusb-1.0.0」
- **驗證時機：** M5 Linux build
---
## R2：Windows WinUSB driver 安裝需要 UAC，使用者拒絕就無法連裝置
- **優先級：P0**
- **可能性：中**
- **影響：高**
- **描述：** Inno Setup 跑 `pnputil /add-driver` 需要 admin 權限，使用者拒絕 UAC 就裝不起來。安裝後第一次跑 app 再跳 UAC 的體驗也很差。
- **緩解：**
1. Inno Setup 設定 `PrivilegesRequired=admin`，讓使用者在啟動安裝檔時就先提權一次（比跑到一半才跳好）
2. 若使用者拒絕 → 顯示明確訊息：「driver 未安裝，app 仍可跑 Mock 模式，但無法連真實 Kneron 裝置」
3. 提供「稍後手動安裝」的備援 script（`tools/install-winusb-driver.bat`）
- **驗證時機：** M4 Windows build
---
## R3：macOS 沒有簽章，Gatekeeper 會擋
- **優先級：P1**
- **可能性：確定會發生**
- **影響：中（體驗差但可 workaround）**
- **描述：** 沒有 Developer ID notarization，首次開啟 `.app` 會跳「無法驗證開發者」的警告。需要使用者右鍵 → 開啟。
- **緩解：**
1. README 與下載頁寫清楚 workaround 步驟
2. `.dmg` 內容加入一張 `首次開啟說明.png` 圖片
3. 提供一行 terminal 命令的替代方案：`xattr -d com.apple.quarantine /Applications/visionA-local.app`
- **不做的事：** 不購買 Apple Developer 帳號（使用者決策 Q2 = C）
- **風險接受理由：** 目標使用者是內部工程師 + 技術型客戶，可接受一次性摩擦
---
## R4：python-build-standalone 可能被防毒軟體誤殺
- **優先級：P1**
- **可能性：中**
- **影響：高**
- **描述：** Windows 環境尤其常見 — 防毒軟體（特別是企業版 Symantec / Trend Micro）對內嵌 Python interpreter 有時會誤判為惡意軟體，直接刪除 `python.exe` 或整個資料夾。
- **緩解：**
1. **策略 A + B 雙保險**：bundled 被刪時自動 fallback 到 system python（使用者決策 Q1 保留 B 就是為了這個）
2. 安裝完成後驗證 `python --version` 能跑，失敗立刻 fallback
3. 提供 `--python-mode=system` 強制參數供 IT 人員 troubleshoot
4. 文件說明：若公司防毒擋住，建議白名單 `visiona-local` 安裝目錄
- **監控：** 若 M4 Windows 測試頻繁遇到此問題，考慮用 pyinstaller 替代 python-build-standalone（pyinstaller 更容易被防毒接受）
---
## R5：Windows SmartScreen 擋安裝檔下載
- **優先級：P1**
- **可能性：確定會發生**
- **影響：中**
- **描述：** 沒有 Authenticode 簽章的 installer，Windows SmartScreen 會跳「Windows 已保護您的電腦」並預設把「執行」按鈕隱藏在「更多資訊」後面。新使用者看到可能以為是病毒。
- **緩解：**
1. README 截圖示範「更多資訊 → 仍要執行」的點擊路徑
2. 下載頁顯眼標註「首次下載會看到 SmartScreen 警告，這是正常現象」
3. 盡量從固定 URL 下載（同一個 URL 被 SmartScreen 累積 reputation，久了會變成 trusted，雖然慢）
- **不做的事：** 不購買 EV Code Signing 憑證（使用者決策）
---
## R6：不做 auto-update → 後續版本推送困難
- **優先級：P2**
- **可能性：確定**
- **影響：中**
- **描述：** 使用者決策 Q6 = 不做 auto-update。這代表未來每次升級都要使用者手動下載新的 installer，而且要再次面對 Gatekeeper / SmartScreen 警告。對「內部工具」可接受，但若使用者多到一定規模，升級擴散會很慢。
- **緩解：**
1. 在 About 頁顯示當前版本 + 一個「開啟下載頁」按鈕（連到 Gitea Release），不自動檢查
2. 內部溝通管道（Slack / Email）負責通知新版本
3. 未來若需要時，可改為「手動檢查更新」（按鈕觸發，不自動），比 auto-update 輕量
- **監控：** 使用者回饋是否抱怨升級繁瑣；若變成痛點，優先做「手動檢查更新」功能
---
## R7：Apple Silicon 使用者用 Rosetta 跑 x86_64 版 → 效能 / 穩定性風險
- **優先級：P2**
- **可能性：低**（使用者決策是先只做 x86_64）
- **影響：中**
- **描述：** 使用者決策 Q4 = 三平台都只做 x86_64。對使用 Intel Mac 的使用者沒問題，但 Apple Silicon（M1/M2/M3）要走 Rosetta。風險點：
- Rosetta 翻譯 Python C extension 可能有邊界情況
- KneronPLUS `.dylib` 是 x86_64-only，必須走 Rosetta，但 pyusb / libusb 的 USB 訊號路徑在 Rosetta 下未驗證過
- 首次啟動會跳 Rosetta 安裝提示（如果使用者還沒裝）
- **緩解：**
1. 明確聲明：「本版僅支援 x86_64，Apple Silicon 需透過 Rosetta 2 執行」
2. 第一次啟動偵測 CPU 架構，若是 arm64 → 顯示 Rosetta 提示
3. 若 M1 階段測試 Rosetta 路徑不穩，評估是否加做 arm64 版本（將是 scope creep）
- **未來工作：** 若使用者多為 Apple Silicon → 第二版加 arm64 build（需要 KneronPLUS arm64 wheel，目前沒有）
---
## R8：python-build-standalone 下載 URL 可能失效
- **優先級：P2**
- **可能性：低**
- **影響：中**
- **描述：** `make vendor-sync` 依賴 astral-sh/python-build-standalone 的 GitHub Release，若他們改變命名慣例或刪除舊 release，build 會中斷。
- **緩解：**
1. `vendor/` 目錄用 git-lfs 或存到內部 artifact storage，一旦下載成功就 cache 住
2. 用固定版本號（pin `20250317`），不用 `latest`
3. 備援：fallback 到 https://www.python.org/ftp/python/ 官方 tarball（雖然不是 standalone，但至少保底）
---
## R9：預置 .nef 模型的 re-distribution 授權
- **優先級：P1**（第三輪 Q-B=B4 + 第四輪 R4-1 延續：開發階段先假設可內嵌，**使用者決定暫不主動詢問 Kneron 法務**，發佈前的 gate 維持必須 check-off，屬於 release blocker）
- **可能性：中**
- **影響：高**（若 Kneron 不允許 re-distribution，會破壞「完全離線」承諾，需改為首次啟動線上下載）
- **描述：** Kneron 預置模型是 Kneron 官方提供，但「打包在另一個產品裡再發布」的授權條款未確認。可能限制 re-distribution。
- **第三輪決策（Q-B=B4）+ 第四輪決策（R4-1）：**
- **開發階段**：先假設可以重新散布，繼續把預置 `.nef` 內嵌進 payload 正常開發
- **現階段不主動詢問 Kneron**（第四輪 R4-1 使用者決定）：避免過早引發授權討論影響進度
- **發佈前（M6 或首次公開 release 前）**：**必須**由 PM / 使用者向 Kneron 官方（或依循 Innovedus 既有 OEM 合約）正式確認授權條款；若屆時仍無法確認，觸發 Plan B
- **此項為 P1 release blocker**：未確認前不得對外發佈
- **Plan B 對應文件**：見 [`plan-b-online-download.md`](./plan-b-online-download.md)
- **緩解：**
1. PM Agent 在 PRD / launch-checklist 追蹤項中列為發佈前必須 check-off 的項目
2. Architect 在 `packaging.md` 的 bundle 清單中為預置模型加註「授權待 Kneron 確認」
3. 若最終不允許 → Plan B：改為首次啟動線上下載（從 Innovedus 內部 Gitea / CDN），打破「完全離線」承諾，需再與使用者確認可接受度
4. About 頁加上「模型版權：Kneron Inc.」聲明（不論授權結果都要做）
- **追蹤項（P1 release blocker）：**
- [ ] PM 取得 Kneron 預置模型 re-distribution 書面授權或回信
- [ ] 若無法取得 → 觸發 Plan B，重新評估 M6 範圍
---
## R10：ffmpeg LGPL 合規要求
- **優先級：P2**
- **可能性：確定要處理**
- **影響：低（文件工作）**
- **描述：** LGPL 要求：
1. 聲明使用 ffmpeg 與版本
2. 提供 LGPL 全文
3. 提供取得 source 的方式
4. （靜態連結時）提供 relink 所需的 object files（static build 才需要）
- **緩解：**
1. 我們是動態呼叫 ffmpeg binary（不是 link），這個寬鬆很多
2. About 頁加入聲明 + 連結到 ffmpeg.org 與 LGPL 全文
3. 產品 Repo 的 `THIRD_PARTY_LICENSES.md` 列出所有第三方授權
- **驗證：** 法務 review About 頁與 license 文件（使用者決策：不優先，內部工具先發再說）
---
---
## R11：發佈通路基礎設施未確認（內部 Gitea Releases / GitHub Releases）
- **優先級：P2**（追蹤項，發佈前必須解決）
- **可能性：確定需要處理**
- **影響：中**（若無對外發佈通路，DevOps 需臨時建置或改用其他方式如 S3 + 自製下載頁）
- **描述：** PRD `release-strategy` 與 `packaging.md §7` 都假設有「內部 Gitea Release」或「GitHub Release」作為安裝檔分發通路，但 progress.md 的「未解決問題」明確列出尚未確認 Innovedus 內部有此基礎設施。
- **緩解：**
1. PM / 使用者在 M5 前確認 Innovedus 是否已有 Gitea Release 或 GitHub Release（public / private repo 皆可）的發佈通路
2. 若無 → DevOps Agent 評估改走 S3 靜態站 + 自製 `latest.json` 下載頁，或直接內部檔案伺服器
3. launch-checklist 列為發佈前必確認項
- **與 R9 的關係：** 若 R9 不允許內嵌，Plan B 的線上下載也需要這個通路，兩者共用解決方案。
---
## R12：CI runner 三平台是否齊備
- **優先級：P2**
- **可能性：確定需要處理**
- **影響：中**（若缺 runner，build 只能在開發者機器手動跑，發佈節奏與一致性差）
- **描述：** `build-pipeline.md` 假設 CI 有 macOS、Windows、Linux 三平台 runner 可分別跑 `make installer-macos/windows/linux`。實際上 Innovedus 內部 CI（GitHub Actions / Gitea Actions / Jenkins）是否已有這三種 runner 尚未確認。
- **緩解：**
1. M4（Windows）與 M5（Linux）前確認對應 runner 可用
2. 若缺 runner → 短期改為開發者本機手動跑，長期補 runner
3. macOS runner 最棘手（GitHub Actions macOS 有用量上限；自架需要實體 Mac）→ 可能要採購或借用
4. launch-checklist 列為發佈前必確認項
---
## 風險總表
| # | 風險 | P | 可能性 | 影響 | 緩解狀態 |
|---|------|---|-------|------|---------|
| R1 | Linux wheel glibc 相容性 | P0 | 高 | 高 | 有方案，需 M5 驗證 |
| R2 | Windows WinUSB UAC 被拒絕 | P0 | 中 | 高 | 有方案，需 M4 驗證 |
| R3 | macOS 無簽章 Gatekeeper | P1 | 確定 | 中 | 接受，有 workaround |
| R4 | python-build-standalone 被防毒誤殺 | P1 | 中 | 高 | 雙策略 fallback |
| R5 | Windows SmartScreen 警告 | P1 | 確定 | 中 | 接受，文件說明 |
| R6 | 不做 auto-update 擴散慢 | P2 | 確定 | 中 | 接受 |
| R7 | Apple Silicon 走 Rosetta | P2 | 低 | 中 | 接受 |
| R8 | pbs 下載失敗 | P2 | 低 | 中 | vendor cache + pin 版本 |
| R9 | .nef 授權（Kneron re-distribution） | **P1** | 中 | 高 | **Release blocker**：開發階段內嵌，R4-1 決定暫不主動問 Kneron，發佈前 gate 維持 |
| R10 | ffmpeg LGPL 合規 | P2 | 確定 | 低 | 文件工作 |
| R11 | 發佈通路基礎設施未確認 | P2 | 確定 | 中 | 追蹤項，M5 前確認 |
| R12 | CI runner 三平台是否齊備 | P2 | 確定 | 中 | 追蹤項，M4/M5 前確認 |
## 新發現的風險（相對 round 1）
相較於第一輪分析（`architect-analysis-round1.md`），第二輪多出以下幾個風險：
- **R4**（python-build-standalone 被防毒誤殺）：這是因為決策 Q1 = A 內嵌 Python 後才浮現，round 1 當時還傾向用系統 Python 所以沒這個問題
- **R8**（pbs 下載 URL 失效）：同上，由新的內嵌方案引入
- **R7**（Apple Silicon 走 Rosetta）：round 1 建議做 Universal Binary，Q4 決策改為只做 x86_64 後，Rosetta 路徑未經驗證變成風險點
**已解決（相對 round 1）：**
- ~~R1 Apple Developer 憑證~~ → 決策 Q2 接受無簽章
- ~~R2 Windows EV Cert~~ → 決策 Q2 接受 SmartScreen
- ~~R3 KneronPLUS macOS arm64~~ → 決策 Q4 只做 x86_64，不用管 arm64 wheel
- ~~R4 離線 wheel vs 線上下載~~ → 決策 Q1 A 完全離線
- ~~R5 預置模型精簡~~ → 決策 Q5 全打包

399
local-tool/.autoflow/04-architecture/tray-and-lifecycle.md Normal file
View File

@ -0,0 +1,399 @@
# Lifecycle — visionA-local
> 程序生命週期、single-instance lock、port 衝突、程序啟停、錯誤恢復
>
> ⚠️ **Tray 已砍**（第三輪使用者決策 Q-A=A3）。原本這份文件含 Tray 實作章節，現已全數移除。
> 檔名暫時保留為 `tray-and-lifecycle.md` 以避免大量交叉引用改動，內容已不含 tray。
> 相關 i18n key（`tray.*`）、圖資產（`tray-*.png`）、原 `edge-ai-platform/server/tray/` 皆不再沿用。
---
## 1. 生命週期總覽
```
[使用者雙擊 app]
↓
[Wails 啟動] → [single-instance check] → [已有 instance 在跑？]
│ │
│ no │ yes → 啟用已存在 instance 的視窗 → exit
▼
[檢查 .installed 標記] → [尚未安裝？]
│ │
│ no │ yes → [進入安裝精靈]（見 dependency-bundling.md）
▼
[spawn Go server 子行程]
↓
[等待 /api/system/health 200，最多 10 秒]
↓
[WebView loads http://127.0.0.1:{port}]
↓
[Dashboard 顯示]
↓
... 使用中 ...
↓
[使用者關閉主視窗（= Quit，見 Q7=B）]
↓
[cleanupAndExit]
├─ 送 SIGTERM 給 Go server
├─ 等 3 秒 graceful shutdown
├─ 仍存活 → SIGKILL
├─ 移除 single-instance lock
└─ Wails exit
```
## 2. Single-Instance Lock
### 2.1 需求
同一個使用者不應該同時跑兩個 visionA-local 視窗（會搶 3721 port、搶 Python sidecar 造成衝突）。
### 2.2 實作
**用檔案鎖 + PID + port 三重確認：**
```go
// visiona-local/lifecycle.go
func acquireSingleInstance(dataDir string) (release func(), err error) {
lockPath := filepath.Join(dataDir, "visiona-local.lock")
// 1. 嘗試建立 lock 檔（O_EXCL）
f, err := os.OpenFile(lockPath, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0644)
if err != nil && os.IsExist(err) {
// 2. 已存在 → 讀取裡面的 PID
data, _ := os.ReadFile(lockPath)
pid, _ := strconv.Atoi(strings.TrimSpace(string(data)))
// 3. 檢查該 PID 是否還活著
if pid > 0 && processAlive(pid) {
// 活著 → 嘗試透過 IPC 叫醒該 instance（見 2.3）
if raiseExistingInstance() {
return nil, ErrAlreadyRunning
}
}
// 4. stale lock → 覆寫
os.Remove(lockPath)
f, err = os.OpenFile(lockPath, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0644)
if err != nil {
return nil, err
}
}
// 5. 寫入自己的 PID
fmt.Fprintf(f, "%d", os.Getpid())
f.Close()
// 6. 回傳 cleanup function
return func() { os.Remove(lockPath) }, nil
}
```
### 2.3 喚起已存在 instance
用 localhost HTTP 呼叫一個特殊 endpoint：
```go
// Wails app 監聽 127.0.0.1:{random_port}/ipc/raise
func raiseExistingInstance() bool {
// 從 lock 檔附近的 .ipc-port 讀 port
portFile := filepath.Join(dataDir, "visiona-local.ipc-port")
data, err := os.ReadFile(portFile)
if err != nil {
return false
}
port := strings.TrimSpace(string(data))
resp, err := http.Get(fmt.Sprintf("http://127.0.0.1:%s/ipc/raise", port))
if err != nil {
return false
}
defer resp.Body.Close()
return resp.StatusCode == 200
}
```
被喚起的 instance 收到 `/ipc/raise` 後執行 `runtime.WindowShow(ctx)` 讓主視窗浮到前面。
### 2.3.1 第二次雙擊的完整序列
使用者在 app 已啟動時再次雙擊圖示 / 從 Spotlight / 從命令列啟動：
```
新 instance 啟動（process B）
↓
acquireSingleInstance() → lock 檔存在、PID 存活
↓
呼叫 raiseExistingInstance() → 讀 .ipc-port → GET http://127.0.0.1:{ipc-port}/ipc/raise
↓
既有 instance（process A）收到 → runtime.WindowShow(ctx) + runtime.WindowUnminimise(ctx) + runtime.WindowSetAlwaysOnTop(ctx,true) → 立刻 setAlwaysOnTop(false)（短暫提前到最上層後釋放）
↓
process A 回應 200
↓
process B 看到 200 → 立即 os.Exit(0)（不執行任何 cleanup，因為沒動任何狀態）
↓
使用者看到的效果：沒有新視窗，既有視窗被提到前景並閃一下
```
**失敗分支**：若 `/ipc/raise` 無回應（既有 instance 卡住），process B 判定既有 instance 不健康 → 嘗試 SIGTERM PID → 等 2 秒 → 若仍活著顯示錯誤對話框「偵測到另一個已停止回應的 instance，請手動結束後重試」，process B 退出但不奪取 lock（避免雙活）。
### 2.4 各平台差異
- **macOS**：Wails / Cocoa 本來就處理 "open another instance" 為 activate existing，但此行為只適用「從 Dock/Finder 啟動第二次」。從命令列或 Spotlight 仍可能啟動第二個程序，所以還是需要 app 層的鎖。
- **Windows**：必須自己實作。沒有原生機制會合併多個 exe 進入同一個 instance。
- **Linux**：同 Windows，但 AppImage 每次都是新程序，鎖檔更重要。
## 3. Port 衝突處理
### 3.1 問題
- 預設用 3721，但使用者可能有其他東西佔用
- 之前跑的 visionA-local 異常退出沒釋放 port
### 3.2 解法：動態 port + kill stale
```go
// server/main.go 的 killExistingProcess 邏輯保留並擴充
// visiona-local/server_launcher.go 新增
func pickPort(preferred int) (int, error) {
// 1. 先嘗試 preferred port
if available(preferred) {
return preferred, nil
}
// 2. 檢查 preferred port 上的程序是否是「上次沒清乾淨的 visiona-local-server」
if isOurStaleServer(preferred) {
killByPort(preferred)
time.Sleep(500 * time.Millisecond)
if available(preferred) {
return preferred, nil
}
}
// 3. 找下一個可用 port（3722, 3723, ...）
for p := preferred + 1; p < preferred+20; p++ {
if available(p) {
return p, nil
}
}
return 0, errors.New("no free port in range")
}
func isOurStaleServer(port int) bool {
// 檢查 process name 是否是 visiona-local-server
// Linux/macOS: lsof -i :port + ps -p PID
// Windows: netstat -ano + tasklist /FI "PID eq ..."
// ...
}
```
### 3.3 UI 呈現
如果最終選到的 port 不是 3721，在 Settings > Server 狀態區塊顯示實際 port，並在 server logs 印一行 warning。不彈視窗打擾使用者。
## 4. 程序啟停細節
### 4.1 啟動 Go server（spawn 邏輯）
```go
// visiona-local/server_launcher.go
type ServerProcess struct {
cmd *exec.Cmd
cancel context.CancelFunc
port int
dataDir string
}
func (inst *Installer) launchServer() (*ServerProcess, error) {
port, err := pickPort(3721)
if err != nil {
return nil, err
}
ctx, cancel := context.WithCancel(context.Background())
// 從 .installed 讀出 python.mode
meta := readInstallMeta(inst.dataDir)
binPath := filepath.Join(inst.dataDir, "bin", "visiona-local-server")
if runtime.GOOS == "windows" {
binPath += ".exe"
}
pythonBin := filepath.Join(inst.dataDir, "venv", "bin", "python3")
if runtime.GOOS == "windows" {
pythonBin = filepath.Join(inst.dataDir, "venv", "Scripts", "python.exe")
}
scriptsDir := filepath.Join(inst.dataDir, "scripts")
dataSubdir := filepath.Join(inst.dataDir, "data")
args := []string{
"--port", strconv.Itoa(port),
"--host", "127.0.0.1",
"--python", pythonBin,
"--scripts-dir", scriptsDir,
"--data-dir", dataSubdir,
"--log-level", "info",
}
cmd := exec.CommandContext(ctx, binPath, args...)
cmd.Stdout = inst.serverLogWriter("stdout")
cmd.Stderr = inst.serverLogWriter("stderr")
if err := cmd.Start(); err != nil {
cancel()
return nil, err
}
// 等健康檢查
if err := waitHealthy(port, 10*time.Second); err != nil {
cmd.Process.Kill()
cancel()
return nil, fmt.Errorf("server did not become healthy: %w", err)
}
return &ServerProcess{cmd: cmd, cancel: cancel, port: port, dataDir: inst.dataDir}, nil
}
func (sp *ServerProcess) Stop() {
// 1. graceful: SIGTERM
sp.cmd.Process.Signal(syscall.SIGTERM)
// 2. 等 3 秒
done := make(chan error, 1)
go func() { done <- sp.cmd.Wait() }()
select {
case <-done:
// ok
case <-time.After(3 * time.Second):
// 3. 強制殺
sp.cmd.Process.Kill()
<-done
}
sp.cancel()
}
```
### 4.2 Server 意外崩潰偵測
Wails app 開一個 goroutine `watchServer()`：
- 每 10 秒對 `/api/system/health` 做 healthcheck
- 失敗 3 次 → 認定 server 掛了
- **不自動重啟**（第一版）→ 顯示「Server 無回應」錯誤視窗，提供「重啟 server / 重新啟動 app / 查看 log」三個選項
- 第二版可加自動重啟（最多 3 次，避免 crash loop）
### 4.3 Python sidecar 生命週期
Python sidecar 由 Go server 自行管理（不由 Wails 控），沿用 `edge-ai-platform/server/internal/device/` 的 bridge 模式：
- 需要時 spawn（第一次 scan devices）
- 空閒 N 分鐘後自動 kill（省記憶體）
- Go server 關閉時一定要 reap（避免殭屍程序）
- **Mock 模式下完全不 spawn**（見 `architecture-overview §7`）
### 4.4 Python sidecar crash auto-restart（第四輪補件）
Python sidecar 可能因為 KneronPLUS 驅動異常、libusb 斷線、OOM 等原因崩潰。Go server 偵測 sidecar 崩潰後執行 auto-restart 策略：
```
device.Manager goroutine 監聽 python sidecar stdout/stderr pipe
↓
pipe EOF 或 process exit → 判定 crash
↓
restart_count < 3？
├─ Yes → sleep(backoff) → spawn 新 sidecar
│ backoff: 1s → 3s → 10s（指數退避）
│ spawn 成功 → 重置 restart_count、重新 scan devices
│ spawn 失敗 → restart_count++ → 下一輪
└─ No（連續 3 次失敗）→ 放棄 auto-restart
↓
WebSocket /ws/devices/events push
{"type":"sidecar_crashed","restart_attempts":3,
"last_error":"..."}
↓
前端顯示錯誤 modal：「硬體連線失敗，請檢查 USB 裝置或切換到 Mock 模式」
```
**restart_count 重置時機**：任何一次成功跑滿 5 分鐘不崩，就重置為 0（避免累積記住舊錯誤）。
**同一時段 Go server 也透過 WebSocket broadcast 給前端**，讓使用者立即知道問題，不用等下次操作才發現。
### 4.5 啟動時的資料目錄遷移
為了兼容早期開發階段可能殘留的舊路徑，Wails app 在 `acquireSingleInstance` **之後、`stepSetupPython*` 之前**執行一次性檢查：
```go
// visiona-local/data_migration.go
func MigrateOldDataDirs(newDir string, logger *log.Logger) {
candidates := oldDataDirCandidates() // 平台相依
for _, old := range candidates {
if _, err := os.Stat(old); err != nil {
continue
}
if _, err := os.Stat(newDir); err == nil {
logger.Printf("⚠️ 偵測到舊資料目錄 %s，但新路徑 %s 已存在，請手動清理舊路徑", old, newDir)
continue
}
if err := os.Rename(old, newDir); err != nil {
logger.Printf("⚠️ 遷移 %s → %s 失敗：%v", old, newDir, err)
continue
}
breadcrumb := filepath.Join(newDir, ".migrated-from")
os.WriteFile(breadcrumb, []byte(old+"\n"+time.Now().Format(time.RFC3339)), 0644)
logger.Printf("✅ 已將 %s 遷移到 %s", old, newDir)
}
}
func oldDataDirCandidates() []string {
home, _ := os.UserHomeDir()
switch runtime.GOOS {
case "darwin":
return []string{
filepath.Join(home, ".visiona-local"), // 隱藏資料夾
filepath.Join(home, "Library", "Application Support", "visionA-local"), // 大寫舊名
}
case "windows":
appdata := os.Getenv("APPDATA")
return []string{
filepath.Join(home, ".visiona-local"),
filepath.Join(appdata, "visionA-local"),
}
case "linux":
return []string{
filepath.Join(home, ".visiona-local"),
filepath.Join(home, ".local", "share", "visionA-local"),
}
}
return nil
}
```
**原則**：
- 遷移失敗不擋啟動
- 新路徑已存在時不覆蓋
- `.migrated-from` breadcrumb 供 troubleshooting 與未來版本確認是否已遷移過
- 只遷移一次（之後舊路徑已不存在，迴圈自然跳過）
---
## 5. 錯誤恢復矩陣
| 錯誤情境 | 偵測方式 | 處理 |
|---------|---------|-----|
| Python runtime 壞掉（bundled 被防毒刪） | venv 執行失敗 | 自動 fallback 到 system python；仍壞則提示重裝 |
| 3721 port 被佔用 | `pickPort` 找不到 | 顯示錯誤對話框 + 建議手動指定 port |
| Go server 無法啟動 | health check timeout | 顯示錯誤 + 附上最後 20 行 log |
| KneronPLUS driver 未安裝（Windows） | `pnputil /enum-drivers` 找不到 | 首次啟動時詢問 UAC；拒絕 → 降級到 Mock 模式 |
| Python sidecar 崩潰 | Go server 偵測 pipe 斷開 | 指數退避 auto-restart（1s/3s/10s），最多 3 次；超過則 WebSocket push 錯誤事件給前端顯示 modal（見 §4.4）|
| Lock 檔 stale（前一次沒清乾淨） | PID 不存在 | 自動清除並取得 lock |
| WebView 載入失敗 | `/api/system/health` 200 但 WebView 白屏 | 顯示「重新載入」按鈕 |
## 6. 平台差異總表
| 項目 | macOS | Windows | Linux |
|------|-------|---------|-------|
| Single-instance 機制 | 檔案鎖 + Cocoa 協助 | 檔案鎖 + Named Mutex | 檔案鎖 |
| 關閉視窗行為 | 關閉 = 結束（非 mac 慣例，但使用者決策 Q7=B） | 關閉 = 結束 | 關閉 = 結束 |
| Signal handling | SIGTERM / SIGKILL | TerminateProcess + graceful Ctrl+Break | SIGTERM / SIGKILL |
| Process tree 清理 | launchd 幫忙 reap | job object | prctl PR_SET_PDEATHSIG |
| 檔案鎖位置 | `~/Library/Application Support/visiona-local/visiona-local.lock` | `%APPDATA%\visiona-local\visiona-local.lock` | `~/.local/share/visiona-local/visiona-local.lock` |

145
local-tool/.autoflow/05-implementation/reviews/M1-1-review.md Normal file
View File

@ -0,0 +1,145 @@
# M1-1 Review Report — repo 骨架初始化
**審查者**：Reviewer Agent
**審查時間**：2026-04-10
**審查範圍**：M1-1 產出（`.gitignore` / `Makefile` / `README.md` / 目錄骨架 / `.gitkeep`）
**參考文件**：
- `.autoflow/04-architecture/architecture-overview.md` §4.1
- `.autoflow/04-architecture/build-pipeline.md` §1、§2、§3
- `.autoflow/progress.md`（第三輪 Q-D 決策：vendor/ 不進 git）
---
## 結論：✅ 通過（含 3 項 🟢 建議，不阻斷 M1-2）
整體品質良好，目錄結構、.gitignore 的 vendor/ 排除策略、Makefile target 覆蓋度、README 平台版本標註都符合規格。沒有誤建 `go.mod` / `package.json` / `wails.json`，也沒有 `git init`。以下列出 3 項建議項目，可在 M1-2 前順手補上，或延到後續任務處理。
---
## 檢查清單
### 1. 目錄結構對齊 architecture-overview.md §4.1
- [x] `server/` 存在（含 `.gitkeep`） — M1-2 會複製 edge-ai-platform 的 Go 後端
- [x] `frontend/` 存在（含 `.gitkeep`） — M1-4 會複製 Next.js 業務前端
- [x] `visiona-local/` 存在（含 `.gitkeep`） — M1-9 會從 installer/ 複製 Wails shell
- [x] `payload/` 存在（含 `.gitkeep`）
- [x] `vendor/` 存在（含 `.gitkeep`） — 雖 architecture-overview §4.1 原圖沒畫出 top-level vendor/，但 build-pipeline.md §2 明確定義 `/Users/jimchen/visionA/local-tool/vendor/` 為依賴快取根目錄，建立是正確的
- [x] `dist/` 存在 — 用於最終發行物
- [x] `scripts/` 存在（含 `.gitkeep`） — build-pipeline.md §3.1 有 `scripts/vendor-sync.sh`、§1 `installer-linux` 有 `scripts/build-appimage.sh`，合理
- [x] `Makefile` 與 `README.md` 在 repo root
### 2. .gitignore 正確性（對照 build-pipeline.md §2.4）
- [x] `/vendor/**` 被排除（R4-Q-D 決策 D2：vendor 不進 git）
- [x] `!/vendor/.gitkeep` 白名單保留
- [x] `!/vendor/README.md` 白名單保留（但實際 README.md 尚未建立 — 見 🟢-1）
- [x] `/dist/` 排除
- [x] `/visiona-local/build/` 排除（Wails build 輸出）
- [x] `/visiona-local/payload/` 排除（build 暫存），`!/visiona-local/payload/.gitkeep` 白名單
- [x] `/payload/*.tar.gz`、`/payload/*.zip` 排除
- [x] Go 常見忽略齊全（`*.exe` / `*.dylib` / `*.so` / `*.test` / `go.work.sum`）
- [x] Node/Next.js 常見忽略齊全（`node_modules/` / `.next/` / `out/` / `*.tsbuildinfo` / `.pnpm-store/`）
- [x] Python venv、cache 齊全
- [x] OS 忽略齊全（`.DS_Store` / `Thumbs.db` / `desktop.ini` / `._*`）
- [x] Editor（`.vscode/` / `.idea/` / `*.swp`）
- [x] Secrets（`.env*` / `*.pem` / `*.key`）
- [x] 保留既有的 `.claude/` 與 `.autoflow/.backups/` 規則
### 3. Makefile target 命名對齊 build-pipeline.md §1
| build-pipeline.md 規格 | M1-1 實作 | 狀態 |
|---|---|---|
| `help` | `help` | ✅ |
| `dev` / `dev-mock` | `dev` / `dev-mock` | ✅ |
| `build-server` | `build-server`（+ alias `server`） | ✅ |
| `build-frontend` | `build-frontend`（+ alias `frontend`） | ✅ |
| `build-embed` | `build-embed` | ✅ |
| `payload` / `payload-macos/windows/linux` | 同名 | ✅ |
| `installer-macos` | **拆成 `wails-macos` + `dmg`** | ⚠️ 見下 |
| `installer-windows` | **拆成 `wails-windows` + `exe`** | ⚠️ 見下 |
| `installer-linux` | **拆成 `wails-linux` + `appimage`** | ⚠️ 見下 |
| `vendor-sync` | `vendor-sync`（新增，build-pipeline.md §3.1 有腳本） | ✅ |
| `test` / `lint` / `fmt` / `clean` | 同名 | ✅ |
**命名差異說明：** Backend 把 `installer-{os}` 拆成兩段（`wails-{os}` 負責 wails build、`dmg`/`exe`/`appimage` 負責打包成發行檔）。**這個拆分可接受**，理由：
1. 單一職責更清晰，debug 時可只跑 wails build 不打包
2. CI 可以分開 cache wails build 產物
3. 未來要換打包工具（例如 dmgbuild → create-dmg）只影響後半段
4. 可以加一個 `installer-macos: wails-macos dmg` 的聚合 target 保持對 spec 的向下相容（見 🟢-2）
### 4. README.md 平台版本標註
- [x] macOS 14 (Sonoma) / 15 (Sequoia)，x86_64（Apple Silicon 走 Rosetta 2）✅
- [x] Windows 10 / 11，x86_64 ✅
- [x] Ubuntu 22.04 / 24.04，x86_64 ✅
- [x] 明確標註「不支援 ARM native（使用者決策 Q4）」
- [x] 有目錄結構說明、文件索引、狀態（M1 開發中）
- [x] 開發者快速開始有提醒「M1-1 所有 target 都是 placeholder，不會真的 build」，避免誤解
### 5. 禁區檢查
- [x] 沒有誤建 `go.mod`（root / server/ 都沒有） — M1-2、M1-3 會處理
- [x] 沒有誤建 `package.json`（frontend/） — M1-4 會處理
- [x] 沒有誤建 `wails.json`（visiona-local/） — M1-9 會處理
- [x] 沒有 `.git/` 目錄 — 未執行 `git init`，正確
- [x] 沒有 `go.work` — architecture-overview §4.1 有列出，但屬 M1-3 範圍，M1-1 跳過是對的
---
## 問題列表
### 🔴 阻斷
（無）
### 🟡 需修
（無）
### 🟢 建議（不阻斷 M1-2，可順手補）
#### 🟢-1：建立 `vendor/README.md` 說明依賴取得方式
`.gitignore` 已經把 `!/vendor/README.md` 列為白名單，但實際檔案尚未建立。建議補一份最小版本，說明：
- vendor/ 的用途（離線依賴快取）
- 為什麼不進 git（R4-Q-D 決策，避免 binary bloat）
- 如何取得（`make vendor-sync`）
- 子目錄結構（`python/` / `wheels/` / `ffmpeg/` / `yt-dlp/` / `drivers/`）
這樣新開發者 clone 之後看到空的 vendor/ 不會疑惑。
**優先級：** 低，可在 M1-2 前順手加，或延到 M3（首次真的用到 vendor/ 時）再補。
#### 🟢-2：加一個 `installer-{os}` 聚合 target 保持向下相容
為了跟 build-pipeline.md §1 原本的命名一致，建議在 Makefile 加：
```makefile
installer: installer-$(OS)
installer-macos: wails-macos dmg
installer-windows: wails-windows exe
installer-linux: wails-linux appimage
```
這樣 build-pipeline.md 原本提到的 `make installer-macos` 依然能用，又保留 Backend 拆分後的細粒度 target。**目前 M1-1 先不做也可以**，M1-12（dmg 完成時）再補即可。
**優先級：** 低，可延到 M1-12。
#### 🟢-3：`dist/` 目錄沒有 `.gitkeep`
目前 `dist/` 是空目錄，git 不會追蹤空目錄，下次 clone 後 `dist/` 會消失，雖然 Makefile 的 `build-server` 會 `mkdir -p $(DIST)`，但建議補一個 `.gitkeep` 保持一致性（其他五個目錄都有）。注意 `.gitignore` 的 `/dist/` 規則會讓 `.gitkeep` 也被忽略，需要改成：
```
/dist/*
!/dist/.gitkeep
```
或乾脆不保留空 `dist/` 目錄，改在第一次 build 時才建立（Makefile `clean` 已經會 `mkdir -p $(DIST)`，其實不需要在 repo 中預留目錄）。
**建議：** 採後者，**刪掉目前空的 `dist/` 目錄**，由 Makefile 負責建立即可，`.gitignore` 維持 `/dist/` 不變。這樣更乾淨。
**優先級：** 低。
---
## 通過後可以進入 M1-2 嗎？
**可以，立刻進入 M1-2（複製 server core from edge-ai-platform）。**
M1-1 的品質已達標，3 項建議都是錦上添花，不影響後續任務：
- 🟢-1（vendor/README.md）可延到 M3
- 🟢-2（installer 聚合 target）可延到 M1-12
- 🟢-3（dist/ 空目錄）可隨時順手處理
Orchestrator 可直接呼叫 Backend Agent 開始 M1-2。

153
local-tool/.autoflow/05-implementation/reviews/M1-10-review.md Normal file
View File

@ -0,0 +1,153 @@
# M1-10 Review — 改寫 app.go + Python 雙策略空殼 + 生命週期邏輯
**審查日期**：2026-04-10
**審查對象**：`/Users/jimchen/visionA/local-tool/visiona-local/`（`app.go` 重寫、`main.go`、`platform_*.go`、`embed.go` 已刪）
**任務描述**：把原 installer 的肥胖 app.go 整份砍掉重寫，留下啟動殼層：single-instance、舊路徑遷移、port picking、Python 雙策略空殼、spawn server 子行程、graceful shutdown、前端 binding
## 結論：✅ 通過
全部檢查點過關。舊 installer（Relay / Gitea / Tray / Cluster / Firmware / auto-update / libusb / ffmpeg setup / installer wizard）完全清光；`go build ./...` 與 `go vet ./...` 都乾淨通過；三平台資料路徑與 tray-and-lifecycle.md §6 完全一致；Python 雙策略介面符合 dependency-bundling.md §1.5；生命週期邏輯（lock、migrate、port、start/stop、health）都照 TDD 落地。Backend 回報的五個 TODO 均屬 M1+/M2 範圍，不阻斷 M1-10 驗收。**可以進入 M1-12（wails build + dmg）**。
---
## 檢查清單
### 1. 平台資料路徑正確
| 平台 | 期望 | 實際（`platform_*.go` + `appName`）| 狀態 |
|------|------|----------------------------------|------|
| macOS | `~/Library/Application Support/visiona-local` | `filepath.Join(home, "Library", "Application Support", appName)`（appName=`visiona-local`）| ✅ |
| Linux | `$XDG_DATA_HOME/visiona-local` → fallback `~/.local/share/visiona-local` | XDG 檢查齊全，fallback 正確 | ✅ |
| Windows | `%APPDATA%\visiona-local` | `os.Getenv("APPDATA")` + home fallback | ✅ |
**殘留舊名檢查**：只在 `oldDataDirCandidates()` 中出現 `.edge-ai-platform` / `visionA-local`（駝峰）/ `EdgeAIPlatform`，全部為 migration source path，屬正確用法。active 路徑無殘留。✅
### 2. 被砍功能確實不在
`grep` 掃過整個 `visiona-local/*.go`：
| 被砍項目 | 出現位置 | 狀態 |
|---------|---------|------|
| Relay | — | ✅ 無 |
| Gitea | — | ✅ 無 |
| Tray | 只出現在檔頭註解提到「tray 已被整份刪除」 | ✅ 無實作 |
| Cluster | — | ✅ 無 |
| Firmware | — | ✅ 無 |
| auto-update | 只出現在檔頭「已刪除」註解 | ✅ 無實作 |
| libusb | — | ✅ 無 |
| ffmpeg setup | — | ✅ 無 |
| installer wizard | 只出現在檔頭「已刪除」註解 | ✅ 無實作 |
| `embed.go` | 檔案已刪 | ✅ |
| `Installer` 型別 | — | ✅ 無 |
`main.go` 的 `Bind: []interface{}{app}` 只綁 `App`（`NewApp()`），不是舊的 `Installer`。✅
### 3. Python 雙策略介面
對照 `dependency-bundling.md §1.5` 決策樹：
| 檢查項 | 實作 | 狀態 |
|-------|------|------|
| `PythonMode` const | `auto` / `bundled` / `system` 三值齊全 | ✅ |
| `ensurePythonRuntime(auto)` → 先 system fallback bundled | `case PythonModeAuto` 先 `findSystemPython()` 再 `ensureBundledPython()` | ✅（符合 R4 決策：M1 先 system）|
| `findSystemPython()` 檢查 ≥ 3.10 | `isPython310OrNewer()` 解析 `Python 3.X.Y` 並比對 | ✅ |
| 候選名單 | `python3.12` / `3.11` / `3.10` / `python3` / `python` | ✅ |
| 避開 Windows Store stub | `strings.Contains(strings.ToLower(p), "windowsapps")` → skip | ✅ |
| `ensureBundledPython()` 為 placeholder | 直接回 `"bundled python runtime not yet implemented (M2 feature)"` 並附 `TODO(M2)` 註解指向 §1.3 | ✅ |
**小建議（不阻擋）**：`findSystemPython()` 沒有把 venv 建立 / wheel 安裝包進去，這是刻意的——M1 範圍只要「找到 interpreter 並把路徑傳給 server」，venv/wheels 留到 M2 由 bundled flow 一起處理。符合 M1 縮限範圍。
### 4. 生命週期邏輯
對照 `tray-and-lifecycle.md`：
| 檢查項 | § | 實作 | 狀態 |
|-------|-----|------|------|
| `acquireSingleInstance` lock + PID check | §2.2 | `O_CREATE|O_EXCL` + read PID + `processAlive` + stale lock 清理 | ✅ |
| `processAlive` 跨平台 | §2.4 | Unix: `proc.Signal(0)`；Windows: `tasklist /FI "PID eq ..."` | ✅ |
| 喚起既有 instance | §2.3 | `tryRaiseExistingInstance` 讀 `.ipc-port` 並打 `/api/system/health`（M1+ 才改成 `/ipc/raise`，已有 TODO 註解）| ✅（M1 可接受）|
| `migrateOldDataDirs` 在 lock 之前 | §4.5 | `startup()` 順序：`MkdirAll` → `migrate` → `acquireSingleInstance` | ✅ |
| 遷移失敗不擋啟動 | §4.5 | `continue` + stderr 警告 | ✅ |
| 新路徑已存在不覆蓋 | §4.5 | 檢查空目錄才 `os.Remove` + `Rename` | ✅（比 TDD 稍寬鬆但更實用：允許剛 MkdirAll 的空資料夾被替換）|
| `.migrated-from` breadcrumb | §4.5 | 寫入 `old\n + RFC3339 time` | ✅ |
| `pickPort(3721)` | §3.2 | 從 `defaultPreferredPort=3721` 起跳，掃 20 個 | ✅ |
| `isOurStaleServer` 偵測 | §3.2 | 尚未實作，已註 `TODO(M1+)` | ⚠️ 非阻斷（Backend 回報 known TODO）|
| `startServer` 流程 | §4.1 | ensurePython → pickPort → locateBinary → spawn → writeIPCPort → waitHealthy | ✅ |
| `stopServer` / `ServerProcess.stop()` SIGTERM → grace → SIGKILL | §4.1 | `shutdownGracePeriod=5s`，超時後 `Kill` + `<-done`；Windows 分支直接 `Kill` | ✅（TDD 寫 3s，實作 5s 更寬鬆，可接受）|
| `waitHealthy(port, timeout)` | §4.1 | `/api/system/health` 輪詢，`healthCheckTimeout=15s`，300ms 間隔 | ✅（TDD 寫 10s，實作 15s 更寬鬆）|
| `watchServer` 每 10 秒輪詢 | §4.2 | 尚未實作，Backend 回報 M1+ | ⚠️ 非阻斷 |
| `writeIPCPort` | §2.3 | 寫到 `dataDir/visiona-local.ipc-port` | ✅ |
**timeout 差異說明**：TDD 寫 3s grace / 10s health，實作用 5s / 15s。實作放寬不是縮緊，對正確性無影響；若 reviewer 嚴格要對齊 TDD 可留待 M1+ 統一調，不阻斷 M1-10。
### 5. `go build ./...` 重現
```
$ cd /Users/jimchen/visionA/local-tool/visiona-local && go build ./...
（無輸出）
$ go vet ./...
（無輸出）
```
✅ 乾淨通過，無 warning、無 unused import。
### 6. Wails binding 清單
`main.go`:
```go
Bind: []interface{}{app}
```
`app` 為 `*App`（`NewApp()` 回傳）。可被前端呼叫的 exported methods：
- `GetServerStatus() ServerStatus`
- `GetServerURL() string`
- `OpenBrowser(url string) error`
未綁舊 `Installer`、未綁任何 installer wizard method。✅
`main.go` Title：`"visionA Local"`（不是 `Edge AI Platform Installer`）。✅
### 7. 已知 TODO 清單（Backend 回報）
| TODO | 位置 | M 版本 | 阻斷 M1-10？|
|------|------|-------|------------|
| `ensureBundledPython` | `app.go:417` | M2 | ❌ 不阻斷（M1 先 system）|
| `/ipc/raise` endpoint | `app.go:550` TODO 註解 | M1+ | ❌ 不阻斷 |
| `watchServer` healthcheck 迴圈 | — | M1+ | ❌ 不阻斷 |
| `isOurStaleServer` + 自動 kill | `app.go:452` TODO 註解 | M1+ | ❌ 不阻斷 |
| Fatal 原生對話框（目前只寫 stderr + event emit）| `reportFatal` | M1+ | ❌ 不阻斷 |
五個 TODO 全部都有明確註解或計畫位置，符合「M1 為最小可跑殼層」的定位。
---
## 發現的次要問題（不阻擋 M1-10）
1. **`startServer` 的 error 分支對 `mockMode` 判斷位置怪異**（`app.go:205-208`）：
```go
pyBin, pyMode, err := a.ensurePythonRuntime(a.pythonMode)
if err != nil && !a.mockMode {
return fmt.Errorf(...)
}
```
當 `mockMode=true` 且 python 失敗時，`pyBin` 會是空字串、`pyMode` 可能是 `PythonModeAuto`，後續 `a.pythonBin = pyBin` 會存空字串。邏輯上能跑（因為 mock 不需要 python），但會讓 `GetServerStatus` 回報空的 `pythonBin`，前端顯示可能怪。建議 M1+ 在 mock 分支明確記一個 sentinel value（如 `"<mock>"`）。
2. **`log` 檔開啟錯誤被吞**（`app.go:243-246`）：`OpenFile` 回傳 error 被丟棄，只有 nil check。如果 `logsDir` 磁碟滿或權限異常，會靜默退到 `io.Discard`。建議 M1+ 把 error 寫進 `lastError`。
3. **`locateServerBinary` 的 candidates 順序**在開發模式下，`cwd/dist/` 在「與 exe 同目錄」之後。實務上 `wails dev` 會把 exe 放在 `build/bin/`，與 server binary 的實際位置（`dist/`）不同目錄，所以 candidate 3-4 會被用到。順序合理，但建議在 M1-12 build packaging 時驗證打包後 candidate 1 能命中。
4. **`migrateOldDataDirs` 的 stderr 警告**在 GUI app 情境下使用者看不到。搭配 #Fatal 原生對話框（M1+ TODO）一起改。
以上全部都是建議，**不影響 M1-10 驗收**。
---
## 結論與下一步
**M1-10 通過 ✅，可以進入 M1-12（wails build + dmg packaging）。**
下一階段的重點：
- M1-12 用 `wails build` 產生 macOS `.app`
- 驗證 `locateServerBinary` candidate 1（與 Wails exe 同目錄）能正確命中打包後的 `visiona-local-server`
- 產生 `.dmg` 並確認資料路徑在實機能正確建出
Backend 列出的 M1+ TODO（`/ipc/raise`、`watchServer`、`isOurStaleServer`、Fatal dialog）建議收在一個 M1-13 追蹤 issue，跟 M1-12 平行進行或接在其後。

141
local-tool/.autoflow/05-implementation/reviews/M1-2-review.md Normal file
View File

@ -0,0 +1,141 @@
# M1-2 Review — 複製 server core
- 審查者：Reviewer Agent
- 日期：2026-04-10
- 審查對象：`/Users/jimchen/visionA/local-tool/server/`
- 來源：`/Users/jimchen/Innovedus/edge-ai-platform/edge-ai-platform/server/`
## 結論：✅ 通過
M1-2 的任務目標是「直接複製 server core，跳過要刪的目錄，不修改內容」。所有檢查項全部符合預期，檔案內容與來源 byte-for-byte 相同，跳過清單 100% 正確。Import 在這個階段壞掉是預期中的事（M1-3 才會清理），以下已預先蒐集 M1-3 要修的完整清單。
---
## 跳過清單檢查
| 項目 | 來源是否存在 | 目標是否存在 | 結果 |
|------|------------|------------|------|
| `server/internal/cluster/` | ✅ | ❌ | ✅ 正確跳過 |
| `server/internal/tunnel/` | ✅ | ❌ | ✅ 正確跳過 |
| `server/internal/flash/` | ✅ | ❌ | ✅ 正確跳過 |
| `server/internal/update/` | ✅ | ❌ | ✅ 正確跳過 |
| `server/internal/relay/` | ✅ | ❌ | ✅ 正確跳過（code-reuse-plan 未明列，但符合「relay 相關一律砍」精神） |
| `server/pkg/hwid/` | ✅ | ❌ | ✅ 正確跳過 |
| `server/cmd/relay-server/` | ✅ | ❌ | ✅ 正確跳過（目標根本沒有 `cmd/` 目錄） |
| `server/tray/` | ✅ | ❌ | ✅ 正確跳過 |
| `server/scripts/firmware/` | ✅ | ❌ | ✅ 正確跳過 |
| `server/scripts/update_kl720_firmware.py` | ✅ | ❌ | ✅ 正確跳過 |
| `server/scripts/__pycache__/` | ✅ | ❌ | ✅ 正確跳過 |
| `server/web/out/`（舊 Next.js 產物） | ✅ | ❌ | ✅ 正確跳過 |
| `edge-ai-server` binary / `.next/` | — | ❌ | ✅ 未帶入 |
**驗證方法：** 對目標執行 `for d in ...; do [ -e "$d" ] && echo FOUND || echo OK; done`，全部 OK-MISSING。
---
## 必要檔案檢查
| 項目 | 結果 | 備註 |
|------|------|------|
| `server/main.go` | ✅ | 305 行，與來源逐 byte 相同 |
| `server/go.mod` | ✅ | 與來源相同 |
| `server/go.sum` | ✅ | 與來源相同 |
| `server/internal/api/` | ✅ | 含 handlers、ws、router.go、middleware.go、api_e2e_test.go 全齊 |
| `server/internal/camera/` | ✅ | |
| `server/internal/config/` | ✅ | |
| `server/internal/deps/` | ✅ | |
| `server/internal/device/` | ✅ | |
| `server/internal/driver/` | ✅ | |
| `server/internal/inference/` | ✅ | |
| `server/internal/model/` | ✅ | |
| `server/pkg/logger/` | ✅ | |
| `server/pkg/wsconn/` | ✅ | Backend 判斷保留 — 合理，`ws/` 下的 hub/device_events 等會依賴它 |
| `server/data/models.json` | ✅ | |
| `server/data/nef/` | ✅ | 8 個 `.nef` 檔、`data/` 總大小 73M，符合規格 |
| `server/scripts/kneron_bridge.py` | ✅ | |
| `server/scripts/requirements.txt` | ✅ | |
| `server/scripts/drivers/` | ✅ | 來源也有，順帶帶入，無衝突 |
| `server/web/embed.go` | ✅ | |
**注意：** `server/internal/api/handlers/cluster_handler.go`、`server/internal/api/ws/flash_ws.go`、`cluster_flash_ws.go`、`cluster_inference_ws.go` 這四個「檔案層級要刪」的檔案目前「存在」。這符合本階段規則（只跳過**整個目錄**，不砍單檔；檔案層級的刪除是 M1-3 的工作）。已列入下方 M1-3 待辦。
---
## 內容未修改驗證
使用 `diff -rq SRC/ DST/` 全面比對，結果：
- `diff -q main.go` → 完全相同
- `diff -q go.mod` → 完全相同
- `diff -rq internal/` → 只回報 `Only in SRC: cluster / tunnel / flash / update / relay`（全部都是預期要跳過的）
- `diff -rq pkg/` → 只回報 `Only in SRC: hwid`（預期）
- `diff -rq scripts/` → 只回報 `Only in SRC: __pycache__ / firmware / update_kl720_firmware.py`（預期）
- `diff -rq data/` → 無任何差異
- `diff -rq web/` → 只回報 `Only in SRC: out`（預期，舊 build 產物）
**結論：除了跳過清單上的項目，其餘檔案與來源 100% 相同。Backend Agent 確實沒動任何內容。**
---
## M1-3 要修的 import 清單（預先蒐集）
以下檔案含有「壞掉的 import」或「需要刪除的整檔」，M1-3 必須處理：
### A. 需要刪除的整個檔案
| 檔案 | 原因 |
|------|------|
| `server/internal/api/handlers/cluster_handler.go` | cluster 已砍（removed-code.md §2） |
| `server/internal/api/ws/flash_ws.go` | flash 已砍 |
| `server/internal/api/ws/cluster_flash_ws.go` | cluster + flash |
| `server/internal/api/ws/cluster_inference_ws.go` | cluster |
### B. 需要修改 import 與邏輯的檔案
| 檔案 | 壞掉的 import | M1-3 動作 |
|------|-------------|----------|
| `server/main.go` | `internal/cluster`（L23）、`internal/flash`（L27）、`internal/tunnel`（L30）、`pkg/hwid`（L31） | 依 removed-code.md §3、§4 刪除 import 與對應變數／啟動邏輯，並同步改 module path（`edge-ai-platform` → `visiona-local/server` 或使用者決定的名字） |
| `server/internal/api/router.go` | `internal/cluster`（L13）、`internal/flash`（L15） | 依 api-endpoints.md §4 改寫：移除 `clusterMgr` / `flashSvc` / `relayToken` 參數與對應 routes |
| `server/internal/api/api_e2e_test.go` | `internal/cluster`（L14）、`internal/flash`（L16） | 依 code-reuse-plan §2 改寫：刪除 cluster / flash / auth 測試案例 |
| `server/internal/api/handlers/device_handler.go` | `internal/flash`（L11） | 移除 `FlashDevice` handler 與 `flashSvc` 注入 |
| `server/internal/api/handlers/system_handler.go` | `internal/update`（L9） | 移除 `CheckUpdate`、`giteaURL` 參數、`update-check` handler |
### C. Module path 改名（全檔大量影響）
目前 `go.mod` 仍是 `module edge-ai-platform`（未改），所以**所有 .go 檔**中 `import "edge-ai-platform/..."` 會在 M1-3 改 module 名時一併更新。這是預期內的大規模 find-replace，不算額外壞掉的 import。
### D. grep 結果補充
```
grep -rn "edge-ai-platform/(cluster|tunnel|flash|update|relay|hwid)" server/
```
僅在上表 6 個檔案命中，其餘檔案乾淨。`ws/` 下的剩餘檔案（hub.go、device_events_ws.go、server_logs_ws.go、inference_ws.go）沒有任何壞掉的 import，M1-3 只需保留。
---
## 問題
### 🔴 Critical
無。
### 🟡 Major
無。M1-2 的範圍就是「複製 + 跳過」，目前所有檔案都在正確位置，內容未動，沒有任何超出職責的改動。
### 🟢 Minor / 備註
1. **Module name 尚未更改** — `go.mod` 仍是 `module edge-ai-platform`。這符合「本階段不修改內容」的承諾，但 M1-3 務必記得要改 module name 並同步所有 import。
2. **`scripts/drivers/` 順帶帶入** — 來源 `server/scripts/` 下有一個 `drivers/` 子目錄，code-reuse-plan 沒特別列出也沒列入刪除。Backend Agent 一起複製過來了，屬於無害的保守做法。若確認完全用不到，可在 M1-3 或清理階段再決定是否刪除。
3. **`web/embed.go` 保留但 `web/out/` 未複製** — 這是刻意的：`go:embed` 目標目錄是 `out/`，在 M1 階段因為還沒建 frontend，`embed.go` 編譯會失敗。這是 M1-3 或 frontend 階段要處理的問題（需要先放一個 placeholder `out/` 或改 embed 策略），**請提醒 M1-3 注意此編譯障礙**。
---
## 可以進入 M1-3 嗎？
✅ **可以**。M1-2 所有目標達成，複製完整、跳過正確、內容未動。M1-3 可直接依本報告「M1-3 要修的 import 清單」開始清理工作，建議順序：
1. 先刪除 A 清單的 4 個整檔
2. 再改 B 清單的 5 個檔案（router.go 最關鍵）
3. 執行 `go mod edit -module visiona-local/server`（或使用者決定的名字）
4. 全檔 find-replace `edge-ai-platform/` → 新 module path
5. 處理 `web/embed.go` 的 embed target（建立空 `out/` 或加 build tag）
6. `cd server && go build ./...` 驗證可通過

216
local-tool/.autoflow/05-implementation/reviews/M1-3-review.md Normal file
View File

@ -0,0 +1,216 @@
# M1-3 Review — 改寫 main/config/router + 清 import + module rename
- 審查者：Reviewer Agent
- 日期：2026-04-10
- 審查對象：`/Users/jimchen/visionA/local-tool/server/`
- 依據文件：`api-endpoints.md §4`、`removed-code.md §3~§6`、`M1-2-review.md`
## 結論：✅ 通過
M1-3 的所有目標達成：module 已改名為 `visiona-local/server`、四個要刪的檔案全數刪除、CLI flag 對齊規格、router/config/main/handlers/test 全部清乾淨，`go build ./...` 與 `go vet ./...` 一次通過。可以直接進入 M1-5。
---
## 檢查清單
### A. 要刪除的檔案（removed-code.md §2）
| 檔案 | 狀態 |
|------|------|
| `internal/api/handlers/cluster_handler.go` | ✅ 已刪除 |
| `internal/api/ws/flash_ws.go` | ✅ 已刪除 |
| `internal/api/ws/cluster_flash_ws.go` | ✅ 已刪除 |
| `internal/api/ws/cluster_inference_ws.go` | ✅ 已刪除 |
剩餘 `internal/api/ws/` 下只剩：`device_events_ws.go`、`hub.go`、`inference_ws.go`、`server_logs_ws.go`，符合 api-endpoints.md 中保留的 WebSocket 清單。
剩餘 `internal/api/handlers/` 下只剩：`camera_handler.go`、`device_handler.go`、`model_handler.go`、`model_upload_handler.go`、`system_handler.go`，乾淨。
### B. Module 改名
| 檢查項 | 結果 |
|-------|------|
| `go.mod` module 行 | ✅ `module visiona-local/server` |
| `grep -rn "edge-ai-platform" server/ --include="*.go"` | ⚠️ 僅命中 `driver/kneron/detector.go` L32-33 兩處**字串 literal**（`~/.edge-ai-platform/venv/...`），**非 import path** |
| 全檔 `edge-ai-platform/` import | ✅ 0 處 |
`detector.go` 內的路徑字串是掃描使用者家目錄找既有 Python venv 的 fallback 路徑，不是 module import，**符合 M1-3 要求**（僅 import 需更新）。列為 🟢 備註：等 installer / python runtime 重設計時再調整這兩個 legacy 路徑。
### C. CLI flag 對齊（config.go）
| Flag | 規格 | 實際 | 結果 |
|------|------|------|------|
| `--mock` | 必須 | ✅ bool | ✅ |
| `--dev` | 必須 | ✅ bool | ✅ |
| `--port` | 必須 | ✅ int，default 3721 | ✅ |
| `--data-dir` | 必須 | ✅ string | ✅ |
| `--python-mode` | 必須 | ✅ string（auto/bundled/system） | ✅ |
| `--mock-camera` | 保留 | ✅ bool | ✅ 合理 |
| `--mock-devices` | 保留 | ✅ int | ✅ 合理 |
| `--log-level` | 保留 | ✅ string | ✅ 合理 |
| `--model-dir` | 保留 | ✅ string | ✅ 合理 |
| `--host` | 保留（強制覆寫） | ✅ string，default 127.0.0.1 | ✅ 見 D |
| `--relay-url` | **必砍** | ❌ 不存在 | ✅ |
| `--relay-token` | **必砍** | ❌ 不存在 | ✅ |
| `--tray` | **必砍** | ❌ 不存在 | ✅ |
| `--gui` | **必砍** | ❌ 不存在 | ✅ |
`PythonMode` 定義為 typed string + 三個常數 + 預設 fallback，乾淨且符合 api-endpoints.md §5.2 未來要擴充的規劃。
### D. Host 強制 127.0.0.1
`config.go` L48-49：
```go
// 強制 localhost-only
cfg.Host = "127.0.0.1"
```
✅ **確實 override**。在 `flag.Parse()` 之後無條件覆寫，即使使用者傳 `--host 0.0.0.0` 也會被改回 `127.0.0.1`。防呆正確。
### E. Router 乾淨度（api-endpoints.md §4）
| 檢查項 | 結果 |
|-------|------|
| 簽章移除 `clusterMgr`、`flashSvc`、`relayToken` 三參數 | ✅ |
| `/api/clusters/*` routes | ✅ 0 處 |
| `/api/devices/:id/flash` | ✅ 已移除 |
| `/api/system/update-check` | ✅ 已移除 |
| `/auth/token` + OPTIONS | ✅ 已移除 |
| `/ws/devices/:id/flash-progress` | ✅ 已移除 |
| `/ws/clusters/*` | ✅ 0 處 |
| 保留的 REST routes 與 §4 清單逐項比對 | ✅ 完全符合 |
| 保留的 WS routes（devices/events, devices/:id/inference, server-logs） | ✅ 三條都在 |
| grep `clusterMgr|flashSvc|/api/clusters|/auth/token|update-check|/flash-progress|CheckUpdate` | ✅ 0 matches |
### F. main.go 清理（removed-code.md §3, §4）
| 檢查項 | 結果 |
|-------|------|
| imports 內無 `cluster/flash/tunnel/hwid` | ✅ |
| 沒有 `tunnelClient`、`clusterMgr`、`flashSvc`、`relayToken` 變數 | ✅ |
| 沒有 `relayWebURL`、`openBrowser` 函式 | ✅ |
| `NewSystemHandler` 呼叫移除 `giteaURL` | ✅ L147 只傳 `Version, BuildTime, restartFn` |
| `NewRouter` 呼叫移除 3 個參數 | ✅ L150 簽章對齊 |
| 保留 graceful shutdown + self-restart exec | ✅ |
| 保留 `killExistingProcess` | ✅ 合理（解決 port 被占用） |
### G. device_handler.go
| 檢查項 | 結果 |
|-------|------|
| 移除 `internal/flash` import | ✅ |
| 移除 `FlashDevice` handler | ✅（檔內已無） |
| 建構子 `NewDeviceHandler` 不再注入 `flashSvc` | ✅ 只收 deviceMgr/inferenceSvc/wsHub |
| 保留 Connect/Disconnect/Scan/List/Get/Start/Stop Inference | ✅ |
### H. system_handler.go
| 檢查項 | 結果 |
|-------|------|
| 移除 `internal/update` import | ✅ |
| 移除 `CheckUpdate` handler 與 `giteaURL` 欄位 | ✅ |
| 保留 Health/Info/Metrics/Deps/Restart | ✅ |
**備註**：api-endpoints.md §1.1 有要求 `/api/system/info` 擴充 `actual_port`、`mode`、`python_mode` 三個欄位，以及新增 `/api/system/mode`、`/api/system/python-runtime`、`/api/system/port` 三個 endpoint。目前 `Info()` 只回傳 `version/platform/uptime/goVersion`，新 endpoint 也尚未新增。**但這些是後續 milestone（M2 以後）的工作，不屬於 M1-3 的範圍**（M1-3 的任務是 *清理*，不是新增功能）。列入待辦追蹤，不影響本次通過。
### I. api_e2e_test.go
| 檢查項 | 結果 |
|-------|------|
| 移除 `cluster` / `flash` import | ✅ |
| 移除 cluster / flash / auth 測試案例 | ✅ 檔內無殘留 |
| `setupTestServer` 呼叫 `NewRouter` 簽章對齊 | ✅ L50-53 |
| 保留的測試：Health、DeviceWorkflow、DeviceScan、ModelList、ConnectNonExistent、MultiDeviceIsolation | ✅ |
---
## Build 驗證
自己實際跑的結果：
```bash
cd /Users/jimchen/visionA/local-tool/server
go build ./... → exit 0（無任何輸出）
go vet ./... → exit 0（無任何輸出）
```
✅ **完全乾淨**，無 compile error、無 vet warning。
---
## 針對審查重點 6、7、8 的判斷
### 6. CORS 中的 `X-Relay-Token` header（middleware.go L19）
```go
c.Header("Access-Control-Allow-Headers", "Content-Type, Authorization, X-Relay-Token")
```
**判斷：🟢 Minor（無害但可清）**。
- `relay-url/relay-token` flag、`RelayToken` config、`/auth/token` endpoint 都已移除，前端也不會再送這個 header。保留在 CORS allow-list 屬於**無害殘留**（瀏覽器只會放行，不會主動產生請求）。
- Backend 的判斷「保留但可清」合理。建議 M1-3 收尾或 M1-5 之前順手改成 `"Content-Type, Authorization"`，避免將來審計時引起疑問，但不阻擋進入 M1-5。
### 7. `internal/driver/` 裡的 `Flash` / `FlashProgress`
讀了 `internal/driver/interface.go`、`driver/kneron/kl720_driver.go:397` 附近、`driver/mock/mock_driver.go:68`，結論：
- `DeviceDriver` 介面的 `Flash(modelPath, progressCh)` 是**把 .nef 模型載入到 Kneron 裝置**的方法，對應 Kneron SDK 的 model load API（`kl720_driver.go` 的註解明確寫「models can be freely reloaded」，並搭配 `scripts/kneron_bridge.py`）。
- 這跟已刪除的 `internal/flash` package（韌體燒錄服務）完全是兩回事 —— 後者是 firmware flashing（KL720 firmware binary → device flash memory），前者是 model loading（把已訓練好的 .nef 模型丟到裝置的 RAM/ flash 區）。
- 既然 `/api/devices/:id/inference/start` 仍然需要先把模型載上去，這個 `Flash` 方法是**必要的**，不能刪。
**Backend 的判斷正確，列為 ✅ 無問題**。唯一 cosmetic 的點：未來可考慮把 `Flash` / `FlashProgress` 改名為 `LoadModel` / `LoadProgress` 避免語意混淆，但屬於重構，不在 M1-3 範圍。
### 8. `web/out/placeholder.txt` 解法
確認：
- `web/embed.go` 用 `//go:embed all:out` 指向 `out/` 目錄
- 因為 frontend 尚未 build，原本 `out/` 不存在會導致 `go build` 失敗（M1-2 review 已預警）
- M1-3 在 `out/` 下放了一個 `placeholder.txt`，讓 embed target 存在，build 即可通過
**判斷：🟢 合理的最小修補**。`all:` 前綴會一起 embed 底線或點開頭的檔案，但 placeholder.txt 不影響實際 static serving（因為等 frontend build 完就會覆蓋整個 `out/`）。簡單、正確、不擾動 embed.go。
---
## 問題
### 🔴 Critical
無。
### 🟡 Major
無。
### 🟢 Minor / Suggestion
1. **`middleware.go` L19 的 `X-Relay-Token`** — 無害殘留，建議之後收尾時清掉：
```go
c.Header("Access-Control-Allow-Headers", "Content-Type, Authorization")
```
2. **`driver/kneron/detector.go` L32-33 的 `.edge-ai-platform` 字串** — legacy 路徑字串，不是 import path，不影響 M1-3，但未來 installer/python runtime 重設計時應跟著改名（例如改為 `.visiona-local/venv/...`）。
3. **`/api/system/info` 尚未擴充 `actual_port` / `mode` / `python_mode`，以及 `/api/system/mode`、`/api/system/python-runtime`、`/api/system/port` 三個新 endpoint 尚未實作** — 屬於 M2 以後的工作（api-endpoints.md §1.1, §5），**不阻擋 M1-3 / M1-5**，但要記得追蹤。
4. **`Flash` / `FlashProgress` 命名語意模糊** — 未來重構時可考慮改為 `LoadModel` / `LoadProgress`，非必要。
### 優點
- Module rename 徹底、Go import 0 殘留，找不到任何 `edge-ai-platform/` import path。
- Router 與 api-endpoints.md §4 的規格**逐行對齊**，連註解順序都維持原作者風格。
- `config.go` 的 Host 強制 override 防呆寫得乾淨（flag 還是允許傳入便於開發者習慣，但結尾強制覆寫，二者兼顧）。
- `PythonMode` 用 typed string + fallback 預設值，為 M2 的 runtime 切換邏輯鋪好路。
- `api_e2e_test.go` 精簡得宜，保留了關鍵 workflow 測試，build + 編譯都乾淨（雖然本次沒跑 `go test`，但 vet 通過代表 test file 的 symbol 引用都對）。
- `killExistingProcess` 保留是明智的 — 對本地 daemon 很實用，開發時切換 binary 不會被 stale process 擋住。
---
## 可以進入 M1-5（build Go binary）嗎？
✅ **可以直接進入 M1-5**。
理由：
1. `go build ./...` 與 `go vet ./...` 在 reviewer 端重現，皆一次通過。
2. 所有刪除清單、module rename、router 簽章、CLI flag、Host 強制覆寫都對齊規格。
3. `web/out/placeholder.txt` 已解決 M1-2 預警的 embed 編譯障礙，`go build` 不再卡在 embed target 缺失。
4. 剩餘的 🟢 項目（CORS header、detector 路徑字串、system info 擴充）都不影響 binary 能不能 build，也不影響 binary 跑起來的核心功能，可延後處理。
建議 M1-5 時：
- 跑一次 `go test ./...` 當作額外保險（本次 review 未跑，僅跑 build + vet）。
- 驗證 `go build -o visiona-local-server .` 產出 binary 並直接執行一次，確認 `--mock --dev --port 3721` 能成功起 server。
- 順手把 🟢#1（CORS header）清掉，避免審計疑問。

57
local-tool/.autoflow/05-implementation/reviews/M1-5-review.md Normal file
View File

@ -0,0 +1,57 @@
# Code Review 報告 — M1-5（Go binary + smoke test）
## 審查摘要
- 審查對象：`dist/visiona-local-server` 及 `Makefile` 的 `server` / `build-server` target
- 產出 Agent：Backend Agent
- 審查結果：✅ 通過
- 問題統計：Critical: 0 / Major: 0 / Minor: 1 / Suggestion: 1
## 驗收項目清單
| # | 驗收項目 | 結果 | 證據 |
|---|---------|------|------|
| 1 | Binary 存在且可執行 | ✅ | `file dist/visiona-local-server` → `Mach-O 64-bit executable x86_64`，31 MB |
| 2 | `--help` 輸出包含 `--mock --dev --port --data-dir --python-mode` | ✅ | `-mock`, `-dev`, `-port`, `-data-dir`, `-python-mode` 皆存在 |
| 3 | `--help` 無 `--relay-url --tray --gui` | ✅ | 已完全移除，flag 清單乾淨 |
| 4 | `--host` 強制 127.0.0.1 | ✅ | flag 預設值為 `127.0.0.1`，help 字串 `(forced to 127.0.0.1 for local-only use)` |
| 5 | Smoke：`./visiona-local-server --mock --port 13721` 可啟動 | ✅ | log 顯示 `Server listening on 127.0.0.1:13721` |
| 6 | `GET /api/system/health` 回 200 | ✅ | `{"status":"ok"}` |
| 7 | `GET /api/system/info` 回 200 | ✅ | `{"data":{"goVersion":"go1.26.0","platform":"darwin/amd64","uptime":1.51,"version":"dev"},"success":true}` |
| 8 | Bind 在 127.0.0.1 而非 0.0.0.0 | ✅ | `lsof -nP -iTCP:13721` → `TCP 127.0.0.1:13721 (LISTEN)` |
| 9 | SIGTERM 可優雅關閉 | ✅ | `Received signal terminated, shutting down gracefully...` |
| 10 | Makefile `server` / `build-server` target 可執行 | ✅ | 兩個 target 已定義，`server` 為 `build-server` 的 alias，內容為 `cd server && go build -o ../dist/visiona-local-server .` |
| 11 | Embedded frontend 已掛載 | ✅ | log：`Serving embedded frontend static files`，註冊 `/_next/*filepath`、`/favicon.ico` |
| 12 | 外部依賴自檢 | ✅ | ffmpeg 8.0.1、yt-dlp 2026.02.04、python3 3.14.3 全部 OK |
## 問題清單
### Minor（建議修復）
| # | 檔案 | 問題描述 | 建議 |
|---|------|---------|------|
| 1 | `dist/data/models.json` | 啟動時 warning：`could not load models from .../dist/data/models.json: no such file or directory` | M1-8 打包時應把 seed 的 `models.json` 放進 `dist/data/`，或讓 backend 在檔案不存在時靜默跳過（目前就是走這條，只是 log 成 warning 略吵） |
### Suggestion（非必要）
| # | 建議 |
|---|------|
| 1 | 預設 `GIN_MODE=debug` 在正式 binary 跑會印很多 route 註冊 log；M1-9 installer build 時透過 ldflags 或環境變數設為 `release` 更乾淨 |
## 備註：Port 衝突與歷史 daemon
執行 smoke test 時發現系統上有一隻 legacy `edge-ai-server` (PID 44243) 已經佔用 `127.0.0.1:3721`（帶 `--relay-url / --relay-token / --tray` 參數，顯然是 M0 時代的背景 daemon）。**這不影響 M1-5 交付**，但：
1. 第一次 smoke test 若跑在 3721，curl 回應其實來自 legacy daemon，不是新 binary。**我改用 port 13721 重測，確認新 binary 行為正確。**
2. 建議 M1-9（Wails installer）或交付文件裡加一段「升級注意事項」：提醒使用者先 `pkill edge-ai-server` 或手動移除舊 launchd plist，否則新舊 binary 搶 port。
## 優點
- `--host` flag 明確標示 `forced to 127.0.0.1 for local-only use`，意圖清楚，local-only 原則落實到 CLI 層
- 啟動時主動做外部依賴自檢（ffmpeg / yt-dlp / python3），對使用者除錯很友善
- Graceful shutdown 正確實作（SIGTERM → 關閉 → 進程退出，無殘留）
- 路由註冊完整：system、models、devices、camera、media、ws 全部對齊 TDD 規格
- Makefile target 命名直覺，`server` 作為 `build-server` alias 符合慣用做法
## 總結意見
**M1-5 完整通過。** Binary 可執行、CLI flags 符合規格、強制 bind 127.0.0.1、health/info endpoint 正常、graceful shutdown 正確、Makefile target 可用。僅一個 Minor（models.json warning）與一個 Suggestion（GIN debug mode），皆不阻斷 M1 驗收。
可進入 M1-9（Wails installer shell）。

73
local-tool/.autoflow/05-implementation/reviews/M1-7-review.md Normal file
View File

@ -0,0 +1,73 @@
# Code Review 報告 — M1-7（前端清理 + pnpm build）
## 審查摘要
- 審查對象：`frontend/src/`（清理 cluster/relay 相關程式碼）、`frontend/out/`（pnpm build 產物）
- 產出 Agent：Frontend Agent
- 審查結果：✅ 通過（帶已知 walk-around，不阻斷 M1）
- 問題統計：Critical: 0 / Major: 0 / Minor: 4（皆已知、延到 M2）/ Suggestion: 1
## 驗收項目清單
| # | 驗收項目 | 結果 | 證據 |
|---|---------|------|------|
| 1 | `frontend/src/app/clusters/` 不存在 | ✅ | `ls` → No such file or directory |
| 2 | `frontend/src/app/workspace/cluster/` 不存在 | ✅ | `ls` → No such file or directory |
| 3 | `frontend/src/components/cluster/` 不存在 | ✅ | `ls` → No such file or directory |
| 4 | `frontend/src/components/relay-token-sync.tsx` 不存在 | ✅ | `ls` → No such file or directory |
| 5 | sidebar 不含 Clusters 導航項 | ✅ | `sidebar.tsx` navItems 僅 dashboard / models / devices / workspace / settings |
| 6 | Workspace 已提升為一級導航 | ✅ | `{ href: '/workspace', label: 'Workspace', icon: 'W' }` |
| 7 | `pnpm build` 可重現且成功 | ✅ | `Compiled successfully in 3.9s`、`Generating static pages (11/11)` |
| 8 | 產出 `frontend/out/` | ✅ | 已產出，含 index.html、devices/、models/、settings/、workspace/ |
| 9 | `frontend/out/` 無 clusters 目錄 | ✅ | `ls out/ \| grep cluster` → 無 |
| 10 | cluster 殘留皆為字串/註解，非 import/JSX | ✅ | grep 命中 4 檔：`i18n/types.ts`、`i18n/en.ts`、`i18n/zh-TW.ts`、`use-resolved-params.ts`（註解中的範例路徑） |
## pnpm build 輸出路由表
```
○ / (Static)
○ /_not-found
○ /devices
● /devices/[id] (SSG, uses generateStaticParams → /devices/_)
○ /models
● /models/[id] (SSG → /models/_)
○ /settings
○ /workspace
● /workspace/[deviceId] (SSG → /workspace/_)
```
全部 11 個靜態頁面成功產出，無編譯錯誤、無 TypeScript 錯誤。
## 問題清單
### Minor（已知 walk-around，延至 M2，不阻斷 M1）
| # | 檔案 | 問題描述 | 延後原因 |
|---|------|---------|---------|
| 1 | `settings/page.tsx`（推定） | Settings 頁面仍保留 relay token / update-check UI | M2 才重構 Settings |
| 2 | `lib/i18n/en.ts`, `zh-TW.ts`, `types.ts` | i18n 字串仍有 `cluster` key | M2 才清 i18n |
| 3 | `stores/activity-store.ts` / `components/activity-timeline.tsx`（推定） | `flash_*` 字串常量還在 | M2 才清 |
| 4 | `components/layout/sidebar.tsx` L16 | Workspace 用硬編字串 `label: 'Workspace'`，沒走 `t('nav.workspace')` | M2 補 i18n key |
### Suggestion（非必要）
| # | 說明 |
|---|------|
| 1 | Next.js static export 把 `workspace/[deviceId]` 產成 `workspace/_/` 佔位目錄（SSG with `generateStaticParams` 只產出 `_` 這一個 stub）。執行期 Wails shell 會用 `/workspace/{deviceId}` 的 hash route 或 query string 導航，實際渲染靠 client-side 拿 deviceId，目前方式 OK；建議在 `use-resolved-params.ts` 或 workspace 的 client component 加一行註解說明這個 pattern，以免未來有人看到 `out/workspace/_/` 覺得怪 |
## 動態路由 static export 的行為確認
`workspace/[deviceId]`、`devices/[id]`、`models/[id]` 在 Next.js 16 static export 下，若 `generateStaticParams` 回傳空陣列或包含 `_` placeholder，會產出 `/<route>/_` 作為 stub。**這是 Next.js 官方支援的做法**，runtime 在 Wails 環境用 client-side routing 拿到實際的 `deviceId` 即可。**不影響 M1 驗收**（macOS 雙擊 dmg 能跑）。
## 優點
- 刪除工作乾淨俐落，四個必刪路徑零殘留
- sidebar 精簡到只剩 5 個一級導航，符合 local-only 定位
- `pnpm build` 首次執行即成功，無需人工介入
- 產物體積合理、所有必要頁面都有產出
- 殘留的 `cluster` 字串都在 i18n 與註解中，不影響編譯，也不影響 runtime 行為
## 總結意見
**M1-7 通過，可進入 M1 驗收。** 四個已知 walk-around 都明確屬於 M2 範疇（settings 重構、i18n 清理、activity 字串、sidebar i18n key），與 M1 目標「macOS 雙擊 dmg 能跑」無衝突。build 產物完整可用，已準備好給 M1-8 embed 到 Go server。
可進入 M1-9（Wails installer shell）。

128
local-tool/.autoflow/05-implementation/reviews/M1-9-review.md Normal file
View File

@ -0,0 +1,128 @@
# M1-9 Review — 複製 Wails installer shell 改名為 visiona-local
**審查日期**：2026-04-11
**審查對象**：`/Users/jimchen/visionA/local-tool/visiona-local/`
**任務描述**：從 `edge-ai-platform/installer/` 複製 Wails 殼層，改名為 `visiona-local`，只處理命名與 metadata，不碰邏輯
## 結論：✅ 通過
所有必要檔案就位，命名規則一致（`visiona-local` 全小寫 for module/binary/bundle ID、`visionA-local` 駝峰 for 產品顯示名），Bundle ID 正確，三平台 wheels 都在，Makefile target 已就緒但註解掉實際執行。`platform_*.go` / `app.go` 邏輯完全沒動，符合 M1-9 範圍。可以進 M1-10。
---
## 檢查清單
### 1. 必要檔案存在
| 檔案 | 狀態 | 備註 |
|------|------|------|
| `app.go` | ✅ | 26502 bytes，未動 |
| `main.go` | ✅ | 623 bytes |
| `wails.json` | ✅ | |
| `go.mod` | ✅ | `module visiona-local` |
| `go.sum` | ✅ | 7137 bytes |
| `platform_darwin.go` | ✅ | 未動 |
| `platform_linux.go` | ✅ | 未動 |
| `platform_windows.go` | ✅ | 未動 |
| `embed.go` | ✅ | `//go:embed all:payload` |
| `build/darwin/Info.plist` | ✅ | |
| `frontend/` | ✅ | 有 index.html / app.js / style.css / wailsjs |
| `wheels/` | ✅ | macos / linux / windows 三子目錄齊全 |
### 2. wails.json 內容
| 欄位 | 期望 | 實際 | 狀態 |
|------|------|------|------|
| `name` | `visiona-local` | `visiona-local` | ✅ |
| `outputfilename` | `visiona-local` | `visiona-local` | ✅ |
| `info.productName` | `visionA-local`（駝峰） | `visionA-local` | ✅ |
| `info.companyName` | `Innovedus` | `Innovedus` | ✅ |
| `author.name` | — | `Innovedus` | ✅ |
| `info.copyright` | — | `Copyright 2026 Innovedus` | ✅ |
### 3. go.mod module
```go
module visiona-local
go 1.22.0
require github.com/wailsapp/wails/v2 v2.11.0
```
✅ 正確
### 4. Info.plist
| 欄位 | 期望 | 實際 | 狀態 |
|------|------|------|------|
| `CFBundleName` | `visionA-local` | `visionA-local` | ✅ |
| `CFBundleDisplayName` | `visionA-local` | `visionA-local` | ✅ |
| `CFBundleIdentifier` | `com.innovedus.visiona-local` | `com.innovedus.visiona-local` | ✅ |
| `CFBundleExecutable` | `{{.OutputFilename}}`（由 wails 填入） | `{{.OutputFilename}}` | ✅ |
| `CFBundleVersion` / `CFBundleShortVersionString` | `{{.Info.ProductVersion}}` | 同 | ✅ |
| 沒有殘留 `{{.Name}}` / `{{.Identifier}}` placeholder | — | 僅剩 `{{.OutputFilename}}` / `{{.Info.*}}`（Wails 標準欄位，會在 build 時填入） | ✅ |
說明：`{{.OutputFilename}}`、`{{.Info.ProductVersion}}`、`{{.Info.Copyright}}`、`{{.Info.Comments}}` 等是 Wails 標準 template，會在 `wails build` 時從 `wails.json` 填入，不是需要手動清掉的 placeholder。關鍵的 `{{.Name}}` / `{{.Identifier}}` 已經硬編碼為正確值。
### 5. 未誤動邏輯
- `app.go` 26502 bytes、`platform_*.go` 體積與 edge-ai-platform 相近 → 未改動 ✅
- grep `edge-ai-platform` 只在 `platform_darwin.go` / `platform_linux.go` 的資料目錄字串 literal 出現（4 筆），符合 M1-9 不動邏輯的範圍 ✅
### 6. Makefile `wails-macos` target
```makefile
wails-macos: ## wails build darwin/amd64 → visiona-local/build/bin/visiona-local.app
@echo "[M1-9] wails-macos target 已就緒；實際執行在 M1-12 啟用"
@echo " cd visiona-local && wails build -platform darwin/amd64 -clean"
# cd visiona-local && wails build -platform darwin/amd64 -clean
```
✅ target 已寫入 `.PHONY`，實際 `wails build` 指令被註解掉，只印提示訊息，符合 M1-9 不跑 build 的要求。
### 7. wheels/ 三平台
| 平台 | 檔案 | 狀態 |
|------|------|------|
| macOS | `KneronPLUS-2.0.0-py3-none-any.whl` | ✅ |
| Linux | `KneronPLUS-2.0.0-py3-none-any.whl` | ✅ |
| Windows | `KneronPLUS-3.1.2-py3-none-any.whl` | ✅（版本差異屬正常，KneronPLUS Windows 版本號本來就不同） |
---
## 問題
### 🔴 Blocker
無
### 🟡 Major
無
### 🟢 Minor / 提示（不阻擋 M1-9 通過，M1-10 處理）
1. **`main.go` 的 `Title: "Edge AI Platform Installer"`**
- 位置：`visiona-local/main.go:18`
- 說明：視窗標題仍是原 installer 字串。M1-10 要整個改寫 app.go + main.go 為 visionA-local 的 Python 雙策略空殼，屆時會一併改為 `"visionA-local Installer"` 或類似。列為提示，不在 M1-9 修正。
2. **`platform_darwin.go` / `platform_linux.go` 的 `.edge-ai-platform` 資料目錄字串**
- 位置：`platform_darwin.go:17,22`、`platform_linux.go:17,22`
- 說明：共 4 筆 literal，對應原 installer 的 `~/.edge-ai-platform` 資料目錄。依第四輪決策 R4-5，新資料目錄為全小寫 `visiona-local`（macOS 改到 `~/Library/Application Support/visionA-local/`）。題目明確說此屬 M1-10 範圍，此處只標記。
3. **`embed.go` 的 `//go:embed all:payload`**
- 目前 `visiona-local/` 下**沒有** `payload/` 目錄，在 M1-11 打包前，`go build` / `wails build` 會失敗（`pattern all:payload: no matching files found`）。
- M1-9 沒有要求 build 通過，且 Makefile `wails-macos` 實際指令已被註解，所以不阻擋此任務。但請 M1-10/M1-11 注意：在第一次嘗試 build 前，至少要先建立 `payload/.gitkeep` 或臨時空檔案，避免 embed 編譯炸掉。
4. **`frontend/` 仍是原 installer 的舊 UI**（`index.html` / `app.js`）
- M1-10 改寫 installer 邏輯時應同步改 UI，此處僅確認檔案存在，未檢查內容，符合 M1-9 範圍。
---
## 可以進 M1-10 嗎？
✅ **可以**。
M1-9 目標（複製殼、改命名、改 metadata、不動邏輯）已達成。M1-10 的工作建議如下：
1. 改寫 `main.go` 的視窗標題為 visionA-local
2. 改寫 `app.go` / `platform_*.go` 為 Python runtime 雙策略（A 內嵌 python-build-standalone + B fallback 偵測系統 Python）
3. 更新 `platform_darwin.go` / `platform_linux.go` 的資料目錄常數（`~/Library/Application Support/visionA-local/` 與 `~/.config/visiona-local/`）
4. 改寫 `frontend/` installer UI
5. 建立 `payload/.gitkeep`（避免 embed 編譯失敗）

230
local-tool/.autoflow/06-testing/M1-e2e-report.md Normal file
View File

@ -0,0 +1,230 @@
# M1 End-to-End Verification Report
## 測試環境
- macOS: 14.7.6 (BuildVersion 23H626)
- 架構: x86_64
- 檔案系統: APFS（case-insensitive，預設）
- 日期: 2026-04-11
- 測試方式: 複製 `.app` 到 `/tmp/` 模擬全新機器，清空 `~/Library/Application Support/visiona-local`
## 結論（TL;DR）
**M1 未通過。** `.dmg` 本身可正常 mount、`.app` bundle 結構正確、codesign 驗證通過，但**應用程式一啟動就失敗**。發現 **2 個 P0 阻斷 bug**：
1. **資料目錄遷移邏輯在 case-insensitive APFS 上壞掉** — 預設 Mac 根本啟動不了。
2. **Wails 端呼叫 server binary 時用了不存在的 flag `--python`** — 就算繞過 bug 1，server 子行程也會立刻 crash。
Mock 模式無法在全新 Mac 上運作，**瀏覽器無法看到主 UI**，M1 的核心承諾全部跳票。
---
## 前置清理
啟動前發現系統上 legacy `edge-ai-server` 持續被 launchd 重啟（`~/Library/LaunchAgents/com.innovedus.edge-ai-server.plist`），已執行：
```
launchctl unload ~/Library/LaunchAgents/com.innovedus.edge-ai-server.plist
pkill -9 -f edge-ai-server
```
之後 port 3721 淨空。**注意：這是測試環境前置清理，不是 M1 驗收的一部分。但這提醒：使用者第一次安裝若曾裝過 edge-ai-platform，升級 visiona-local 可能 port 衝突。**
---
## 驗證步驟結果
### Step 1: .dmg 檔案 ✅
- 路徑：`/Users/jimchen/visionA/local-tool/dist/visiona-local.dmg`
- 大小：70 MB
- 檔案類型：`zlib compressed data`
### Step 2: Mount ✅
`hdiutil attach` 成功，檢查碼全部通過：
- 掛載點：`/Volumes/visionA-local`
- 可見 `visiona-local.app`
### Step 3: .app 結構 ✅
- `Contents/Info.plist` ✓
- `Contents/MacOS/visiona-local`（9.8 MB，Mach-O 64-bit x86_64）✓
- `Contents/Resources/bin/visiona-local-server`（30 MB）✓
- `Contents/Resources/data/models.json`、`data/nef/` ✓
- `Contents/Resources/iconfile.icns`、`scripts/` ✓
- `codesign --verify --verbose`：**valid on disk, satisfies Designated Requirement** ✓
### Step 4: 全新機器模擬 ✅
`.app` 複製到 `/tmp/visiona-local.app`，DMG 已 detach。
### Step 5: 資料目錄清理 ✅
確認 `~/Library/Application Support/` 下無任何 `vision*` 殘留。
### Step 6 + 7: 啟動 → Server 起來 ❌❌
#### 第一次啟動（走正常流程）
```
$ /tmp/visiona-local.app/Contents/MacOS/visiona-local
[visiona-local] 遷移 /Users/jimchen/Library/Application Support/visionA-local
→ /Users/jimchen/Library/Application Support/visiona-local 失敗：
rename ...: no such file or directory
visiona-local already running
```
**Wails app 直接 exit(0)。** 沒有 server、沒有 UI、什麼都沒有。
**根因分析（P0 Bug #1）：** `visiona-local/app.go:572 migrateOldDataDirs` 的邏輯在 case-insensitive APFS 上會自我毀滅。
實際流程：
1. `startup()` 先 `MkdirAll(newDir)` 建立 `visiona-local/`。
2. `migrateOldDataDirs` 迭代舊候選路徑，其中包含 `visionA-local`（大寫 A）。
3. 在 case-insensitive APFS 上，`os.Stat(visionA-local)` **會 hit 剛建立的 `visiona-local`**（同 inode），所以 Stat 成功。
4. 程式碼接著檢查 newDir 是否存在（成功）、是否為空（剛建出來的，當然是空）→ 執行 `os.Remove(newDir)`。
5. `os.Remove(newDir)` 把那個目錄刪了，但在 case-insensitive FS 上這等於同時刪掉 `visionA-local`（同 inode）。
6. `os.Rename(visionA-local → newDir)` → 來源不存在 → `ENOENT`。
7. 更致命：newDir 已經被刪掉了，後續 `acquireSingleInstance` 嘗試在裡面建 lock 檔，`os.OpenFile` 回 `ENOENT`（父目錄不存在）。
8. `ENOENT` 不是 `IsExist`，函式直接回錯。外層的 handler 把「任何錯誤」都當成「already running」→ `os.Exit(0)`。
我用 Python 實測確認：
```python
os.makedirs('~/Library/Application Support/visiona-local')
os.path.exists('~/Library/Application Support/visionA-local') # → True
```
**這個 bug 在任何預設設定的 Mac 上都會觸發（APFS 預設 case-insensitive），等於 M1 在大部分 Mac 上根本跑不起來。**
#### 第二次啟動（workaround：預先建立非空 dataDir）
為了繼續測後面的步驟，我先 `mkdir visiona-local && touch .keep`。這樣 `migrateOldDataDirs` 的「newDir 已有內容 → 拒絕遷移」分支會 kick in，繞過 bug 1。
結果：Wails app 進程活著（PID 77828），lock file 建好了，寫了 `visiona-local.ipc-port = 3721`。
但 **port 3721 並沒有人 listen**：
```
$ lsof -i :3721
（空）
$ curl http://127.0.0.1:3721/api/system/health
（連線失敗）
```
檢查 `~/Library/Application Support/visiona-local/logs/server.stderr.log`：
```
flag provided but not defined: -python
Usage of .../visiona-local-server:
-python-mode string ...
（列出所有合法 flag，其中沒有 -python）
```
**P0 Bug #2：** `visiona-local/app.go:234` 組 server 參數時：
```go
args := []string{
"--host", "127.0.0.1",
"--port", strconv.Itoa(port),
"--data-dir", a.dataDir,
"--python-mode", string(pyMode),
}
if pyBin != "" {
args = append(args, "--python", pyBin) // ← server 沒有這個 flag
}
```
Server binary 只認 `--python-mode`，**不認 `--python`**。當系統有 python3（我這台 `/usr/local/bin/python3`）時，`ensurePythonRuntime` 會回傳 pyBin，於是 `--python /usr/local/bin/python3` 被加到參數列。Server 一啟動就 `flag provided but not defined: -python` → `os.Exit(2)`。
Wails app 沒有偵測到 server 掛了（沒有 health check wait，或者 check 失敗但沒有 abort），繼續掛在前景。
**組合效應：** 就算使用者手動繞過 bug 1，只要這台 Mac 上有安裝過 python3（絕大多數開發者 / macOS 自帶），就會撞到 bug 2。Mock 模式理論上不該碰 python，但目前的 code path 還是會把 pyBin 傳下去。
### Step 8: 主 UI 可訪問 ❌
因為 server 沒起來，`curl http://127.0.0.1:3721/` 得到 `HTTP 000`（連線拒絕）。**瀏覽器看不到任何東西。**
### Step 9: 資料目錄 ⚠️
在 workaround 下資料目錄內容：
```
.keep（我手動建的）
logs/
server.stderr.log ← 記錄 server 啟動失敗
server.stdout.log ← 空
visiona-local.ipc-port ← 內容 "3721"（但 port 根本沒在 listen）
visiona-local.lock ← 有 PID
```
`.ipc-port` 檔寫的是**預期 port**，不是**實際 port**，這本身也是潛在問題（但相比前兩個 bug 是次要的）。
### Step 10: 乾淨退出 ✅
`pkill -9 -f visiona-local` 後 `pgrep -fl visiona-local` 為空，`.app` 複本、資料目錄都清除乾淨。
### Step 11: make clean + make dmg 從頭跑 ⏭️ 略過
前面已經是阻斷級問題，重新 build 也不會修掉這兩個 bug。略過本步驟，等修好再驗。
---
## M1 驗收結論
| 核心承諾 | 結果 |
|---------|------|
| 1. 雙擊 .dmg → mount → .app 存在 | ✅ |
| 2. 啟動 → Mock 模式跑起來 | ❌ Wails app 秒退（bug 1）或 server 立刻 crash（bug 2） |
| 3. API (`/api/system/health`、`/api/system/info`) 可訪問 | ❌ port 沒有人 listen |
| 4. 主 UI 可在瀏覽器看到 | ❌ 同上 |
| 5. 乾淨退出 | ✅（但因為根本沒真的「運作」過，退出也沒什麼好清的） |
**核心承諾 2 / 3 / 4 全部沒達成。M1 未通過。**
---
## 發現的問題
### 🔴 P0 阻斷
#### P0-1: `migrateOldDataDirs` 在 case-insensitive APFS 上自我毀滅
- **位置**：`visiona-local/app.go:572-598` + `oldDataDirCandidates` 清單中的 `visionA-local`
- **影響**：任何預設 APFS 的 Mac（絕大多數使用者），**第一次啟動必失敗**。
- **修法建議**：
- (A) 用 `os.Stat` 比對 inode：如果舊路徑和新路徑指向同一個 inode，代表 case-insensitive FS 且實際上是同一個目錄，直接 `continue`，不要嘗試遷移。
- (B) 或者，在 candidates 裡**移除** `visionA-local` — 反正新版是 `visiona-local`，如果之前用的也是 `visiona-local`（case-insensitive FS 下等效），根本不需要遷移。只有在真正 case-sensitive FS（少數使用者自選）才需要這個 candidate，那就用 FS 類型偵測決定要不要加。
- (C) 額外修正：`startup()` 裡對 `acquireSingleInstance` 的錯誤處理要分辨「真的有別的 instance 在跑」vs「其他錯誤（例如資料目錄不見了）」。現在任何錯誤都印 "already running" 會誤導 debug。
#### P0-2: Wails 傳給 server 的 `--python` flag 不存在
- **位置**：`visiona-local/app.go:234`
- **影響**：只要系統上有 python（macOS 幾乎都有），server 子行程啟動即死。Mock 模式也一樣會死。
- **修法建議**：
- 改成 `--python-bin`（並在 server 端加對應 flag），或
- 把 pyBin 放在環境變數 `VISIONA_PYTHON_BIN` 傳，或
- 在 Mock 模式下完全不傳 pyBin 相關參數（根本用不到）。
- **額外**：Wails 端應該在 `startServer()` spawn 後做一次 health check（例如 500ms 內 poll `/api/system/health` 幾次），失敗就 `reportFatal`，不要讓 app 繼續假裝有在運作。
### 🟡 需修（非阻斷）
#### M-1: `.ipc-port` 寫的是預期 port 不是實際 port
Server 啟動前就寫好 port file，但如果 server 實際沒起來（bug 2 的情況），前端或 IPC 呼叫者會連到一個不存在的 port。應該在 server 真的 `LISTEN` 成功後才寫 ipc-port 檔（或由 server 自己寫）。
#### M-2: 系統級 launchd agent 殘留
`~/Library/LaunchAgents/com.innovedus.edge-ai-server.plist` 會自動重啟 legacy daemon，搶 3721 port。M1 uninstall / migration 文件應提醒使用者：若曾安裝 edge-ai-platform，需要手動 `launchctl unload` + 刪 plist。或在首次啟動時偵測到同 port 衝突時給出提示。
### 🟢 建議
- **測試環境 matrix**：目前所有開發測試都在同一台有 python、有舊 edge-ai-platform、有 legacy launchd 的 Mac 上跑。這兩個 bug（尤其 bug 1）在「乾淨 Mac」上才暴露。建議納入「新 macOS VM / 沒有 python 的 Mac / case-sensitive APFS 的 Mac」三種情境做 CI-level 驗證。
- `codesign` 目前是 ad-hoc/self-signed，上線前需要 Apple Developer ID 簽章 + notarize，否則 Gatekeeper 會擋。本次測試沒觸發這個議題（因為 `.app` 是本機 build 直接 run），但那是因為本機沒有 quarantine attr。從 `.dmg` 真的雙擊打開時會有不同行為，建議補 Gatekeeper 測試。
- Legacy LaunchAgent 議題（上方 M-2）也要在交付文件 (`07-delivery/launch-checklist.md`) 列成「升級安裝注意事項」。
---
## 結論：**M1 未通過，需修**
兩個 P0 bug 都必須在 ship 前修掉。建議流程：
1. **Architect Agent** 決定 bug 1 的修法（inode 比對 vs. 移除候選 vs. FS 偵測），以及 bug 2 的 flag 契約（改名 / 環境變數 / mock 模式不傳）。
2. **Backend Agent** 實作修復（`app.go` 兩處改動 + 可能的 server flag 新增）。
3. **Reviewer** 審查。
4. 重新 `make clean && make dmg`，**我再跑一次完整 E2E**。
5. 本次的前置清理步驟（unload launchd）也應寫進 launch-checklist，提醒升級使用者。
---
## 附錄：本次使用的清理指令
```bash
# 卸下 legacy launchd agent（若有）
launchctl unload ~/Library/LaunchAgents/com.innovedus.edge-ai-server.plist
pkill -9 -f edge-ai-server
pkill -9 -f visiona-local
# 清資料目錄（模擬全新使用者）
rm -rf "$HOME/Library/Application Support/visiona-local"
rm -rf "$HOME/Library/Application Support/visionA-local" # 注意：APFS 上這會和上一行等效
# 卸載 .dmg（若還掛著）
hdiutil detach /Volumes/visionA-local
```

237
local-tool/.autoflow/progress.md Normal file
View File

@ -0,0 +1,237 @@
# 專案進度 — 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`

263
local-tool/.github/workflows/build.yml vendored Normal file
View File

@ -0,0 +1,263 @@
name: Build
on:
push:
branches: [main]
tags: ['v*']
pull_request:
branches: [main]
workflow_dispatch:
env:
GO_VERSION: '1.26'
NODE_VERSION: '22'
PNPM_VERSION: '9'
# 暫時允許 GPL ffmpeg build 通過 vendor-sync 的授權檢查。
# 發佈前若 ffmpeg 來源改為 LGPL，請移除此變數。
VISIONA_ALLOW_GPL_FFMPEG: '1'
jobs:
# ────────────────────────────────────────────────────────────────
# macOS (Intel / x86_64)
# 使用 macos-13：目前最後的 Intel Mac runner，避免 macos-latest 被
# 切到 Apple Silicon 後產出 ARM binary。
# ────────────────────────────────────────────────────────────────
build-macos:
name: Build macOS (x86_64)
runs-on: macos-13
timeout-minutes: 60
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup Go
uses: actions/setup-go@v5
with:
go-version: ${{ env.GO_VERSION }}
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: ${{ env.NODE_VERSION }}
- name: Setup pnpm
uses: pnpm/action-setup@v4
with:
version: ${{ env.PNPM_VERSION }}
- name: Install Wails CLI
run: |
go install github.com/wailsapp/wails/v2/cmd/wails@latest
echo "$HOME/go/bin" >> "$GITHUB_PATH"
- name: Cache vendor/
uses: actions/cache@v4
with:
path: vendor/
key: vendor-darwin-${{ hashFiles('Makefile') }}-${{ hashFiles('visiona-local/wheels/macos/**') }}
restore-keys: |
vendor-darwin-${{ hashFiles('Makefile') }}-
vendor-darwin-
- name: vendor-sync (macOS deps)
run: make vendor-sync
- name: Build .dmg
run: make dmg
- name: Verify .dmg
run: |
ls -lh dist/visiona-local.dmg
file dist/visiona-local.dmg
hdiutil imageinfo dist/visiona-local.dmg | head -20
- name: Upload .dmg artifact
uses: actions/upload-artifact@v4
with:
name: visiona-local-macos-x64
path: dist/visiona-local.dmg
retention-days: 30
if-no-files-found: error
# ────────────────────────────────────────────────────────────────
# Windows (x86_64)
# 使用 windows-2022。vendor-sync 的 macOS/Linux 部分會失敗，
# 因此只跑 *-windows 的 vendor targets。
# ────────────────────────────────────────────────────────────────
build-windows:
name: Build Windows (x86_64)
runs-on: windows-2022
timeout-minutes: 60
defaults:
run:
shell: bash
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup Go
uses: actions/setup-go@v5
with:
go-version: ${{ env.GO_VERSION }}
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: ${{ env.NODE_VERSION }}
- name: Setup pnpm
uses: pnpm/action-setup@v4
with:
version: ${{ env.PNPM_VERSION }}
- name: Install Wails CLI
run: |
go install github.com/wailsapp/wails/v2/cmd/wails@latest
echo "$(go env GOPATH)/bin" >> "$GITHUB_PATH"
- name: Install Inno Setup
run: choco install innosetup -y --no-progress
shell: pwsh
- name: Add Inno Setup to PATH
run: echo "/c/Program Files (x86)/Inno Setup 6" >> "$GITHUB_PATH"
- name: Cache vendor/
uses: actions/cache@v4
with:
path: vendor/
key: vendor-windows-${{ hashFiles('Makefile') }}-${{ hashFiles('visiona-local/wheels/windows/**') }}
restore-keys: |
vendor-windows-${{ hashFiles('Makefile') }}-
vendor-windows-
- name: vendor-sync (Windows-only deps)
run: |
make vendor-python-windows \
vendor-wheels-windows \
vendor-ffmpeg-windows \
vendor-ytdlp-windows
- name: Build server.exe
env:
GOOS: windows
GOARCH: amd64
run: |
mkdir -p payload/windows/bin
cd server
go build -o ../payload/windows/bin/visiona-local-server.exe .
ls -lh ../payload/windows/bin/visiona-local-server.exe
- name: Build frontend (for go:embed)
run: make build-embed
- name: Build .exe installer
run: make exe
- name: Verify .exe
run: |
ls -lh dist/visiona-local-*.exe || ls -lh dist/*.exe
file dist/visiona-local-*.exe 2>/dev/null || true
- name: Upload .exe artifact
uses: actions/upload-artifact@v4
with:
name: visiona-local-windows-x64
path: dist/visiona-local-*.exe
retention-days: 30
if-no-files-found: error
# ────────────────────────────────────────────────────────────────
# Linux (x86_64)
# 使用 ubuntu-22.04（glibc 2.35，相容性比 24.04 更好）。
# ────────────────────────────────────────────────────────────────
build-linux:
name: Build Linux (x86_64)
runs-on: ubuntu-22.04
timeout-minutes: 60
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup Go
uses: actions/setup-go@v5
with:
go-version: ${{ env.GO_VERSION }}
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: ${{ env.NODE_VERSION }}
- name: Setup pnpm
uses: pnpm/action-setup@v4
with:
version: ${{ env.PNPM_VERSION }}
- name: Install system deps
run: |
sudo apt-get update
sudo apt-get install -y --no-install-recommends \
build-essential \
pkg-config \
libgtk-3-dev \
libwebkit2gtk-4.1-dev \
libusb-1.0-0-dev \
fuse \
libfuse2 \
desktop-file-utils
- name: Install Wails CLI
run: |
go install github.com/wailsapp/wails/v2/cmd/wails@latest
echo "$HOME/go/bin" >> "$GITHUB_PATH"
- name: Install appimagetool
run: |
curl -fL -o /tmp/appimagetool \
"https://github.com/AppImage/AppImageKit/releases/latest/download/appimagetool-x86_64.AppImage"
chmod +x /tmp/appimagetool
sudo mv /tmp/appimagetool /usr/local/bin/appimagetool
appimagetool --version || true
- name: Cache vendor/
uses: actions/cache@v4
with:
path: vendor/
key: vendor-linux-${{ hashFiles('Makefile') }}-${{ hashFiles('visiona-local/wheels/linux/**') }}
restore-keys: |
vendor-linux-${{ hashFiles('Makefile') }}-
vendor-linux-
- name: vendor-sync (Linux-only deps)
run: |
make vendor-python-linux \
vendor-wheels-linux \
vendor-ffmpeg-linux \
vendor-ytdlp-linux
- name: Build server (Linux)
run: |
mkdir -p payload/linux/bin
cd server
GOOS=linux GOARCH=amd64 go build -o ../payload/linux/bin/visiona-local-server .
ls -lh ../payload/linux/bin/visiona-local-server
- name: Build frontend (for go:embed)
run: make build-embed
- name: Build AppImage
run: make appimage
- name: Verify AppImage
run: |
ls -lh dist/visiona-local-*.AppImage
file dist/visiona-local-*.AppImage
- name: Upload AppImage artifact
uses: actions/upload-artifact@v4
with:
name: visiona-local-linux-x64
path: dist/visiona-local-*.AppImage
retention-days: 30
if-no-files-found: error

61
local-tool/.github/workflows/release.yml vendored Normal file
View File

@ -0,0 +1,61 @@
# TODO: enable when first release ready
#
# 此 workflow 會在推送 v* tag 時自動建立 GitHub Release，
# 並把 build.yml 產出的三平台 artifact 上傳。
#
# 啟用方式：
# 1. 確認 build.yml 三個 job 都能穩定成功
# 2. 把 `on.push.tags` 區塊取消註解
# 3. 推送 tag：`git tag v0.1.0 && git push origin v0.1.0`
name: Release
on:
workflow_dispatch:
# push:
# tags: ['v*']
jobs:
release:
name: Create GitHub Release
runs-on: ubuntu-22.04
permissions:
contents: write
steps:
- name: Checkout
uses: actions/checkout@v4
# 觸發並等待 build.yml 完成（或改用 workflow_run 觸發）
# 這裡先用最簡單的做法：假設 build.yml 已經跑過，直接抓 artifact
- name: Download macOS artifact
uses: actions/download-artifact@v4
with:
name: visiona-local-macos-x64
path: release/
- name: Download Windows artifact
uses: actions/download-artifact@v4
with:
name: visiona-local-windows-x64
path: release/
- name: Download Linux artifact
uses: actions/download-artifact@v4
with:
name: visiona-local-linux-x64
path: release/
- name: List release assets
run: ls -lh release/
- name: Create GitHub Release
uses: softprops/action-gh-release@v2
with:
tag_name: ${{ github.ref_name }}
name: visionA-local ${{ github.ref_name }}
draft: true
generate_release_notes: true
files: |
release/visiona-local.dmg
release/visiona-local-*.exe
release/visiona-local-*.AppImage

73
local-tool/.gitignore vendored Normal file
View File

@ -0,0 +1,73 @@
# Autoflow Agent（由 autoflow-agent init 自動產生）
.claude/
.autoflow/CLAUDE.md.backup.*
.autoflow/.backups/
# ── 第三方依賴（由 make vendor-sync 下載，不進 git；第三輪決策 Q-D=D2） ──
/vendor/**
!/vendor/.gitkeep
!/vendor/README.md
# ── 建置產出 ──
/dist/
/visiona-local/build/bin/
/visiona-local/build/darwin/Resources/
/visiona-local/payload/
!/visiona-local/payload/.gitkeep
# M1-11：頂層 payload/ 是 build 產物，不進 git（除了 .gitkeep）
/payload/**
!/payload/.gitkeep
/payload/*.tar.gz
/payload/*.zip
# ── Go ──
*.exe
*.exe~
*.dll
*.so
*.dylib
*.test
*.out
go.work.sum
# ── Node / Next.js / pnpm ──
node_modules/
.pnpm-store/
.next/
out/
*.tsbuildinfo
.npm
.pnpm-debug.log*
# ── Python（dev 時可能出現的 venv / cache） ──
__pycache__/
*.py[cod]
*$py.class
.venv/
venv/
*.egg-info/
# ── Editor / IDE ──
.vscode/
.idea/
*.swp
*.swo
# ── OS ──
.DS_Store
.DS_Store?
._*
.Spotlight-V100
.Trashes
ehthumbs.db
Thumbs.db
desktop.ini
# ── Env / Secrets ──
.env
.env.local
.env.*.local
*.pem
*.key

485
local-tool/Makefile Normal file
View File

@ -0,0 +1,485 @@
# visionA-local — Makefile（骨架，M1-1）
#
# 這份 Makefile 目前所有 targets 都只是 placeholder，實際內容會在後續任務逐步填入：
# - M1-2 複製 server core
# - M1-4 複製 frontend
# - M1-8 build-server / build-frontend 實作
# - M1-9 visiona-local (Wails) shell
# - M1-11 payload-macos
# - M1-12 installer-macos (dmg)
# - M2+ Windows / Linux / CI
#
# 詳見 .autoflow/04-architecture/build-pipeline.md
SHELL := /bin/bash
VERSION ?= v0.1.0-dev
BUILD_TIME := $(shell date -u +%Y-%m-%dT%H:%M:%SZ)
OS := $(shell uname -s | tr A-Z a-z)
DIST := dist
PAYLOAD := visiona-local/payload
.PHONY: help \
vendor-sync vendor-python vendor-wheels vendor-ffmpeg vendor-ytdlp \
vendor-python-windows vendor-wheels-windows vendor-ffmpeg-windows vendor-ytdlp-windows \
vendor-python-linux vendor-wheels-linux vendor-ffmpeg-linux vendor-ytdlp-linux \
server build-server \
frontend build-frontend build-embed \
payload payload-macos payload-windows payload-linux \
stage-macos stage-windows \
wails-macos wails-windows wails-linux \
dmg exe appimage \
dev dev-mock test lint fmt clean
# ── 幫助 ───────────────────────────────────────────────────────────
help: ## 列出所有 make targets
@echo "visionA-local — available targets (M1-1 skeleton)"
@echo ""
@echo " 依賴同步："
@echo " vendor-sync 下載 python-build-standalone / wheels / ffmpeg / yt-dlp → vendor/"
@echo ""
@echo " Build（單元）："
@echo " server build Go server binary (→ dist/visiona-local-server)"
@echo " frontend pnpm build Next.js 靜態產物 (→ frontend/out)"
@echo ""
@echo " Payload 準備："
@echo " payload-macos stage macOS payload → visiona-local/payload/"
@echo " payload-windows stage Windows payload"
@echo " payload-linux stage Linux payload"
@echo ""
@echo " Wails 應用 build："
@echo " wails-macos wails build darwin/amd64"
@echo " wails-windows wails build windows/amd64"
@echo " wails-linux wails build linux/amd64"
@echo ""
@echo " 安裝檔打包："
@echo " dmg macOS .dmg（dmgbuild）"
@echo " exe Windows .exe（Inno Setup）"
@echo " appimage Linux .AppImage"
@echo ""
@echo " 工具："
@echo " clean 清除 dist/ payload/"
@echo ""
@echo "Note: 目前所有 target 都是 placeholder（只印 TODO），尚未實作。"
# ── 依賴同步 ───────────────────────────────────────────────────────
PYTHON_VERSION := 3.12.9
PBS_RELEASE := 20250317
PBS_URL_DARWIN := https://github.com/astral-sh/python-build-standalone/releases/download/$(PBS_RELEASE)/cpython-$(PYTHON_VERSION)+$(PBS_RELEASE)-x86_64-apple-darwin-install_only.tar.gz
FFMPEG_URL_DARWIN := https://evermeet.cx/ffmpeg/getrelease/ffmpeg/zip
YTDLP_URL_DARWIN := https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_macos
vendor-sync: vendor-python vendor-wheels vendor-ffmpeg vendor-ytdlp ## 下載所有第三方依賴到 vendor/（不進 git，第三輪決策 Q-D=D2）
@echo "==> vendor-sync 完成"
vendor-python: ## 下載 python-build-standalone tarball → vendor/python/darwin/
@mkdir -p vendor/python/darwin
@if [ ! -f vendor/python/darwin/python.tar.gz ]; then \
echo "==> 下載 python-build-standalone $(PYTHON_VERSION)+$(PBS_RELEASE) (macOS x86_64 install_only)..."; \
curl -fL -o vendor/python/darwin/python.tar.gz "$(PBS_URL_DARWIN)"; \
echo "==> tarball 大小：$$(du -sh vendor/python/darwin/python.tar.gz | cut -f1)"; \
else \
echo "==> python tarball 已存在，跳過下載 ($$(du -sh vendor/python/darwin/python.tar.gz | cut -f1))"; \
fi
vendor-wheels: ## 同步 wheels → vendor/wheels/darwin/（內部 wheel 從 visiona-local/wheels 複製，公開相依用 pip download）
@mkdir -p vendor/wheels/darwin
@echo "==> 同步內部 wheels（KneronPLUS 等）..."
@if [ -d visiona-local/wheels/macos ]; then \
cp visiona-local/wheels/macos/*.whl vendor/wheels/darwin/ 2>/dev/null || true; \
fi
@echo "==> 從 PyPI 下載公開相依 wheels (cp312, macosx_x86_64)..."
@pip3 download \
--only-binary=:all: \
--platform macosx_10_9_x86_64 \
--platform macosx_11_0_x86_64 \
--platform macosx_12_0_x86_64 \
--python-version 3.12 \
--implementation cp \
--dest vendor/wheels/darwin \
numpy opencv-python-headless pyusb requests || echo "WARN: pip download 部分失敗（詳見上方訊息）"
@echo "==> wheels 總覽："
@ls -1 vendor/wheels/darwin/*.whl 2>/dev/null | wc -l | xargs -I{} echo " 共 {} 個 wheel"
@du -sh vendor/wheels/darwin
vendor-ffmpeg: ## 下載 ffmpeg static build (macOS x86_64) → vendor/ffmpeg/darwin/（預設要求 LGPL，必要時可用 VISIONA_ALLOW_GPL_FFMPEG=1 暫時放行 GPL）
@mkdir -p vendor/ffmpeg/darwin
@if [ -f vendor/ffmpeg/darwin/ffmpeg ]; then \
echo "==> ffmpeg 已存在，跳過 ($$(du -sh vendor/ffmpeg/darwin/ffmpeg | cut -f1))"; \
else \
echo "==> 下載 ffmpeg static build (macOS) from evermeet.cx..."; \
curl -fL -o /tmp/ffmpeg-latest.zip "$(FFMPEG_URL_DARWIN)"; \
unzip -o /tmp/ffmpeg-latest.zip -d vendor/ffmpeg/darwin/; \
rm -f /tmp/ffmpeg-latest.zip; \
chmod +x vendor/ffmpeg/darwin/ffmpeg; \
echo "==> ffmpeg 大小：$$(du -sh vendor/ffmpeg/darwin/ffmpeg | cut -f1)"; \
vendor/ffmpeg/darwin/ffmpeg -version 2>&1 | head -3; \
echo "==> 授權檢查："; \
if vendor/ffmpeg/darwin/ffmpeg -version 2>&1 | grep -q -- '--enable-gpl'; then \
if [ "$${VISIONA_ALLOW_GPL_FFMPEG:-0}" = "1" ]; then \
echo " !! WARNING: 此 build 含 --enable-gpl（GPL build） !!"; \
echo " !! VISIONA_ALLOW_GPL_FFMPEG=1 已啟用，暫時允許（僅限本地驗收，不可發佈） !!"; \
else \
echo "!! 錯誤：此 build 含 --enable-gpl，違反 LGPL 策略 !!"; \
echo "!! macOS 暫無現成 LGPL binary 來源，需自行 build 或用 VISIONA_ALLOW_GPL_FFMPEG=1 暫時放行 !!"; \
rm -f vendor/ffmpeg/darwin/ffmpeg; \
exit 1; \
fi; \
else \
echo " OK: 未偵測到 --enable-gpl"; \
fi; \
fi
vendor-ytdlp: ## 下載 yt-dlp standalone (macOS) → vendor/yt-dlp/darwin/
@mkdir -p vendor/yt-dlp/darwin
@if [ ! -f vendor/yt-dlp/darwin/yt-dlp ]; then \
echo "==> 下載 yt-dlp (macOS)..."; \
curl -fL -o vendor/yt-dlp/darwin/yt-dlp "$(YTDLP_URL_DARWIN)"; \
chmod +x vendor/yt-dlp/darwin/yt-dlp; \
echo "==> yt-dlp 大小：$$(du -sh vendor/yt-dlp/darwin/yt-dlp | cut -f1)"; \
vendor/yt-dlp/darwin/yt-dlp --version 2>&1 | head -1; \
else \
echo "==> yt-dlp 已存在，跳過 ($$(du -sh vendor/yt-dlp/darwin/yt-dlp | cut -f1))"; \
fi
# ── Build（單元） ──────────────────────────────────────────────────
server: build-server ## alias for build-server
build-server: build-embed ## build Go server binary → dist/visiona-local-server（會先 build frontend + embed）
@mkdir -p $(DIST)
cd server && go build -o ../$(DIST)/visiona-local-server .
@echo "built: $(DIST)/visiona-local-server"
frontend: build-frontend ## alias for build-frontend
build-frontend: ## pnpm build → frontend/out/
@echo "==> pnpm build frontend..."
cd frontend && pnpm install --frozen-lockfile && pnpm build
@echo "==> frontend/out 完成："
@du -sh frontend/out
build-embed: build-frontend ## 同步 frontend/out → server/web/out 供 go:embed
@echo "==> 同步 frontend/out → server/web/out..."
rm -rf server/web/out
mkdir -p server/web/out
cp -R frontend/out/. server/web/out/
@du -sh server/web/out
# ── Payload 準備 ───────────────────────────────────────────────────
payload: payload-$(OS) ## 依當前 OS 準備 payload
payload-macos: build-server vendor-python vendor-wheels vendor-ffmpeg vendor-ytdlp ## 準備 macOS payload → payload/darwin/（含 python runtime + wheels + ffmpeg + yt-dlp）
@echo "==> 建立 macOS payload (binary + models + scripts + python + wheels + ffmpeg + yt-dlp)..."
rm -rf payload/darwin
mkdir -p payload/darwin/bin payload/darwin/data payload/darwin/scripts payload/darwin/python payload/darwin/wheels
cp dist/visiona-local-server payload/darwin/bin/
cp vendor/ffmpeg/darwin/ffmpeg payload/darwin/bin/
cp vendor/yt-dlp/darwin/yt-dlp payload/darwin/bin/
chmod +x payload/darwin/bin/ffmpeg payload/darwin/bin/yt-dlp
cp -R server/data/* payload/darwin/data/
cp -R server/scripts/* payload/darwin/scripts/
cp vendor/python/darwin/python.tar.gz payload/darwin/python/
@cp vendor/wheels/darwin/*.whl payload/darwin/wheels/ 2>/dev/null || true
@echo "==> macOS payload 完成："
@du -sh payload/darwin
@echo ""
@echo "payload/darwin 結構："
@find payload/darwin -maxdepth 2 -type d | sed 's|^| |'
@echo ""
@echo "payload/darwin/python："
@ls -lh payload/darwin/python
@echo "payload/darwin/wheels："
@ls -1 payload/darwin/wheels | head -20
stage-macos: payload-macos ## 將 payload/darwin/ 放到 Wails build/darwin/Resources/
@echo "==> 放置 payload 到 Wails build/darwin/Resources..."
rm -rf visiona-local/build/darwin/Resources
mkdir -p visiona-local/build/darwin/Resources
cp -R payload/darwin/. visiona-local/build/darwin/Resources/
@echo "==> stage 完成："
@du -sh visiona-local/build/darwin/Resources
# ── M4：Windows vendor + payload + wails + exe ─────────────────────
# 注意：wails-windows 與 exe 必須在 Windows runner 上跑；在 macOS 上會明確 fail。
# payload-windows / vendor-*-windows 是 curl 下載，跨平台可跑（server.exe 步驟除外）。
PBS_URL_WINDOWS := https://github.com/astral-sh/python-build-standalone/releases/download/$(PBS_RELEASE)/cpython-$(PYTHON_VERSION)+$(PBS_RELEASE)-x86_64-pc-windows-msvc-install_only.tar.gz
FFMPEG_URL_WINDOWS := https://github.com/BtbN/FFmpeg-Builds/releases/latest/download/ffmpeg-master-latest-win64-gpl.zip
YTDLP_URL_WINDOWS := https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp.exe
vendor-python-windows: ## 下載 python-build-standalone Windows x86_64 → vendor/python/windows/
@mkdir -p vendor/python/windows
@if [ ! -f vendor/python/windows/python.tar.gz ]; then \
echo "==> 下載 python-build-standalone $(PYTHON_VERSION)+$(PBS_RELEASE) (Windows x86_64 install_only)..."; \
curl -fL -o vendor/python/windows/python.tar.gz "$(PBS_URL_WINDOWS)"; \
echo "==> tarball 大小：$$(du -sh vendor/python/windows/python.tar.gz | cut -f1)"; \
else \
echo "==> python (Windows) tarball 已存在，跳過 ($$(du -sh vendor/python/windows/python.tar.gz | cut -f1))"; \
fi
vendor-wheels-windows: ## 同步 Windows wheels → vendor/wheels/windows/
@mkdir -p vendor/wheels/windows
@echo "==> 同步內部 wheels (Windows, KneronPLUS 等)..."
@if [ -d visiona-local/wheels/windows ]; then \
cp visiona-local/wheels/windows/*.whl vendor/wheels/windows/ 2>/dev/null || true; \
fi
@echo "==> 從 PyPI 下載公開相依 wheels (cp312, win_amd64)..."
@pip3 download \
--only-binary=:all: \
--platform win_amd64 \
--python-version 3.12 \
--implementation cp \
--dest vendor/wheels/windows \
numpy opencv-python-headless pyusb requests || echo "WARN: pip download 部分失敗（詳見上方訊息）"
@echo "==> Windows wheels 總覽："
@ls -1 vendor/wheels/windows/*.whl 2>/dev/null | wc -l | xargs -I{} echo " 共 {} 個 wheel"
@du -sh vendor/wheels/windows 2>/dev/null || true
vendor-ffmpeg-windows: ## 下載 ffmpeg Windows static build → vendor/ffmpeg/windows/
@mkdir -p vendor/ffmpeg/windows
@if [ -f vendor/ffmpeg/windows/ffmpeg.exe ]; then \
echo "==> ffmpeg.exe 已存在，跳過"; \
else \
echo "==> 下載 ffmpeg Windows build from BtbN..."; \
echo "!! WARNING: BtbN 為 GPL build；license 由 PM 最終確認 !!"; \
curl -fL -o /tmp/ffmpeg-win.zip "$(FFMPEG_URL_WINDOWS)"; \
unzip -j -o /tmp/ffmpeg-win.zip "*/bin/ffmpeg.exe" -d vendor/ffmpeg/windows/; \
rm -f /tmp/ffmpeg-win.zip; \
echo "==> ffmpeg.exe 大小：$$(du -sh vendor/ffmpeg/windows/ffmpeg.exe | cut -f1)"; \
fi
vendor-ytdlp-windows: ## 下載 yt-dlp.exe → vendor/yt-dlp/windows/
@mkdir -p vendor/yt-dlp/windows
@if [ ! -f vendor/yt-dlp/windows/yt-dlp.exe ]; then \
echo "==> 下載 yt-dlp.exe..."; \
curl -fL -o vendor/yt-dlp/windows/yt-dlp.exe "$(YTDLP_URL_WINDOWS)"; \
echo "==> yt-dlp.exe 大小：$$(du -sh vendor/yt-dlp/windows/yt-dlp.exe | cut -f1)"; \
else \
echo "==> yt-dlp.exe 已存在，跳過"; \
fi
payload-windows: vendor-python-windows vendor-wheels-windows vendor-ffmpeg-windows vendor-ytdlp-windows ## 準備 Windows payload → payload/windows/
@echo "==> 建立 Windows payload (binary + models + scripts + python + wheels + ffmpeg + yt-dlp)..."
rm -rf payload/windows
mkdir -p payload/windows/bin payload/windows/data payload/windows/scripts payload/windows/python payload/windows/wheels
@echo "Note: visiona-local-server.exe 必須在 Windows runner 上 build："
@echo " cd server && GOOS=windows GOARCH=amd64 go build -o ../payload/windows/bin/visiona-local-server.exe ."
@if [ -f payload/windows/bin/visiona-local-server.exe ]; then \
echo "==> server.exe 已存在"; \
else \
echo "!! WARN: payload/windows/bin/visiona-local-server.exe 不存在（需在 Windows 上補 build） !!"; \
fi
cp vendor/ffmpeg/windows/ffmpeg.exe payload/windows/bin/
cp vendor/yt-dlp/windows/yt-dlp.exe payload/windows/bin/
cp -R server/data/. payload/windows/data/
cp -R server/scripts/. payload/windows/scripts/
cp vendor/python/windows/python.tar.gz payload/windows/python/
@cp vendor/wheels/windows/*.whl payload/windows/wheels/ 2>/dev/null || true
@echo "==> Windows payload 完成："
@du -sh payload/windows
@echo ""
@echo "payload/windows 結構："
@find payload/windows -maxdepth 2 -type d | sed 's|^| |'
stage-windows: payload-windows ## 將 payload/windows/ 放到 Wails build/windows/Resources/
@echo "==> 放置 payload 到 Wails build/windows/Resources..."
rm -rf visiona-local/build/windows/Resources
mkdir -p visiona-local/build/windows/Resources
cp -R payload/windows/. visiona-local/build/windows/Resources/
@echo "==> stage 完成："
@du -sh visiona-local/build/windows/Resources
# ── M5：Linux vendor + payload + wails + AppImage ──────────────────
# 注意：wails-linux 與 appimage 必須在 Linux runner 上跑；在 macOS 上會明確 fail。
# payload-linux / vendor-*-linux 是 curl 下載，跨平台可跑（server 步驟除外）。
PBS_URL_LINUX := https://github.com/astral-sh/python-build-standalone/releases/download/$(PBS_RELEASE)/cpython-$(PYTHON_VERSION)+$(PBS_RELEASE)-x86_64-unknown-linux-gnu-install_only.tar.gz
FFMPEG_URL_LINUX := https://johnvansickle.com/ffmpeg/releases/ffmpeg-release-amd64-static.tar.xz
YTDLP_URL_LINUX := https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_linux
vendor-python-linux: ## 下載 python-build-standalone Linux x86_64 → vendor/python/linux/
@mkdir -p vendor/python/linux
@if [ ! -f vendor/python/linux/python.tar.gz ]; then \
echo "==> 下載 python-build-standalone $(PYTHON_VERSION)+$(PBS_RELEASE) (Linux x86_64 install_only)..."; \
curl -fL -o vendor/python/linux/python.tar.gz "$(PBS_URL_LINUX)"; \
echo "==> tarball 大小：$$(du -sh vendor/python/linux/python.tar.gz | cut -f1)"; \
else \
echo "==> python (Linux) tarball 已存在，跳過 ($$(du -sh vendor/python/linux/python.tar.gz | cut -f1))"; \
fi
vendor-wheels-linux: ## 同步 Linux wheels → vendor/wheels/linux/
@mkdir -p vendor/wheels/linux
@echo "==> 同步內部 wheels (Linux, KneronPLUS 等)..."
@if [ -d visiona-local/wheels/linux ]; then \
cp visiona-local/wheels/linux/*.whl vendor/wheels/linux/ 2>/dev/null || true; \
fi
@echo "==> 從 PyPI 下載公開相依 wheels (cp312, manylinux2014_x86_64)..."
@pip3 download \
--only-binary=:all: \
--platform manylinux2014_x86_64 \
--python-version 3.12 \
--implementation cp \
--dest vendor/wheels/linux \
numpy opencv-python-headless pyusb requests || echo "WARN: pip download 部分失敗（詳見上方訊息）"
@echo "==> Linux wheels 總覽："
@ls -1 vendor/wheels/linux/*.whl 2>/dev/null | wc -l | xargs -I{} echo " 共 {} 個 wheel"
@du -sh vendor/wheels/linux 2>/dev/null || true
vendor-ffmpeg-linux: ## 下載 ffmpeg Linux static build → vendor/ffmpeg/linux/
@mkdir -p vendor/ffmpeg/linux
@if [ -f vendor/ffmpeg/linux/ffmpeg ]; then \
echo "==> ffmpeg (Linux) 已存在，跳過 ($$(du -sh vendor/ffmpeg/linux/ffmpeg | cut -f1))"; \
else \
echo "==> 下載 ffmpeg static build (Linux x86_64) from johnvansickle..."; \
echo "!! WARNING: johnvansickle build 為 GPL build；正式發佈前需改用 LGPL 來源 !!"; \
curl -fL -o /tmp/ffmpeg-linux.tar.xz "$(FFMPEG_URL_LINUX)"; \
mkdir -p /tmp/ffmpeg-linux-extract; \
tar xf /tmp/ffmpeg-linux.tar.xz -C /tmp/ffmpeg-linux-extract --strip-components=1; \
cp /tmp/ffmpeg-linux-extract/ffmpeg vendor/ffmpeg/linux/; \
chmod +x vendor/ffmpeg/linux/ffmpeg; \
rm -rf /tmp/ffmpeg-linux* ; \
echo "==> ffmpeg (Linux) 大小：$$(du -sh vendor/ffmpeg/linux/ffmpeg | cut -f1)"; \
if [ "$${VISIONA_ALLOW_GPL_FFMPEG:-0}" != "1" ]; then \
echo " ⚠️ 提醒：此 build 為 GPL，僅限本地驗收，發佈前請改用 LGPL build"; \
fi; \
fi
vendor-ytdlp-linux: ## 下載 yt-dlp (Linux) → vendor/yt-dlp/linux/
@mkdir -p vendor/yt-dlp/linux
@if [ ! -f vendor/yt-dlp/linux/yt-dlp ]; then \
echo "==> 下載 yt-dlp (Linux)..."; \
curl -fL -o vendor/yt-dlp/linux/yt-dlp "$(YTDLP_URL_LINUX)"; \
chmod +x vendor/yt-dlp/linux/yt-dlp; \
echo "==> yt-dlp (Linux) 大小：$$(du -sh vendor/yt-dlp/linux/yt-dlp | cut -f1)"; \
else \
echo "==> yt-dlp (Linux) 已存在，跳過"; \
fi
payload-linux: vendor-python-linux vendor-wheels-linux vendor-ffmpeg-linux vendor-ytdlp-linux ## 準備 Linux payload → payload/linux/
@echo "==> 建立 Linux payload (binary + models + scripts + python + wheels + ffmpeg + yt-dlp)..."
rm -rf payload/linux
mkdir -p payload/linux/bin payload/linux/data payload/linux/scripts payload/linux/python payload/linux/wheels
@echo "Note: visiona-local-server (Linux) 必須在 Linux runner 上 build："
@echo " cd server && GOOS=linux GOARCH=amd64 go build -o ../payload/linux/bin/visiona-local-server ."
@if [ -f payload/linux/bin/visiona-local-server ]; then \
echo "==> visiona-local-server 已存在"; \
elif [ -f dist/visiona-local-server-linux ]; then \
cp dist/visiona-local-server-linux payload/linux/bin/visiona-local-server; \
chmod +x payload/linux/bin/visiona-local-server; \
echo "==> 從 dist/visiona-local-server-linux 複製 server binary"; \
else \
echo "!! WARN: payload/linux/bin/visiona-local-server 不存在（需在 Linux 上補 build） !!"; \
fi
@cp vendor/ffmpeg/linux/ffmpeg payload/linux/bin/ 2>/dev/null && chmod +x payload/linux/bin/ffmpeg || echo "!! WARN: ffmpeg 缺失"
@cp vendor/yt-dlp/linux/yt-dlp payload/linux/bin/ 2>/dev/null && chmod +x payload/linux/bin/yt-dlp || echo "!! WARN: yt-dlp 缺失"
@if [ -d server/data ]; then cp -R server/data/. payload/linux/data/; fi
@if [ -d server/scripts ]; then cp -R server/scripts/. payload/linux/scripts/; fi
@cp vendor/python/linux/python.tar.gz payload/linux/python/ 2>/dev/null || echo "!! WARN: python tarball 缺失"
@cp vendor/wheels/linux/*.whl payload/linux/wheels/ 2>/dev/null || true
@echo "==> Linux payload 完成："
@du -sh payload/linux 2>/dev/null || true
@echo ""
@echo "payload/linux 結構："
@find payload/linux -maxdepth 2 -type d 2>/dev/null | sed 's|^| |'
# ── Wails build ────────────────────────────────────────────────────
wails-macos: stage-macos ## wails build darwin/amd64 → visiona-local/build/bin/visiona-local.app
cd visiona-local && wails build -platform darwin/amd64 -clean
cp -R visiona-local/build/darwin/Resources/bin \
visiona-local/build/darwin/Resources/data \
visiona-local/build/darwin/Resources/scripts \
visiona-local/build/darwin/Resources/python \
visiona-local/build/darwin/Resources/wheels \
visiona-local/build/bin/visiona-local.app/Contents/Resources/
codesign --force --deep --sign - visiona-local/build/bin/visiona-local.app
codesign --verify --verbose visiona-local/build/bin/visiona-local.app
@du -sh visiona-local/build/bin/visiona-local.app
wails-windows: stage-windows ## ⚠️ 必須在 Windows runner 上執行：wails build -platform windows/amd64
@case "$$(uname -s 2>/dev/null)" in \
MINGW*|CYGWIN*|MSYS*) : ;; \
*) \
echo ""; \
echo "❌ wails-windows 只能在 Windows runner 上 build（偵測到 $$(uname -s)）"; \
echo " 請在 Windows 機器上執行此 target，或用 CI 的 Windows runner"; \
echo " 若只是要檢查前置步驟，可單獨跑 make stage-windows"; \
echo ""; \
exit 1 ;; \
esac
cd visiona-local && wails build -platform windows/amd64 -clean
@du -sh visiona-local/build/bin/visiona-local.exe
wails-linux: payload-linux ## ⚠️ 必須在 Linux runner 上執行：wails build -platform linux/amd64
@if [ "$$(uname -s)" != "Linux" ]; then \
echo ""; \
echo "❌ wails-linux 只能在 Linux 上 build（偵測到 $$(uname -s)）"; \
echo " 請在 Linux x86_64 runner（GitHub Actions ubuntu-latest 即可）執行"; \
echo " 若只是要檢查前置步驟，可單獨跑 make payload-linux"; \
echo ""; \
exit 1; \
fi
cd visiona-local && wails build -platform linux/amd64 -clean
@du -sh visiona-local/build/bin/visiona-local
# ── 安裝檔打包 ─────────────────────────────────────────────────────
dmg: wails-macos ## hdiutil UDZO → dist/visiona-local.dmg
mkdir -p $(DIST)
rm -f $(DIST)/visiona-local.dmg
hdiutil create -volname "visionA-local" \
-srcfolder visiona-local/build/bin/visiona-local.app \
-ov -format UDZO \
$(DIST)/visiona-local.dmg
@du -sh $(DIST)/visiona-local.dmg
@file $(DIST)/visiona-local.dmg
exe: wails-windows ## ⚠️ 必須在 Windows 上跑：Inno Setup → dist/visiona-local-*-windows-x64.exe
@if ! command -v iscc > /dev/null 2>&1 && ! command -v iscc.exe > /dev/null 2>&1; then \
echo ""; \
echo "❌ Inno Setup Compiler (iscc) 未安裝"; \
echo " 請從 https://jrsoftware.org/isdl.php 下載並安裝 Inno Setup 6"; \
echo " 安裝後將 iscc.exe 目錄加入 PATH"; \
echo ""; \
exit 1; \
fi
@mkdir -p $(DIST)
iscc installer/windows/visiona-local.iss
@echo "==> 產出："
@ls -lh $(DIST)/visiona-local-*-windows-x64.exe 2>/dev/null || echo "未找到產出檔"
appimage: wails-linux ## ⚠️ 必須在 Linux 上跑：build-appimage.sh → dist/visiona-local-*-linux-x64.AppImage
@if [ "$$(uname -s)" != "Linux" ]; then \
echo ""; \
echo "❌ appimage 只能在 Linux 上 build（偵測到 $$(uname -s)）"; \
echo " 需要 appimagetool，請在 Linux x86_64 runner 執行"; \
echo ""; \
exit 1; \
fi
@mkdir -p $(DIST)
VERSION=$(VERSION) bash installer/linux/build-appimage.sh
@echo "==> 產出："
@ls -lh $(DIST)/visiona-local-*-linux-x64.AppImage 2>/dev/null || echo "未找到產出檔"
# ── 開發（placeholder） ────────────────────────────────────────────
dev:
@echo "TODO: make -j2 dev-server dev-frontend（開發模式）"
dev-mock:
@echo "TODO: make -j2 dev-mock-server dev-frontend（Mock 模式）"
test:
@echo "TODO: go test + pnpm test"
lint:
@echo "TODO: go vet + pnpm lint"
fmt:
@echo "TODO: go fmt"
# ── 清理 ───────────────────────────────────────────────────────────
clean: ## 清除 dist/ 與 payload/ 產物
@echo "Cleaning dist/ and payload artifacts..."
rm -rf $(DIST)
rm -rf $(PAYLOAD)
@mkdir -p $(DIST) $(PAYLOAD)
@touch $(DIST)/.gitkeep $(PAYLOAD)/.gitkeep
@echo "Done."

200
local-tool/README.md Normal file
View File

@ -0,0 +1,200 @@
# visionA-local
> **裝起來像一般 app，離線也能跑，接上 Kneron 就推論。**
> 把 `edge-ai-platform` 的 Kneron AI 邊緣推論能力，打包成單機桌面應用。
![macOS x86_64](https://img.shields.io/badge/macOS_x86__64-beta-brightgreen)
![Windows x86_64](https://img.shields.io/badge/Windows_x86__64-TBD-lightgrey)
![Linux x86_64](https://img.shields.io/badge/Linux_x86__64-TBD-lightgrey)
![License](https://img.shields.io/badge/license-TBD-orange)
<!-- TODO: docs/screenshots/logo.png -->
---
## 這是什麼
visionA-local 是 `edge-ai-platform`（原本要部署到 EC2 + Docker 的 Kneron 邊緣推論平台）的**單機桌面衍生版本**。為「帶著筆電做 Kneron demo 的人」而生 —— 主要服務 Innovedus 內部 FAE 與外部 Kneron 開發者。
三個核心承諾：
- 🎒 **零依賴**：Python runtime、KneronPLUS SDK、ffmpeg、yt-dlp、預置 `.nef` 模型全部內嵌
- ✈️ **零網路**：下載一次後完全離線可用（適合客戶現場 IT 鎖得死緊的場景）
- 🖱️ **零學習成本**：雙擊安裝 → 開啟 → Mock 模式 30 秒內跑出第一幀推論
對標產品：Docker Desktop、Ollama。
---
## 安裝（使用者）
### macOS（x86_64，beta）
1. 從內部 Gitea Releases 下載 `visiona-local.dmg`
2. 雙擊開啟 dmg → 把 `visionA-local.app` 拖到 `Applications/`
3. **第一次啟動**：因為未做程式碼簽章，Gatekeeper 會警告「來自未識別開發者」
- 在 Finder 中**右鍵點 `visionA-local.app` → 選「開啟」**（不是雙擊）
- 對話框出現「仍要開啟」時點確認
- 往後直接雙擊即可
4. **首次啟動會花 30–60 秒**解壓內嵌的 Python runtime 並離線安裝 wheels
這是預期行為，不是卡住。之後啟動只要幾秒
> 📁 資料目錄：`~/Library/Application Support/visiona-local/`
> 包含 log、lock、ipc-port、自上傳模型
### Windows / Linux
**Coming soon** — build script 已經寫好，等 CI runner 齊備後就會釋出。
- Windows：Inno Setup `.exe` installer
- Linux：`.AppImage` + udev rules（需 root 裝 `99-kneron.rules`）
---
## 系統需求
| 平台 | 最低版本 | 架構 |
|------|---------|------|
| macOS | 14 Sonoma | x86_64 ¹ |
| Windows | 10 1809 | x86_64 |
| Ubuntu | 22.04 | x86_64 |
¹ Apple Silicon 理論上可透過 Rosetta 2 執行，但**未經測試**。
**離線可用**：安裝後所有核心功能（包含 Python sidecar、推論、模型管理、攝影機、影片解碼）完全不需要網路。
---
## 功能總覽
### ✅ 有的功能
- **裝置管理**：USB 自動偵測 Kneron KL520 / KL720，10 秒內連線
- **攝影機推論**：MJPEG 串流 + 即時 overlay（首次延遲 ≤ 250ms，穩定後 ≤ 150ms）
- **Mock 模式**：零硬體入口，產品經理、SA 也能拿來說故事
- **模型管理**：8 個預置 `.nef` 模型（分類 / 偵測 / 臉辨）+ 自上傳切換
- **核心推論引擎**：image classification、object detection、face recognition
- **媒體推論**：支援圖片、影片檔、URL（內嵌 yt-dlp）
- **中英雙語**，跟隨系統 Dark Mode
### ❌ 不做的事（明確排除）
為了聚焦「個人工具」，以下功能從 `edge-ai-platform` 全數砍掉：
- ❌ Cluster（多裝置叢集）
- ❌ Relay / Tunnel（遠端連線、反向代理）
- ❌ 韌體燒錄（firmware flash）
- ❌ 系統列 Tray 常駐
- ❌ Auto-update
- ❌ Telemetry / 崩潰回報
- ❌ License 啟用、憑證簽章
- ❌ Mac App Store / Microsoft Store / Snap Store 上架
---
## 開發者區
### 專案結構
```
local_tool/
├── .autoflow/ PRD / 設計 / 架構 / 進度文件
├── server/ Go 1.26 後端（Gin + go:embed）
├── frontend/ Next.js 16 + React 19 + shadcn
├── visiona-local/ Wails 應用殼（installer）
├── payload/ 打包暫存區
├── vendor/ 第三方依賴（make vendor-sync 下載，不進 git）
├── dist/ 最終安裝檔（.dmg / .exe / .AppImage）
├── installer/ Inno Setup / AppImage script
├── scripts/ build 與維運腳本
└── Makefile
```
### 開發流程
```bash
# 1. 下載全部第三方依賴到 vendor/
make vendor-sync
# 2. 本機 build 並產出 dmg（macOS）
make dmg
# 查看所有可用 targets
make help
```
主要 make targets：
| Target | 作用 |
|--------|------|
| `vendor-sync` | 下載 python-build-standalone、wheels、ffmpeg、yt-dlp |
| `build-server` | 編譯 Go server binary（先 build frontend + embed） |
| `build-frontend` | pnpm build Next.js 靜態產物 |
| `payload-macos` | 準備 macOS payload（binary + python + wheels + ffmpeg + yt-dlp + 模型） |
| `wails-macos` | Wails build + ad-hoc codesign |
| `dmg` | 產出 `dist/visiona-local.dmg` |
| `exe` | Windows installer（需在 Windows runner 執行） |
| `appimage` | Linux AppImage（需在 Linux runner 執行） |
### 三方平台 build
| 平台 | 指令 | 執行環境 |
|------|------|---------|
| macOS | `make dmg` | 本機（Intel Mac） |
| Windows | `make exe` | Windows runner + Inno Setup 6 |
| Linux | `make appimage` | Ubuntu 22.04+ runner + appimagetool |
`vendor-*-windows` / `vendor-*-linux` 可在 macOS 上跑通（只有 `wails-*` 和最後一步 installer 需要對應平台）。
### 文件位置
所有設計與架構文件在 `.autoflow/`：
| 類型 | 路徑 |
|------|------|
| 產品需求（PRD） | [`.autoflow/02-prd/PRD.md`](./.autoflow/02-prd/PRD.md) |
| 設計規格 | [`.autoflow/03-design/`](./.autoflow/03-design/) |
| 架構設計 | [`.autoflow/04-architecture/design-doc.md`](./.autoflow/04-architecture/design-doc.md) |
| TDD | [`.autoflow/04-architecture/TDD.md`](./.autoflow/04-architecture/TDD.md) |
| 進度 | [`.autoflow/progress.md`](./.autoflow/progress.md) |
---
## 已知限制與 TODO
- 🔴 **ffmpeg 目前是 GPL build**（含 `--enable-gpl --enable-libx264`），由 `VISIONA_ALLOW_GPL_FFMPEG=1` flag 放行本地驗收，**發佈前等法務 review**
- 🟡 **Kneron 預置模型 re-distribution 授權**：開發階段假設可用，正式發佈前需與 Kneron 官方確認
- 🟡 **Windows / Linux 安裝檔**：build script 就緒，等 CI runner 齊備
- 🟡 **Apple Silicon** 未經測試（理論上 Rosetta 2 可跑）
- 🟡 **Linux Kneron USB vendor ID**：`installer/linux/99-kneron.rules` 需最終確認
- 🟡 程式碼簽章（Developer ID / EV cert）**不做**，使用者需手動繞過 Gatekeeper / SmartScreen
- 🟡 **無 auto-update**：新版需手動從 Gitea 下載
---
## 授權
**License: TBD**（內部工具 / MIT / proprietary 待定，發佈前確認）
### 第三方元件授權
| 元件 | 授權 | 備註 |
|------|------|------|
| ffmpeg | **GPL**（目前使用 GPL build） | ⚠️ 法務 review pending |
| yt-dlp | Unlicense | — |
| KneronPLUS SDK | Kneron 商用條款 | 再次確認 re-distribution 權利 |
| python-build-standalone | MPL 2.0 / PSFL | — |
| Python 標準函式庫 | PSFL | — |
| shadcn/ui | MIT | — |
| Next.js / React | MIT | — |
| Wails | MIT | — |
| Gin | MIT | — |
完整第三方授權清單於 `.autoflow/02-prd/PRD.md` §4.8。
---
## 致謝 / 起源
visionA-local 衍生自 Innovedus 內部專案 `edge-ai-platform`（原為部署於 EC2 + Docker 的多人共享平台）。本專案將其改造為單機桌面版本，聚焦「一個人帶一台筆電」的使用場景。
感謝 Kneron、python-build-standalone（astral-sh）、shadcn 等開源社群。

41
local-tool/frontend/.gitignore vendored Normal file
View File

@ -0,0 +1,41 @@
# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
# dependencies
/node_modules
/.pnp
.pnp.*
.yarn/*
!.yarn/patches
!.yarn/plugins
!.yarn/releases
!.yarn/versions
# testing
/coverage
# next.js
/.next/
/out/
# production
/build
# misc
.DS_Store
*.pem
# debug
npm-debug.log*
yarn-debug.log*
yarn-error.log*
.pnpm-debug.log*
# env files (can opt-in for committing if needed)
.env*
# vercel
.vercel
# typescript
*.tsbuildinfo
next-env.d.ts

0
local-tool/frontend/.gitkeep Normal file
View File

36
local-tool/frontend/README.md Normal file
View File

@ -0,0 +1,36 @@
This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
## Getting Started
First, run the development server:
```bash
npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev
```
Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
## Learn More
To learn more about Next.js, take a look at the following resources:
- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
## Deploy on Vercel
The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.

23
local-tool/frontend/components.json Normal file
View File

@ -0,0 +1,23 @@
{
"$schema": "https://ui.shadcn.com/schema.json",
"style": "new-york",
"rsc": true,
"tsx": true,
"tailwind": {
"config": "",
"css": "src/app/globals.css",
"baseColor": "neutral",
"cssVariables": true,
"prefix": ""
},
"iconLibrary": "lucide",
"rtl": false,
"aliases": {
"components": "@/components",
"utils": "@/lib/utils",
"ui": "@/components/ui",
"lib": "@/lib",
"hooks": "@/hooks"
},
"registries": {}
}

18
local-tool/frontend/eslint.config.mjs Normal file
View File

@ -0,0 +1,18 @@
import { defineConfig, globalIgnores } from "eslint/config";
import nextVitals from "eslint-config-next/core-web-vitals";
import nextTs from "eslint-config-next/typescript";
const eslintConfig = defineConfig([
...nextVitals,
...nextTs,
// Override default ignores of eslint-config-next.
globalIgnores([
// Default ignores of eslint-config-next:
".next/**",
"out/**",
"build/**",
"next-env.d.ts",
]),
]);
export default eslintConfig;

27
local-tool/frontend/next.config.ts Normal file
View File

@ -0,0 +1,27 @@
import type { NextConfig } from "next";
const isDev = process.env.NODE_ENV === "development";
const nextConfig: NextConfig = {
...(isDev
? {
async rewrites() {
return [
{
source: "/api/:path*",
destination: "http://localhost:3721/api/:path*",
},
{
source: "/ws/:path*",
destination: "http://localhost:3721/ws/:path*",
},
];
},
}
: {
output: "export",
trailingSlash: true,
}),
};
export default nextConfig;

45
local-tool/frontend/package.json Normal file
View File

@ -0,0 +1,45 @@
{
"name": "frontend",
"version": "0.1.0",
"private": true,
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start",
"lint": "eslint",
"test": "vitest run",
"test:watch": "vitest"
},
"dependencies": {
"class-variance-authority": "^0.7.1",
"clsx": "^2.1.1",
"driver.js": "^1.4.0",
"lucide-react": "^0.575.0",
"next": "16.1.6",
"next-themes": "^0.4.6",
"radix-ui": "^1.4.3",
"react": "19.2.3",
"react-dom": "19.2.3",
"recharts": "^3.7.0",
"sonner": "^2.0.7",
"tailwind-merge": "^3.5.0",
"zustand": "^5.0.11"
},
"devDependencies": {
"@tailwindcss/postcss": "^4",
"@testing-library/jest-dom": "^6.9.1",
"@testing-library/react": "^16.3.2",
"@types/node": "^20",
"@types/react": "^19",
"@types/react-dom": "^19",
"@vitejs/plugin-react": "^5.1.4",
"eslint": "^9",
"eslint-config-next": "16.1.6",
"jsdom": "^28.1.0",
"shadcn": "^3.8.5",
"tailwindcss": "^4",
"tw-animate-css": "^1.4.0",
"typescript": "^5",
"vitest": "^4.0.18"
}
}

9475
local-tool/frontend/pnpm-lock.yaml generated Normal file
View File

File diff suppressed because it is too large Load Diff

3
local-tool/frontend/pnpm-workspace.yaml Normal file
View File

@ -0,0 +1,3 @@
ignoredBuiltDependencies:
- sharp
- unrs-resolver

7
local-tool/frontend/postcss.config.mjs Normal file
View File

@ -0,0 +1,7 @@
const config = {
plugins: {
"@tailwindcss/postcss": {},
},
};
export default config;

1
local-tool/frontend/public/file.svg Normal file
View File

@ -0,0 +1 @@
<svg fill="none" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg"><path d="M14.5 13.5V5.41a1 1 0 0 0-.3-.7L9.8.29A1 1 0 0 0 9.08 0H1.5v13.5A2.5 2.5 0 0 0 4 16h8a2.5 2.5 0 0 0 2.5-2.5m-1.5 0v-7H8v-5H3v12a1 1 0 0 0 1 1h8a1 1 0 0 0 1-1M9.5 5V2.12L12.38 5zM5.13 5h-.62v1.25h2.12V5zm-.62 3h7.12v1.25H4.5zm.62 3h-.62v1.25h7.12V11z" clip-rule="evenodd" fill="#666" fill-rule="evenodd"/></svg>
Side by Side

After

Width:  |  Height:  |  Size: 391 B

1
local-tool/frontend/public/globe.svg Normal file
View File

@ -0,0 +1 @@
<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><g clip-path="url(#a)"><path fill-rule="evenodd" clip-rule="evenodd" d="M10.27 14.1a6.5 6.5 0 0 0 3.67-3.45q-1.24.21-2.7.34-.31 1.83-.97 3.1M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16m.48-1.52a7 7 0 0 1-.96 0H7.5a4 4 0 0 1-.84-1.32q-.38-.89-.63-2.08a40 40 0 0 0 3.92 0q-.25 1.2-.63 2.08a4 4 0 0 1-.84 1.31zm2.94-4.76q1.66-.15 2.95-.43a7 7 0 0 0 0-2.58q-1.3-.27-2.95-.43a18 18 0 0 1 0 3.44m-1.27-3.54a17 17 0 0 1 0 3.64 39 39 0 0 1-4.3 0 17 17 0 0 1 0-3.64 39 39 0 0 1 4.3 0m1.1-1.17q1.45.13 2.69.34a6.5 6.5 0 0 0-3.67-3.44q.65 1.26.98 3.1M8.48 1.5l.01.02q.41.37.84 1.31.38.89.63 2.08a40 40 0 0 0-3.92 0q.25-1.2.63-2.08a4 4 0 0 1 .85-1.32 7 7 0 0 1 .96 0m-2.75.4a6.5 6.5 0 0 0-3.67 3.44 29 29 0 0 1 2.7-.34q.31-1.83.97-3.1M4.58 6.28q-1.66.16-2.95.43a7 7 0 0 0 0 2.58q1.3.27 2.95.43a18 18 0 0 1 0-3.44m.17 4.71q-1.45-.12-2.69-.34a6.5 6.5 0 0 0 3.67 3.44q-.65-1.27-.98-3.1" fill="#666"/></g><defs><clipPath id="a"><path fill="#fff" d="M0 0h16v16H0z"/></clipPath></defs></svg>
Side by Side

After

Width:  |  Height:  |  Size: 1.0 KiB

1
local-tool/frontend/public/next.svg Normal file
View File

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 394 80"><path fill="#000" d="M262 0h68.5v12.7h-27.2v66.6h-13.6V12.7H262V0ZM149 0v12.7H94v20.4h44.3v12.6H94v21h55v12.6H80.5V0h68.7zm34.3 0h-17.8l63.8 79.4h17.9l-32-39.7 32-39.6h-17.9l-23 28.6-23-28.6zm18.3 56.7-9-11-27.1 33.7h17.8l18.3-22.7z"/><path fill="#000" d="M81 79.3 17 0H0v79.3h13.6V17l50.2 62.3H81Zm252.6-.4c-1 0-1.8-.4-2.5-1s-1.1-1.6-1.1-2.6.3-1.8 1-2.5 1.6-1 2.6-1 1.8.3 2.5 1a3.4 3.4 0 0 1 .6 4.3 3.7 3.7 0 0 1-3 1.8zm23.2-33.5h6v23.3c0 2.1-.4 4-1.3 5.5a9.1 9.1 0 0 1-3.8 3.5c-1.6.8-3.5 1.3-5.7 1.3-2 0-3.7-.4-5.3-1s-2.8-1.8-3.7-3.2c-.9-1.3-1.4-3-1.4-5h6c.1.8.3 1.6.7 2.2s1 1.2 1.6 1.5c.7.4 1.5.5 2.4.5 1 0 1.8-.2 2.4-.6a4 4 0 0 0 1.6-1.8c.3-.8.5-1.8.5-3V45.5zm30.9 9.1a4.4 4.4 0 0 0-2-3.3 7.5 7.5 0 0 0-4.3-1.1c-1.3 0-2.4.2-3.3.5-.9.4-1.6 1-2 1.6a3.5 3.5 0 0 0-.3 4c.3.5.7.9 1.3 1.2l1.8 1 2 .5 3.2.8c1.3.3 2.5.7 3.7 1.2a13 13 0 0 1 3.2 1.8 8.1 8.1 0 0 1 3 6.5c0 2-.5 3.7-1.5 5.1a10 10 0 0 1-4.4 3.5c-1.8.8-4.1 1.2-6.8 1.2-2.6 0-4.9-.4-6.8-1.2-2-.8-3.4-2-4.5-3.5a10 10 0 0 1-1.7-5.6h6a5 5 0 0 0 3.5 4.6c1 .4 2.2.6 3.4.6 1.3 0 2.5-.2 3.5-.6 1-.4 1.8-1 2.4-1.7a4 4 0 0 0 .8-2.4c0-.9-.2-1.6-.7-2.2a11 11 0 0 0-2.1-1.4l-3.2-1-3.8-1c-2.8-.7-5-1.7-6.6-3.2a7.2 7.2 0 0 1-2.4-5.7 8 8 0 0 1 1.7-5 10 10 0 0 1 4.3-3.5c2-.8 4-1.2 6.4-1.2 2.3 0 4.4.4 6.2 1.2 1.8.8 3.2 2 4.3 3.4 1 1.4 1.5 3 1.5 5h-5.8z"/></svg>
Side by Side

After

Width:  |  Height:  |  Size: 1.3 KiB

1
local-tool/frontend/public/vercel.svg Normal file
View File

@ -0,0 +1 @@
<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1155 1000"><path d="m577.3 0 577.4 1000H0z" fill="#fff"/></svg>
Side by Side

After

Width:  |  Height:  |  Size: 128 B

1
local-tool/frontend/public/window.svg Normal file
View File

@ -0,0 +1 @@
<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.5 2.5h13v10a1 1 0 0 1-1 1h-11a1 1 0 0 1-1-1zM0 1h16v11.5a2.5 2.5 0 0 1-2.5 2.5h-11A2.5 2.5 0 0 1 0 12.5zm3.75 4.5a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5M7 4.75a.75.75 0 1 1-1.5 0 .75.75 0 0 1 1.5 0m1.75.75a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5" fill="#666"/></svg>
Side by Side

After

Width:  |  Height:  |  Size: 385 B

132
local-tool/frontend/src/app/devices/[id]/device-detail-client.tsx Normal file
View File

@ -0,0 +1,132 @@
'use client';
import { useEffect } from 'react';
import Link from 'next/link';
import { useResolvedParams } from '@/hooks/use-resolved-params';
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
import { Button } from '@/components/ui/button';
import { Separator } from '@/components/ui/separator';
import { DeviceStatusBadge } from '@/components/devices/device-status';
import { DeviceHealthCard } from '@/components/devices/device-health-card';
import { DeviceConnectionLog } from '@/components/devices/device-connection-log';
import { DeviceSettingsCard } from '@/components/devices/device-settings-card';
import { useDeviceStore } from '@/stores/device-store';
import { useDevicePreferencesStore } from '@/stores/device-preferences-store';
import { useTranslation } from '@/lib/i18n';
export default function DeviceDetailClient() {
const { t } = useTranslation();
const { id } = useResolvedParams();
const { selectedDevice, fetchDevice, connectDevice, disconnectDevice } = useDeviceStore();
const prefs = useDevicePreferencesStore((s) => s.getPreferences(id));
useEffect(() => {
if (id) {
fetchDevice(id);
}
}, [id, fetchDevice]);
if (!selectedDevice) {
return (
<div className="space-y-4">
<div className="h-8 w-48 animate-pulse rounded bg-muted" />
<div className="h-48 animate-pulse rounded-lg border bg-muted" />
</div>
);
}
const isConnected = selectedDevice.status === 'connected' || selectedDevice.status === 'flashing' || selectedDevice.status === 'inferencing';
const displayName = prefs.alias || selectedDevice.name;
return (
<div className="space-y-6">
<div className="flex items-center gap-2">
<Link href="/devices">
<Button variant="ghost" size="sm">{'← ' + t('common.back')}</Button>
</Link>
</div>
<div className="flex items-start justify-between">
<div>
<h1 className="text-2xl font-bold">{displayName}</h1>
{prefs.alias && (
<p className="text-sm text-muted-foreground">{selectedDevice.name}</p>
)}
<DeviceStatusBadge status={selectedDevice.status} />
</div>
<div className="flex gap-2">
{isConnected ? (
<>
<Link href={`/workspace/${id}`}>
<Button variant="outline" data-tour-id="open-workspace-btn">{t('devices.detail.openWorkspace')}</Button>
</Link>
<Button variant="ghost" onClick={() => disconnectDevice(id)}>
{t('common.disconnect')}
</Button>
</>
) : (
<Button onClick={() => connectDevice(id)}>{t('common.connect')}</Button>
)}
</div>
</div>
<Separator />
<div className="grid grid-cols-1 gap-4 md:grid-cols-2">
<Card>
<CardHeader>
<CardTitle className="text-base">{t('devices.detail.deviceInfo')}</CardTitle>
</CardHeader>
<CardContent className="space-y-3">
<div className="flex justify-between">
<span className="text-muted-foreground">{t('devices.detail.id')}</span>
<span className="font-mono text-sm">{selectedDevice.id}</span>
</div>
<div className="flex justify-between">
<span className="text-muted-foreground">{t('devices.detail.type')}</span>
<span>{selectedDevice.type}</span>
</div>
<div className="flex justify-between">
<span className="text-muted-foreground">{t('devices.detail.firmware')}</span>
<span>{selectedDevice.firmwareVersion || t('common.na')}</span>
</div>
<div className="flex justify-between">
<span className="text-muted-foreground">{t('devices.detail.port')}</span>
<span className="font-mono text-sm">{selectedDevice.port}</span>
</div>
</CardContent>
</Card>
<Card>
<CardHeader>
<CardTitle className="text-base">{t('devices.detail.modelStatus')}</CardTitle>
</CardHeader>
<CardContent>
{selectedDevice.flashedModel ? (
<div className="space-y-3">
<div className="flex justify-between">
<span className="text-muted-foreground">{t('devices.flashedModel')}</span>
<span className="font-medium">{selectedDevice.flashedModel}</span>
</div>
<p className="text-sm text-muted-foreground">
{t('devices.detail.readyForInference')}
</p>
</div>
) : (
<p className="text-sm text-muted-foreground">
{t('devices.detail.noModelFlashed')}
</p>
)}
</CardContent>
</Card>
</div>
<div className="grid grid-cols-1 gap-4 md:grid-cols-2">
<DeviceHealthCard device={selectedDevice} />
<DeviceConnectionLog deviceId={id} />
</div>
<DeviceSettingsCard deviceId={id} />
</div>
);
}

11
local-tool/frontend/src/app/devices/[id]/page.tsx Normal file
View File

@ -0,0 +1,11 @@
import DeviceDetailClient from './device-detail-client';
// Provide a placeholder param for Next.js static export.
// Actual routing is handled by Go SPA fallback — all dynamic paths serve index.html.
export function generateStaticParams() {
return [{ id: '_' }];
}
export default function DeviceDetailPage() {
return <DeviceDetailClient />;
}

36
local-tool/frontend/src/app/devices/page.tsx Normal file
View File

@ -0,0 +1,36 @@
'use client';
import { useEffect } from 'react';
import { useDeviceStore } from '@/stores/device-store';
import { useDeviceEvents } from '@/hooks/use-device-events';
import { DeviceList } from '@/components/devices/device-list';
import { Button } from '@/components/ui/button';
import { RefreshCw } from 'lucide-react';
import { useTranslation } from '@/lib/i18n';
export default function DevicesPage() {
const { t } = useTranslation();
const { devices, loading, scanning, fetchDevices, scanDevices } = useDeviceStore();
useDeviceEvents();
useEffect(() => {
fetchDevices();
}, [fetchDevices]);
return (
<div className="space-y-6">
<div className="flex items-center justify-between">
<div>
<h1 className="text-2xl font-bold">{t('devices.title')}</h1>
<p className="text-muted-foreground">{t('devices.subtitle')}</p>
</div>
<Button onClick={scanDevices} disabled={scanning} variant="outline" data-tour-id="scan-devices-btn">
<RefreshCw className={`mr-2 h-4 w-4 ${scanning ? 'animate-spin' : ''}`} />
{scanning ? t('devices.scanning') : t('devices.scan')}
</Button>
</div>
<DeviceList devices={devices} loading={loading} />
</div>
);
}

BIN
local-tool/frontend/src/app/favicon.ico Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 25 KiB

224
local-tool/frontend/src/app/globals.css Normal file
View File

@ -0,0 +1,224 @@
@import "tailwindcss";
@import "tw-animate-css";
@import "shadcn/tailwind.css";
@custom-variant dark (&:is(.dark *));
@theme inline {
--color-background: var(--background);
--color-foreground: var(--foreground);
--font-sans: var(--font-geist-sans);
--font-mono: var(--font-geist-mono);
--color-sidebar-ring: var(--sidebar-ring);
--color-sidebar-border: var(--sidebar-border);
--color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
--color-sidebar-accent: var(--sidebar-accent);
--color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
--color-sidebar-primary: var(--sidebar-primary);
--color-sidebar-foreground: var(--sidebar-foreground);
--color-sidebar: var(--sidebar);
--color-chart-5: var(--chart-5);
--color-chart-4: var(--chart-4);
--color-chart-3: var(--chart-3);
--color-chart-2: var(--chart-2);
--color-chart-1: var(--chart-1);
--color-ring: var(--ring);
--color-input: var(--input);
--color-border: var(--border);
--color-destructive: var(--destructive);
--color-accent-foreground: var(--accent-foreground);
--color-accent: var(--accent);
--color-muted-foreground: var(--muted-foreground);
--color-muted: var(--muted);
--color-secondary-foreground: var(--secondary-foreground);
--color-secondary: var(--secondary);
--color-primary-foreground: var(--primary-foreground);
--color-primary: var(--primary);
--color-popover-foreground: var(--popover-foreground);
--color-popover: var(--popover);
--color-card-foreground: var(--card-foreground);
--color-card: var(--card);
--radius-sm: calc(var(--radius) - 4px);
--radius-md: calc(var(--radius) - 2px);
--radius-lg: var(--radius);
--radius-xl: calc(var(--radius) + 4px);
--radius-2xl: calc(var(--radius) + 8px);
--radius-3xl: calc(var(--radius) + 12px);
--radius-4xl: calc(var(--radius) + 16px);
}
:root {
--radius: 0.625rem;
--background: oklch(1 0 0);
--foreground: oklch(0.145 0 0);
--card: oklch(1 0 0);
--card-foreground: oklch(0.145 0 0);
--popover: oklch(1 0 0);
--popover-foreground: oklch(0.145 0 0);
--primary: oklch(0.205 0 0);
--primary-foreground: oklch(0.985 0 0);
--secondary: oklch(0.97 0 0);
--secondary-foreground: oklch(0.205 0 0);
--muted: oklch(0.97 0 0);
--muted-foreground: oklch(0.556 0 0);
--accent: oklch(0.97 0 0);
--accent-foreground: oklch(0.205 0 0);
--destructive: oklch(0.577 0.245 27.325);
--border: oklch(0.922 0 0);
--input: oklch(0.922 0 0);
--ring: oklch(0.708 0 0);
--chart-1: oklch(0.646 0.222 41.116);
--chart-2: oklch(0.6 0.118 184.704);
--chart-3: oklch(0.398 0.07 227.392);
--chart-4: oklch(0.828 0.189 84.429);
--chart-5: oklch(0.769 0.188 70.08);
--sidebar: oklch(0.985 0 0);
--sidebar-foreground: oklch(0.145 0 0);
--sidebar-primary: oklch(0.205 0 0);
--sidebar-primary-foreground: oklch(0.985 0 0);
--sidebar-accent: oklch(0.97 0 0);
--sidebar-accent-foreground: oklch(0.205 0 0);
--sidebar-border: oklch(0.922 0 0);
--sidebar-ring: oklch(0.708 0 0);
}
.dark {
--background: oklch(0.145 0 0);
--foreground: oklch(0.985 0 0);
--card: oklch(0.205 0 0);
--card-foreground: oklch(0.985 0 0);
--popover: oklch(0.205 0 0);
--popover-foreground: oklch(0.985 0 0);
--primary: oklch(0.922 0 0);
--primary-foreground: oklch(0.205 0 0);
--secondary: oklch(0.269 0 0);
--secondary-foreground: oklch(0.985 0 0);
--muted: oklch(0.269 0 0);
--muted-foreground: oklch(0.708 0 0);
--accent: oklch(0.269 0 0);
--accent-foreground: oklch(0.985 0 0);
--destructive: oklch(0.704 0.191 22.216);
--border: oklch(1 0 0 / 10%);
--input: oklch(1 0 0 / 15%);
--ring: oklch(0.556 0 0);
--chart-1: oklch(0.488 0.243 264.376);
--chart-2: oklch(0.696 0.17 162.48);
--chart-3: oklch(0.769 0.188 70.08);
--chart-4: oklch(0.627 0.265 303.9);
--chart-5: oklch(0.645 0.246 16.439);
--sidebar: oklch(0.205 0 0);
--sidebar-foreground: oklch(0.985 0 0);
--sidebar-primary: oklch(0.488 0.243 264.376);
--sidebar-primary-foreground: oklch(0.985 0 0);
--sidebar-accent: oklch(0.269 0 0);
--sidebar-accent-foreground: oklch(0.985 0 0);
--sidebar-border: oklch(1 0 0 / 10%);
--sidebar-ring: oklch(0.556 0 0);
}
@layer base {
* {
@apply border-border outline-ring/50;
}
body {
@apply bg-background text-foreground;
}
}
/* driver.js theme overrides — integrates with shadcn/ui CSS variables */
.driver-popover {
background-color: var(--popover) !important;
color: var(--popover-foreground) !important;
border: 1px solid var(--border) !important;
border-radius: var(--radius) !important;
box-shadow: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1) !important;
}
.driver-popover .driver-popover-title {
font-size: 0.95rem !important;
font-weight: 600 !important;
color: var(--popover-foreground) !important;
}
.driver-popover .driver-popover-title .driver-step-counter {
font-weight: 400 !important;
font-size: 0.8rem !important;
color: var(--muted-foreground) !important;
margin-left: 4px;
}
.driver-popover .driver-popover-description {
font-size: 0.85rem !important;
color: var(--muted-foreground) !important;
}
.driver-popover .driver-popover-close-btn {
color: var(--muted-foreground) !important;
}
.driver-popover .driver-popover-close-btn:hover {
color: var(--popover-foreground) !important;
}
.driver-popover-navigation-btns {
gap: 6px;
}
.driver-popover .driver-popover-prev-btn {
background-color: var(--secondary) !important;
color: var(--secondary-foreground) !important;
border: 1px solid var(--border) !important;
border-radius: calc(var(--radius) - 2px) !important;
font-size: 0.8rem !important;
padding: 4px 12px !important;
text-shadow: none !important;
}
.driver-popover .driver-popover-next-btn {
background-color: var(--primary) !important;
color: var(--primary-foreground) !important;
border: none !important;
border-radius: calc(var(--radius) - 2px) !important;
font-size: 0.8rem !important;
padding: 4px 12px !important;
text-shadow: none !important;
}
.driver-popover .driver-popover-prev-btn:hover {
opacity: 0.9;
}
.driver-popover .driver-popover-next-btn:hover {
opacity: 0.9;
}
.driver-overlay {
background-color: rgb(0 0 0 / 0.5) !important;
}
.driver-popover .driver-btn-disabled {
opacity: 0.4 !important;
cursor: not-allowed !important;
pointer-events: none !important;
}
.driver-popover .driver-pending-hint {
color: var(--chart-1) !important;
font-size: 0.8rem !important;
font-weight: 500;
}
.driver-popover-navigation-btns .driver-exit-tour {
font-size: 0.75rem;
color: var(--muted-foreground);
background: none;
border: none;
cursor: pointer;
padding: 4px 8px;
margin-right: auto;
transition: color 0.15s;
}
.driver-popover-navigation-btns .driver-exit-tour:hover {
color: var(--destructive);
}

54
local-tool/frontend/src/app/layout.tsx Normal file
View File

@ -0,0 +1,54 @@
import type { Metadata } from "next";
import { Geist, Geist_Mono } from "next/font/google";
import "./globals.css";
import { Sidebar } from "@/components/layout/sidebar";
import { Header } from "@/components/layout/header";
import { Toaster } from "@/components/ui/sonner";
import { ThemeSync } from "@/components/theme-sync";
import { LangSync } from "@/components/lang-sync";
import { StoreHydration } from "@/components/store-hydration";
import { GuidedTour } from "@/components/guided-tour";
const geistSans = Geist({
variable: "--font-geist-sans",
subsets: ["latin"],
});
const geistMono = Geist_Mono({
variable: "--font-geist-mono",
subsets: ["latin"],
});
export const metadata: Metadata = {
title: "visionA-local",
description: "Local-first Edge AI development tool",
};
export default function RootLayout({
children,
}: Readonly<{
children: React.ReactNode;
}>) {
return (
<html lang="en">
<body
className={`${geistSans.variable} ${geistMono.variable} antialiased`}
>
<div className="flex h-screen">
<Sidebar />
<div className="flex flex-1 flex-col overflow-hidden">
<Header />
<main className="flex-1 overflow-auto p-6">
{children}
</main>
</div>
</div>
<StoreHydration />
<ThemeSync />
<LangSync />
<GuidedTour />
<Toaster richColors position="bottom-right" />
</body>
</html>
);
}

45
local-tool/frontend/src/app/models/[id]/model-detail-client.tsx Normal file
View File

@ -0,0 +1,45 @@
'use client';
import { useEffect } from 'react';
import { useModelStore } from '@/stores/model-store';
import { ModelDetail } from '@/components/models/model-detail';
import { Button } from '@/components/ui/button';
import Link from 'next/link';
import { useResolvedParams } from '@/hooks/use-resolved-params';
import { useTranslation } from '@/lib/i18n';
export default function ModelDetailClient() {
const { id } = useResolvedParams();
const { selectedModel, loading, fetchModel } = useModelStore();
const { t } = useTranslation();
useEffect(() => {
if (id) {
fetchModel(id);
}
}, [id, fetchModel]);
if (loading || !selectedModel) {
return (
<div className="space-y-4">
<div className="h-8 w-48 animate-pulse rounded bg-muted" />
<div className="h-4 w-96 animate-pulse rounded bg-muted" />
<div className="grid grid-cols-2 gap-4">
<div className="h-48 animate-pulse rounded-lg border bg-muted" />
<div className="h-48 animate-pulse rounded-lg border bg-muted" />
</div>
</div>
);
}
return (
<div className="space-y-4">
<Link href="/models">
<Button variant="ghost" size="sm">
{'← ' + t('common.back')}
</Button>
</Link>
<ModelDetail model={selectedModel} />
</div>
);
}

11
local-tool/frontend/src/app/models/[id]/page.tsx Normal file
View File

@ -0,0 +1,11 @@
import ModelDetailClient from './model-detail-client';
// Provide a placeholder param for Next.js static export.
// Actual routing is handled by Go SPA fallback — all dynamic paths serve index.html.
export function generateStaticParams() {
return [{ id: '_' }];
}
export default function ModelDetailPage() {
return <ModelDetailClient />;
}

69
local-tool/frontend/src/app/models/page.tsx Normal file
View File

@ -0,0 +1,69 @@
'use client';
import { useEffect, useState } from 'react';
import { useModelStore } from '@/stores/model-store';
import { ModelGrid } from '@/components/models/model-grid';
import { ModelFilters } from '@/components/models/model-filters';
import { ModelUploadDialog } from '@/components/models/model-upload-dialog';
import { ModelComparisonDialog } from '@/components/models/model-comparison-dialog';
import { Button } from '@/components/ui/button';
import { useTranslation } from '@/lib/i18n';
export default function ModelsPage() {
const { models, loading, fetchModels, comparisonIds, clearComparison } = useModelStore();
const [compareMode, setCompareMode] = useState(false);
const [showComparison, setShowComparison] = useState(false);
const { t } = useTranslation();
useEffect(() => {
fetchModels();
}, [fetchModels]);
return (
<div className="space-y-6">
<div className="flex items-center justify-between">
<div>
<h1 className="text-2xl font-bold">{t('models.title')}</h1>
<p className="text-muted-foreground">{t('models.subtitle')}</p>
</div>
<div className="flex gap-2">
<Button
variant={compareMode ? 'secondary' : 'outline'}
onClick={() => {
setCompareMode(!compareMode);
if (compareMode) clearComparison();
}}
>
{compareMode ? t('models.exitCompare') : t('models.compareModels')}
</Button>
<ModelUploadDialog />
</div>
</div>
<ModelFilters />
<ModelGrid models={models} loading={loading} compareMode={compareMode} />
{comparisonIds.length > 0 && (
<div className="fixed bottom-6 left-1/2 -translate-x-1/2 z-50 flex items-center gap-4 rounded-lg border bg-card px-6 py-3 shadow-lg">
<span className="text-sm font-medium">
{t('models.comparison.selected', { n: comparisonIds.length })}
</span>
<Button
size="sm"
disabled={comparisonIds.length < 2}
onClick={() => setShowComparison(true)}
>
{t('models.comparison.compare')}
</Button>
<Button size="sm" variant="ghost" onClick={clearComparison}>
{t('models.comparison.clear')}
</Button>
</div>
)}
<ModelComparisonDialog
open={showComparison}
onOpenChange={setShowComparison}
/>
</div>
);
}

87
local-tool/frontend/src/app/page.tsx Normal file
View File

@ -0,0 +1,87 @@
'use client';
import { useEffect } from 'react';
import Link from 'next/link';
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
import { Button } from '@/components/ui/button';
import { useModelStore } from '@/stores/model-store';
import { useDeviceStore } from '@/stores/device-store';
import { useActivityStore } from '@/stores/activity-store';
import { StatCard } from '@/components/dashboard/stat-card';
import { ActivityTimeline } from '@/components/dashboard/activity-timeline';
import { ConnectedDevicesList } from '@/components/dashboard/connected-devices-list';
import { Boxes, Cable, Zap, Upload } from 'lucide-react';
import { useTranslation } from '@/lib/i18n';
import { OnboardingDialog } from '@/components/onboarding-dialog';
export default function DashboardPage() {
const { t } = useTranslation();
const { models, fetchModels } = useModelStore();
const { devices, fetchDevices } = useDeviceStore();
const activities = useActivityStore((s) => s.activities);
useEffect(() => {
fetchModels();
fetchDevices();
}, [fetchModels, fetchDevices]);
const connectedCount = devices.filter(
(d) => d.status === 'connected' || d.status === 'flashing' || d.status === 'inferencing',
).length;
const flashCount = activities.filter((a) => a.type === 'flash_complete').length;
return (
<div className="space-y-6">
<OnboardingDialog />
<div>
<h1 className="text-2xl font-bold">{t('dashboard.title')}</h1>
<p className="text-muted-foreground">{t('dashboard.subtitle')}</p>
</div>
<div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4">
<StatCard title={t('dashboard.models')} value={models.length} icon={Boxes} iconColor="text-blue-600" />
<StatCard title={t('dashboard.devices')} value={devices.length} icon={Cable} iconColor="text-purple-600" />
<StatCard
title={t('dashboard.connected')}
value={connectedCount}
icon={Cable}
iconColor="text-green-600"
/>
<StatCard title={t('dashboard.flashes')} value={flashCount} icon={Zap} iconColor="text-yellow-600" />
</div>
<div className="grid grid-cols-1 gap-6 lg:grid-cols-2">
<ConnectedDevicesList />
<ActivityTimeline />
</div>
<Card>
<CardHeader>
<CardTitle className="text-base">{t('dashboard.quickActions')}</CardTitle>
</CardHeader>
<CardContent>
<div className="flex flex-wrap gap-3">
<Link href="/models">
<Button variant="outline">
<Boxes className="mr-2 h-4 w-4" />
{t('dashboard.browseModels')}
</Button>
</Link>
<Link href="/devices">
<Button variant="outline">
<Cable className="mr-2 h-4 w-4" />
{t('dashboard.manageDevices')}
</Button>
</Link>
<Link href="/models">
<Button>
<Upload className="mr-2 h-4 w-4" />
{t('dashboard.uploadModel')}
</Button>
</Link>
</div>
</CardContent>
</Card>
</div>
);
}

284
local-tool/frontend/src/app/settings/page.tsx Normal file
View File

@ -0,0 +1,284 @@
'use client';
import { useState, useEffect } from 'react';
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
import { Input } from '@/components/ui/input';
import { Label } from '@/components/ui/label';
import {
Select,
SelectContent,
SelectItem,
SelectTrigger,
SelectValue,
} from '@/components/ui/select';
import { Button } from '@/components/ui/button';
import { Separator } from '@/components/ui/separator';
import { Tabs, TabsList, TabsTrigger, TabsContent } from '@/components/ui/tabs';
import { useSettingsStore } from '@/stores/settings-store';
import { getApiBaseUrl, getWsBaseUrl, getBackendUrl, setBackendUrl } from '@/lib/constants';
import { showSuccess } from '@/lib/toast';
import { useTranslation } from '@/lib/i18n';
import { ServerLogViewer } from '@/components/server-log-viewer';
import { ServerStatusDashboard } from '@/components/server-status-dashboard';
// TODO(M2+): read these values from the backend via /api/system/info once that
// endpoint exists. For M2 we display placeholders so the Settings UI structure
// and i18n bindings can be validated without backend changes.
const DATA_DIR_PLACEHOLDER = '~/Library/Application Support/visiona-local';
const MODELS_UPLOAD_PATH_PLACEHOLDER = '~/Library/Application Support/visiona-local/models';
const BUNDLED_PYTHON_PLACEHOLDER = 'Bundled Python 3.11 (ready)';
export default function SettingsPage() {
const { t } = useTranslation();
const { theme, language, setLanguage, resetToDefaults } = useSettingsStore();
const [backendUrlInput, setBackendUrlInput] = useState('');
const [apiUrl, setApiUrl] = useState('');
const [wsUrl, setWsUrl] = useState('');
useEffect(() => {
setBackendUrlInput(getBackendUrl());
setApiUrl(getApiBaseUrl());
setWsUrl(getWsBaseUrl());
}, []);
function handleSaveBackendUrl() {
setBackendUrl(backendUrlInput);
setApiUrl(getApiBaseUrl());
setWsUrl(getWsBaseUrl());
showSuccess(t('settings.backendUrlSaved'));
}
// Derived port for Advanced tab — parsed from backend URL if possible.
let serverPortDisplay = '3721';
try {
const u = new URL(apiUrl || 'http://localhost:3721');
if (u.port) serverPortDisplay = u.port;
} catch {
/* ignore */
}
return (
<div className="space-y-6">
<div>
<h1 className="text-2xl font-bold">{t('settings.title')}</h1>
<p className="text-muted-foreground">{t('settings.subtitle')}</p>
</div>
<Tabs defaultValue="general" className="w-full">
<TabsList>
<TabsTrigger value="general">{t('settings.tabs.general')}</TabsTrigger>
<TabsTrigger value="hardware">{t('settings.tabs.hardware')}</TabsTrigger>
<TabsTrigger value="models">{t('settings.tabs.models')}</TabsTrigger>
<TabsTrigger value="advanced">{t('settings.tabs.advanced')}</TabsTrigger>
</TabsList>
{/* ─────────── General ─────────── */}
<TabsContent value="general" className="space-y-6">
<Card>
<CardHeader>
<CardTitle className="text-base">{t('settings.general.title')}</CardTitle>
</CardHeader>
<CardContent className="space-y-6">
<div className="space-y-2">
<Label>{t('settings.general.language')}</Label>
<Select value={language} onValueChange={(v) => setLanguage(v as 'zh-TW' | 'en')}>
<SelectTrigger className="w-60">
<SelectValue />
</SelectTrigger>
<SelectContent>
<SelectItem value="zh-TW">{t('settings.languageZhTW')}</SelectItem>
<SelectItem value="en">{t('settings.languageEn')}</SelectItem>
</SelectContent>
</Select>
<p className="text-xs text-muted-foreground">
{t('settings.general.languageRestartHint')}
</p>
</div>
<Separator />
<div className="space-y-2">
<Label>{t('settings.general.theme')}</Label>
<Input
value={
theme === 'dark'
? `${t('settings.general.themeFollowSystem')} — ${t('settings.general.themeCurrentDark')}`
: `${t('settings.general.themeFollowSystem')} — ${t('settings.general.themeCurrentLight')}`
}
readOnly
className="bg-muted w-80"
/>
<p className="text-xs text-muted-foreground">
{t('settings.general.themeFollowSystemHint')}
</p>
</div>
<Separator />
<div className="space-y-2">
<Label>{t('settings.general.dataDirectory')}</Label>
<Input value={DATA_DIR_PLACEHOLDER} readOnly className="bg-muted font-mono text-sm" />
<p className="text-xs text-muted-foreground">
{t('settings.general.dataDirectoryHint')}
</p>
</div>
</CardContent>
</Card>
</TabsContent>
{/* ─────────── Hardware ─────────── */}
<TabsContent value="hardware" className="space-y-6">
<Card>
<CardHeader>
<CardTitle className="text-base">{t('settings.hardware.title')}</CardTitle>
</CardHeader>
<CardContent className="space-y-6">
<div className="space-y-2">
<Label>{t('settings.hardware.runtimeMode')}</Label>
{/* TODO(M2+): wire up to backend mock/real toggle endpoint */}
<Select value="mock" disabled>
<SelectTrigger className="w-60">
<SelectValue />
</SelectTrigger>
<SelectContent>
<SelectItem value="mock">{t('settings.hardware.runtimeModeMock')}</SelectItem>
<SelectItem value="real">{t('settings.hardware.runtimeModeReal')}</SelectItem>
</SelectContent>
</Select>
<p className="text-xs text-muted-foreground">
{t('settings.hardware.runtimeModeHint')}
</p>
</div>
<Separator />
<div className="space-y-2">
<Label>{t('settings.hardware.pythonMode')}</Label>
<Input value={BUNDLED_PYTHON_PLACEHOLDER} readOnly className="bg-muted w-80" />
<p className="text-xs text-muted-foreground">
{t('settings.hardware.pythonModeHint')}
</p>
</div>
</CardContent>
</Card>
</TabsContent>
{/* ─────────── Models ─────────── */}
<TabsContent value="models" className="space-y-6">
<Card>
<CardHeader>
<CardTitle className="text-base">{t('settings.models.title')}</CardTitle>
</CardHeader>
<CardContent className="space-y-6">
<div className="space-y-2">
<Label>{t('settings.models.presetModels')}</Label>
{/* TODO(M2+): fetch /api/models and list preset models here */}
<p className="text-sm text-muted-foreground">
{t('settings.models.presetModelsEmpty')}
</p>
</div>
<Separator />
<div className="space-y-2">
<Label>{t('settings.models.uploadPath')}</Label>
<Input
value={MODELS_UPLOAD_PATH_PLACEHOLDER}
readOnly
className="bg-muted font-mono text-sm"
/>
<p className="text-xs text-muted-foreground">
{t('settings.models.uploadPathHint')}
</p>
</div>
</CardContent>
</Card>
</TabsContent>
{/* ─────────── Advanced ─────────── */}
<TabsContent value="advanced" className="space-y-6">
<Card>
<CardHeader>
<CardTitle className="text-base">{t('settings.serverConfig')}</CardTitle>
</CardHeader>
<CardContent className="space-y-4">
<div className="space-y-2">
<Label>{t('settings.backendUrl')}</Label>
<div className="flex gap-2">
<Input
value={backendUrlInput}
onChange={(e) => setBackendUrlInput(e.target.value)}
placeholder={t('settings.backendUrlPlaceholder')}
className="flex-1"
/>
<Button onClick={handleSaveBackendUrl} size="sm">
{t('settings.saveBackendUrl')}
</Button>
</div>
<p className="text-xs text-muted-foreground">
{t('settings.backendUrlHint')}
</p>
</div>
<Separator />
<div className="space-y-2">
<Label>{t('settings.hardware.serverPort')}</Label>
<Input value={serverPortDisplay} readOnly className="bg-muted w-32" />
<p className="text-xs text-muted-foreground">
{t('settings.hardware.serverPortHint')}
</p>
</div>
<div className="space-y-2">
<Label>{t('settings.apiUrl')}</Label>
<Input value={apiUrl} readOnly className="bg-muted" />
</div>
<div className="space-y-2">
<Label>{t('settings.wsUrl')}</Label>
<Input value={wsUrl} readOnly className="bg-muted" />
</div>
</CardContent>
</Card>
<ServerStatusDashboard />
<ServerLogViewer />
<Card>
<CardHeader>
<CardTitle className="text-base">{t('settings.advanced.about')}</CardTitle>
</CardHeader>
<CardContent className="space-y-3">
<div className="flex justify-between text-sm">
<span className="text-muted-foreground">{t('settings.versionLabel')}</span>
<span className="font-medium">v0.1.0</span>
</div>
<div className="flex justify-between text-sm">
<span className="text-muted-foreground">{t('settings.platform')}</span>
<span className="font-medium">visionA Local</span>
</div>
</CardContent>
</Card>
<Card>
<CardHeader>
<CardTitle className="text-base">{t('settings.advanced.resetAll')}</CardTitle>
</CardHeader>
<CardContent className="space-y-3">
<p className="text-xs text-muted-foreground">
{t('settings.advanced.resetAllHint')}
</p>
<Button
variant="outline"
onClick={() => {
resetToDefaults();
showSuccess(t('settings.resetSuccess'));
}}
>
{t('settings.resetToDefaults')}
</Button>
</CardContent>
</Card>
</TabsContent>
</Tabs>
</div>
);
}

11
local-tool/frontend/src/app/workspace/[deviceId]/page.tsx Normal file
View File

@ -0,0 +1,11 @@
import WorkspaceClient from './workspace-client';
// Provide a placeholder param for Next.js static export.
// Actual routing is handled by Go SPA fallback — all dynamic paths serve index.html.
export function generateStaticParams() {
return [{ deviceId: '_' }];
}
export default function WorkspacePage() {
return <WorkspaceClient />;
}

93
local-tool/frontend/src/app/workspace/[deviceId]/workspace-client.tsx Normal file
View File

@ -0,0 +1,93 @@
'use client';
import { useEffect } from 'react';
import Link from 'next/link';
import { Button } from '@/components/ui/button';
import { CameraInferenceView } from '@/components/camera/camera-inference-view';
import { InferencePanel } from '@/components/inference/inference-panel';
import { useDeviceStore } from '@/stores/device-store';
import { useInferenceStore } from '@/stores/inference-store';
import { useInferenceStream } from '@/hooks/use-inference-stream';
import { useCameraStore } from '@/stores/camera-store';
import { useResolvedParams } from '@/hooks/use-resolved-params';
import { api } from '@/lib/api';
import { useTranslation } from '@/lib/i18n';
export default function WorkspaceClient() {
const { t } = useTranslation();
const { deviceId } = useResolvedParams();
const { selectedDevice, fetchDevice } = useDeviceStore();
const { isRunning, setRunning, reset } = useInferenceStore();
const { isStreaming, sourceType } = useCameraStore();
// For image/video mode, inference runs automatically as part of the pipeline
const isMediaMode = sourceType === 'image' || sourceType === 'video' || sourceType === 'batch_image';
// Enable WebSocket stream when inference is running OR when media pipeline is active
useInferenceStream(deviceId, isRunning || (isStreaming && isMediaMode));
// Auto-set isRunning when media upload starts streaming
useEffect(() => {
if (isStreaming && isMediaMode) {
setRunning(true);
}
}, [isStreaming, isMediaMode, setRunning]);
const { fetchCameras } = useCameraStore();
useEffect(() => {
if (deviceId) {
fetchDevice(deviceId);
fetchCameras();
}
return () => {
reset();
};
}, [deviceId, fetchDevice, fetchCameras, reset]);
const handleStartInference = async () => {
await api.post(`/devices/${deviceId}/inference/start`);
setRunning(true);
};
const handleStopInference = async () => {
await api.post(`/devices/${deviceId}/inference/stop`);
setRunning(false);
};
return (
<div className="space-y-4">
<div className="flex items-center justify-between">
<div className="flex items-center gap-2">
<Link href={`/devices/${deviceId}`}>
<Button variant="ghost" size="sm">{'← ' + t('common.back')}</Button>
</Link>
<h1 className="text-xl font-bold">
{t('inference.workspace') + ':'} {selectedDevice?.name || deviceId}
</h1>
</div>
{/* Only show manual inference controls in camera mode */}
{!isMediaMode && (
<div className="flex gap-2">
{isRunning ? (
<Button variant="destructive" onClick={handleStopInference}>
{t('inference.stopInference')}
</Button>
) : (
<Button onClick={handleStartInference} disabled={!isStreaming} data-tour-id="start-inference-btn">
{t('inference.startInference')}
</Button>
)}
</div>
)}
</div>
<div className="flex gap-6">
<div className="flex-1">
<CameraInferenceView deviceId={deviceId} />
</div>
<InferencePanel />
</div>
</div>
);
}

62
local-tool/frontend/src/app/workspace/page.tsx Normal file
View File

@ -0,0 +1,62 @@
'use client';
// TODO: M2 redesign workspace landing (device picker, empty state)
import Link from 'next/link';
import { useEffect } from 'react';
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
import { Button } from '@/components/ui/button';
import { useDeviceStore } from '@/stores/device-store';
import { useTranslation } from '@/lib/i18n';
export default function WorkspaceIndexPage() {
const { t } = useTranslation();
const { devices, fetchDevices } = useDeviceStore();
useEffect(() => {
fetchDevices();
}, [fetchDevices]);
const connected = devices.filter(
(d) => d.status === 'connected' || d.status === 'inferencing',
);
return (
<div className="space-y-6">
<div>
<h1 className="text-2xl font-bold">{t('workspace.title')}</h1>
<p className="text-muted-foreground">{t('workspace.subtitle')}</p>
</div>
{connected.length === 0 ? (
<Card>
<CardHeader>
<CardTitle className="text-base">{t('workspace.noConnectedDevice')}</CardTitle>
</CardHeader>
<CardContent>
<p className="text-sm text-muted-foreground mb-4">
{t('workspace.noConnectedDeviceDesc')}
</p>
<Link href="/devices">
<Button>{t('workspace.goToDevices')}</Button>
</Link>
</CardContent>
</Card>
) : (
<div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
{connected.map((d) => (
<Link key={d.id} href={`/workspace/${d.id}`}>
<Card className="cursor-pointer transition-colors hover:bg-accent">
<CardHeader>
<CardTitle className="text-base">{d.name}</CardTitle>
</CardHeader>
<CardContent>
<p className="text-sm text-muted-foreground">{d.type}</p>
</CardContent>
</Card>
</Link>
))}
</div>
)}
</div>
);
}

80
local-tool/frontend/src/components/camera/batch-image-thumbnails.tsx Normal file
View File

@ -0,0 +1,80 @@
'use client';
import { useCameraStore } from '@/stores/camera-store';
import { useInferenceStore } from '@/stores/inference-store';
import { getBackendUrl, appendRelayToken } from '@/lib/constants';
import { ScrollArea, ScrollBar } from '@/components/ui/scroll-area';
import { Progress } from '@/components/ui/progress';
import { cn } from '@/lib/utils';
import { useTranslation } from '@/lib/i18n';
import { Check, Loader2 } from 'lucide-react';
export function BatchImageThumbnails() {
const { t } = useTranslation();
const {
batchImages,
batchSelectedIndex,
batchProcessedCount,
setBatchSelectedIndex,
} = useCameraStore();
const batchResults = useInferenceStore((s) => s.batchResults);
if (batchImages.length === 0) return null;
const progress = (batchProcessedCount / batchImages.length) * 100;
return (
<div className="space-y-2">
<div className="flex items-center gap-2">
<Progress value={progress} className="flex-1" />
<span className="text-xs text-muted-foreground whitespace-nowrap">
{batchProcessedCount}/{batchImages.length}
</span>
</div>
<ScrollArea className="w-full">
<div className="flex gap-2 pb-2">
{batchImages.map((img, i) => {
const hasResult = i in batchResults;
const isProcessing = i === batchProcessedCount && !hasResult;
const isSelected = i === batchSelectedIndex;
return (
<button
key={i}
onClick={() => setBatchSelectedIndex(i)}
className={cn(
'relative flex-shrink-0 w-20 h-16 rounded-md overflow-hidden border-2 transition-all',
isSelected
? 'border-primary ring-2 ring-primary/30'
: 'border-transparent hover:border-muted-foreground/30',
!hasResult && !isProcessing && 'opacity-60'
)}
>
<img
src={appendRelayToken(`${getBackendUrl()}/api/media/batch-images/${i}`)}
alt={img.filename}
className="w-full h-full object-cover"
/>
<div className="absolute bottom-0 left-0 right-0 bg-black/60 px-1 py-0.5 flex items-center justify-center">
{isProcessing && (
<Loader2 className="h-3 w-3 text-yellow-400 animate-spin" />
)}
{hasResult && (
<Check className="h-3 w-3 text-green-400" />
)}
{!hasResult && !isProcessing && (
<span className="text-[10px] text-gray-400">
{i + 1}
</span>
)}
</div>
</button>
);
})}
</div>
<ScrollBar orientation="horizontal" />
</ScrollArea>
</div>
);
}

28
local-tool/frontend/src/components/camera/camera-controls.tsx Normal file
View File

@ -0,0 +1,28 @@
'use client';
import { Button } from '@/components/ui/button';
import { useCameraStore } from '@/stores/camera-store';
import { useTranslation } from '@/lib/i18n';
interface CameraControlsProps {
deviceId: string;
}
export function CameraControls({ deviceId }: CameraControlsProps) {
const { t } = useTranslation();
const { cameras, isStreaming, startPipeline, stopPipeline } = useCameraStore();
return (
<div className="flex items-center gap-3">
{isStreaming ? (
<Button variant="destructive" onClick={stopPipeline}>
{t('camera.stopCamera')}
</Button>
) : (
<Button onClick={() => startPipeline(cameras[0]?.id ?? 'mock-cam-0', deviceId)}>
{t('camera.startCamera')}
</Button>
)}
</div>
);
}

78
local-tool/frontend/src/components/camera/camera-feed.tsx Normal file
View File

@ -0,0 +1,78 @@
'use client';
import { useRef, useEffect } from 'react';
import type { SourceType } from '@/types/camera';
import { useTranslation } from '@/lib/i18n';
interface CameraFeedProps {
streamUrl: string;
width?: number;
height?: number;
sourceType?: SourceType | null;
batchImageUrl?: string;
onDimensionsChange?: (width: number, height: number) => void;
/** Rendered as an absolute overlay inside the feed container (e.g. CameraOverlay) */
overlay?: React.ReactNode;
}
export function CameraFeed({ streamUrl, width = 640, height = 480, sourceType, batchImageUrl, onDimensionsChange, overlay }: CameraFeedProps) {
const { t } = useTranslation();
const imgRef = useRef<HTMLImageElement>(null);
useEffect(() => {
const img = imgRef.current;
if (!img || !onDimensionsChange) return;
const observer = new ResizeObserver((entries) => {
for (const entry of entries) {
const { width: w, height: h } = entry.contentRect;
if (w > 0 && h > 0) {
onDimensionsChange(Math.round(w), Math.round(h));
}
}
});
observer.observe(img);
return () => observer.disconnect();
}, [onDimensionsChange]);
if (!streamUrl) {
return (
<div
className="flex items-center justify-center rounded-lg border bg-muted"
style={{ width, height }}
>
<div className="text-center text-muted-foreground">
<p>{t('camera.noInputSource')}</p>
<p className="text-xs mt-1">{t('camera.selectSourceHint')}</p>
</div>
</div>
);
}
const displayUrl = batchImageUrl || streamUrl;
const altText =
sourceType === 'image' || sourceType === 'batch_image'
? t('camera.uploadedImage')
: sourceType === 'video'
? t('camera.videoPlayback')
: t('camera.cameraFeed');
return (
<div className="relative overflow-hidden rounded-lg border">
<img
ref={imgRef}
src={displayUrl}
alt={altText}
style={{ width, height: 'auto' }}
className="block"
/>
{overlay}
{sourceType && sourceType !== 'camera' && (
<div className="absolute top-2 left-2 rounded bg-black/60 px-2 py-1 text-xs text-white z-10">
{sourceType === 'image' ? t('camera.image') : sourceType === 'batch_image' ? t('camera.batchImages') : t('camera.video')}
</div>
)}
</div>
);
}

62
local-tool/frontend/src/components/camera/camera-inference-view.tsx Normal file
View File

@ -0,0 +1,62 @@
'use client';
import { useState, useCallback } from 'react';
import { CameraFeed } from './camera-feed';
import { CameraOverlay } from './camera-overlay';
import { SourceSelector } from './source-selector';
import { BatchImageThumbnails } from './batch-image-thumbnails';
import { useCameraStore } from '@/stores/camera-store';
import { useInferenceStore } from '@/stores/inference-store';
import { getBackendUrl, appendRelayToken } from '@/lib/constants';
interface CameraInferenceViewProps {
deviceId: string;
}
export function CameraInferenceView({ deviceId }: CameraInferenceViewProps) {
const { isStreaming, streamUrl, sourceType, batchSelectedIndex } = useCameraStore();
const { result, batchResults, confidenceThreshold } = useInferenceStore();
const displayWidth = 640;
const [renderedSize, setRenderedSize] = useState({ w: 640, h: 480 });
const isBatchMode = sourceType === 'batch_image';
const handleDimensionsChange = useCallback((w: number, h: number) => {
setRenderedSize({ w, h });
}, []);
// In batch mode, show the selected image's detections
const selectedResult = isBatchMode
? batchResults[batchSelectedIndex]
: result;
const detections = selectedResult?.detections || [];
// In batch mode, use static image endpoint for viewing selected image
const batchImageUrl = isBatchMode
? appendRelayToken(`${getBackendUrl()}/api/media/batch-images/${batchSelectedIndex}`)
: undefined;
return (
<div className="space-y-4">
<SourceSelector deviceId={deviceId} />
{isBatchMode && isStreaming && <BatchImageThumbnails />}
<CameraFeed
streamUrl={isStreaming ? streamUrl : ''}
width={displayWidth}
sourceType={sourceType}
batchImageUrl={batchImageUrl}
onDimensionsChange={handleDimensionsChange}
overlay={
isStreaming ? (
<CameraOverlay
detections={detections}
width={renderedSize.w}
height={renderedSize.h}
confidenceThreshold={confidenceThreshold}
/>
) : undefined
}
/>
</div>
);
}

63
local-tool/frontend/src/components/camera/camera-overlay.tsx Normal file
View File

@ -0,0 +1,63 @@
'use client';
import { useEffect, useRef } from 'react';
import type { DetectionResult } from '@/types/inference';
interface CameraOverlayProps {
detections: DetectionResult[];
width: number;
height: number;
confidenceThreshold: number;
}
const COLORS = ['#FF6B6B', '#4ECDC4', '#45B7D1', '#96CEB4', '#FFEAA7', '#DDA0DD', '#98D8C8', '#F7DC6F'];
export function CameraOverlay({ detections, width, height, confidenceThreshold }: CameraOverlayProps) {
const canvasRef = useRef<HTMLCanvasElement>(null);
useEffect(() => {
const canvas = canvasRef.current;
if (!canvas) return;
const ctx = canvas.getContext('2d');
if (!ctx) return;
ctx.clearRect(0, 0, width, height);
const filtered = detections.filter((d) => d.confidence >= confidenceThreshold);
filtered.forEach((det, i) => {
const color = COLORS[i % COLORS.length];
// Convert normalized coordinates (0-1) to pixel values
const px = det.bbox.x * width;
const py = det.bbox.y * height;
const pw = det.bbox.width * width;
const ph = det.bbox.height * height;
// Draw bounding box
ctx.strokeStyle = color;
ctx.lineWidth = 2;
ctx.strokeRect(px, py, pw, ph);
// Draw label background
const label = `${det.label} ${(det.confidence * 100).toFixed(0)}%`;
ctx.font = '14px sans-serif';
const textWidth = ctx.measureText(label).width;
ctx.fillStyle = color;
ctx.fillRect(px, py - 20, textWidth + 8, 20);
// Draw label text
ctx.fillStyle = '#fff';
ctx.fillText(label, px + 4, py - 5);
});
}, [detections, width, height, confidenceThreshold]);
return (
<canvas
ref={canvasRef}
width={width}
height={height}
style={{ width, height }}
className="absolute left-0 top-0 pointer-events-none"
/>
);
}

254
local-tool/frontend/src/components/camera/source-selector.tsx Normal file
View File

@ -0,0 +1,254 @@
'use client';
import { useState, useEffect, useRef } from 'react';
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';
import { Tabs, TabsList, TabsTrigger } from '@/components/ui/tabs';
import { useCameraStore } from '@/stores/camera-store';
import { useTranslation } from '@/lib/i18n';
import { cn } from '@/lib/utils';
interface SourceSelectorProps {
deviceId: string;
}
export function SourceSelector({ deviceId }: SourceSelectorProps) {
const { t } = useTranslation();
const {
cameras,
isStreaming,
sourceType,
sourceFilename,
isUploading,
startPipeline,
stopPipeline,
uploadImage,
uploadVideo,
uploadBatchImages,
startFromUrl,
} = useCameraStore();
const [mounted, setMounted] = useState(false);
const hasCameras = cameras.length > 0;
const [cameraDisabled, setCameraDisabled] = useState(false);
const [activeTab, setActiveTab] = useState<'camera' | 'image' | 'video'>('camera');
useEffect(() => {
setMounted(true);
}, []);
// After mount, check if cameras are available and switch tab if needed
useEffect(() => {
if (!hasCameras) {
setCameraDisabled(true);
if (activeTab === 'camera') {
setActiveTab('image');
}
} else {
setCameraDisabled(false);
}
}, [hasCameras, activeTab]);
const [videoMode, setVideoMode] = useState<'file' | 'url'>('file');
const [videoUrl, setVideoUrl] = useState('');
const [isDragging, setIsDragging] = useState(false);
const imageFileRef = useRef<HTMLInputElement>(null);
const videoFileRef = useRef<HTMLInputElement>(null);
const handleImageSelect = async (e: React.ChangeEvent<HTMLInputElement>) => {
const files = Array.from(e.target.files || []);
if (files.length === 0) return;
if (files.length === 1) {
await uploadImage(files[0], deviceId);
} else {
await uploadBatchImages(files, deviceId);
}
if (imageFileRef.current) imageFileRef.current.value = '';
};
const handleDragOver = (e: React.DragEvent) => {
e.preventDefault();
setIsDragging(true);
};
const handleDragLeave = () => setIsDragging(false);
const handleDrop = async (e: React.DragEvent) => {
e.preventDefault();
setIsDragging(false);
const files = Array.from(e.dataTransfer.files).filter((f) =>
['.jpg', '.jpeg', '.png'].some((ext) => f.name.toLowerCase().endsWith(ext))
);
if (files.length === 0) return;
if (files.length === 1) {
await uploadImage(files[0], deviceId);
} else {
await uploadBatchImages(files, deviceId);
}
};
const handleVideoSelect = async (e: React.ChangeEvent<HTMLInputElement>) => {
const file = e.target.files?.[0];
if (!file) return;
await uploadVideo(file, deviceId);
if (videoFileRef.current) videoFileRef.current.value = '';
};
const handleUrlSubmit = async () => {
if (!videoUrl.trim()) return;
await startFromUrl(videoUrl.trim(), deviceId);
setVideoUrl('');
};
const sourceLabel =
sourceType === 'camera' ? t('camera.camera') : sourceType === 'image' ? t('camera.image') : sourceType === 'batch_image' ? t('camera.batchImages') : t('camera.video');
if (!mounted) return null;
return (
<div className="space-y-3">
<Tabs
value={activeTab}
onValueChange={(v) => setActiveTab(v as typeof activeTab)}
>
<TabsList className="grid w-full grid-cols-3">
<TabsTrigger value="camera" disabled={isStreaming || cameraDisabled}>
{t('camera.camera')}
</TabsTrigger>
<TabsTrigger value="image" disabled={isStreaming}>
{t('camera.image')}
</TabsTrigger>
<TabsTrigger value="video" disabled={isStreaming}>
{t('camera.video')}
</TabsTrigger>
</TabsList>
</Tabs>
<div className="flex items-center gap-3">
{isStreaming ? (
<>
<Button variant="destructive" onClick={stopPipeline}>
{sourceType === 'camera' ? t('camera.stopCamera') : sourceType === 'image' ? t('camera.stopImage') : sourceType === 'batch_image' ? t('camera.stopBatch') : t('camera.stopVideo')}
</Button>
{sourceFilename && (
<span className="text-sm text-muted-foreground truncate max-w-48">
{sourceFilename}
</span>
)}
</>
) : (
<>
{activeTab === 'camera' && (
hasCameras ? (
<Button onClick={() => startPipeline(cameras[0]?.id ?? '', deviceId)}>
{t('camera.startCamera')}
</Button>
) : (
<p className="text-sm text-muted-foreground">
{t('camera.noCameraDetected')}
</p>
)
)}
{activeTab === 'image' && (
<div
onDragOver={handleDragOver}
onDragLeave={handleDragLeave}
onDrop={handleDrop}
className={cn(
'flex-1 rounded-lg border-2 border-dashed p-3 transition-colors',
isDragging ? 'border-primary bg-primary/5' : 'border-transparent'
)}
>
<div className="flex items-center gap-3">
<Button
onClick={() => imageFileRef.current?.click()}
disabled={isUploading}
>
{isUploading ? t('common.uploading') : t('camera.selectImages')}
</Button>
<span className="text-sm text-muted-foreground">
{t('camera.jpgPngMultiple')}
</span>
</div>
{isDragging && (
<p className="mt-2 text-sm text-primary">{t('camera.dropImagesHere')}</p>
)}
<input
ref={imageFileRef}
type="file"
accept=".jpg,.jpeg,.png"
multiple
className="hidden"
onChange={handleImageSelect}
/>
</div>
)}
{activeTab === 'video' && (
<div className="flex flex-col gap-2 w-full">
<div className="flex items-center gap-2">
<Button
variant={videoMode === 'file' ? 'default' : 'outline'}
size="sm"
onClick={() => setVideoMode('file')}
>
{t('camera.uploadFile')}
</Button>
<Button
variant={videoMode === 'url' ? 'default' : 'outline'}
size="sm"
onClick={() => setVideoMode('url')}
>
{t('camera.pasteUrl')}
</Button>
</div>
{videoMode === 'file' ? (
<div className="flex items-center gap-3">
<Button
onClick={() => videoFileRef.current?.click()}
disabled={isUploading}
>
{isUploading ? t('common.uploading') : t('camera.selectVideo')}
</Button>
<span className="text-sm text-muted-foreground">
{t('camera.mp4AviMov')}
</span>
<input
ref={videoFileRef}
type="file"
accept=".mp4,.avi,.mov"
className="hidden"
onChange={handleVideoSelect}
/>
</div>
) : (
<div className="flex flex-col gap-1.5">
<div className="flex items-center gap-2">
<Input
placeholder={t('camera.urlPlaceholder')}
value={videoUrl}
onChange={(e) => setVideoUrl(e.target.value)}
onKeyDown={(e) => {
if (e.key === 'Enter') handleUrlSubmit();
}}
className="flex-1"
/>
<Button
onClick={handleUrlSubmit}
disabled={isUploading || !videoUrl.trim()}
>
{isUploading ? t('common.loading') : t('common.start')}
</Button>
</div>
<p className="text-xs text-muted-foreground">
{t('camera.urlHelpText')}
</p>
</div>
)}
</div>
)}
</>
)}
</div>
</div>
);
}

91
local-tool/frontend/src/components/dashboard/activity-timeline.tsx Normal file
View File

@ -0,0 +1,91 @@
'use client';
import { useState, useEffect } from 'react';
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
import { useActivityStore, type ActivityType } from '@/stores/activity-store';
import {
Upload,
Trash2,
Cable,
Unplug,
Zap,
CheckCircle,
XCircle,
type LucideIcon,
} from 'lucide-react';
import { useTranslation } from '@/lib/i18n';
const activityIcons: Record<ActivityType, LucideIcon> = {
model_upload: Upload,
model_delete: Trash2,
device_connect: Cable,
device_disconnect: Unplug,
flash_start: Zap,
flash_complete: CheckCircle,
flash_error: XCircle,
};
const activityColors: Record<ActivityType, string> = {
model_upload: 'text-blue-600',
model_delete: 'text-red-600',
device_connect: 'text-green-600',
device_disconnect: 'text-gray-500',
flash_start: 'text-yellow-600',
flash_complete: 'text-green-600',
flash_error: 'text-red-600',
};
export function ActivityTimeline() {
const activities = useActivityStore((s) => s.activities).slice(0, 10);
const { t } = useTranslation();
const [now, setNow] = useState(0);
useEffect(() => {
setNow(Date.now());
const timer = setInterval(() => setNow(Date.now()), 60_000);
return () => clearInterval(timer);
}, []);
function formatTime(timestamp: number) {
if (now === 0) return '';
const diff = now - timestamp;
const minutes = Math.floor(diff / 60000);
if (minutes < 1) return t('dashboard.justNow');
if (minutes < 60) return t('dashboard.minutesAgo', { n: minutes });
const hours = Math.floor(minutes / 60);
if (hours < 24) return t('dashboard.hoursAgo', { n: hours });
const days = Math.floor(hours / 24);
return t('dashboard.daysAgo', { n: days });
}
return (
<Card>
<CardHeader>
<CardTitle className="text-base">{t('dashboard.recentActivity')}</CardTitle>
</CardHeader>
<CardContent>
{activities.length === 0 ? (
<p className="text-sm text-muted-foreground">{t('dashboard.noActivity')}</p>
) : (
<div className="space-y-3">
{activities.map((activity) => {
const Icon = activityIcons[activity.type];
const color = activityColors[activity.type];
return (
<div key={activity.id} className="flex gap-3 items-start">
<Icon className={`h-4 w-4 mt-0.5 shrink-0 ${color}`} />
<div className="flex-1 min-w-0">
<p className="text-sm truncate">{activity.message}</p>
<p className="text-xs text-muted-foreground" suppressHydrationWarning>
{formatTime(activity.timestamp)}
</p>
</div>
</div>
);
})}
</div>
)}
</CardContent>
</Card>
);
}

57
local-tool/frontend/src/components/dashboard/connected-devices-list.tsx Normal file
View File

@ -0,0 +1,57 @@
'use client';
import Link from 'next/link';
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
import { Button } from '@/components/ui/button';
import { Badge } from '@/components/ui/badge';
import { useDeviceStore } from '@/stores/device-store';
import { Cable } from 'lucide-react';
import { useTranslation } from '@/lib/i18n';
export function ConnectedDevicesList() {
const { t } = useTranslation();
const devices = useDeviceStore((s) => s.devices);
const connectedDevices = devices.filter(
(d) => d.status === 'connected' || d.status === 'flashing' || d.status === 'inferencing',
);
return (
<Card>
<CardHeader>
<CardTitle className="text-base">{t('dashboard.connectedDevices')}</CardTitle>
</CardHeader>
<CardContent>
{connectedDevices.length === 0 ? (
<p className="text-sm text-muted-foreground">{t('dashboard.noConnectedDevices')}</p>
) : (
<div className="space-y-3">
{connectedDevices.map((device) => (
<div
key={device.id}
className="flex items-center justify-between rounded-lg border p-3"
>
<div className="flex items-center gap-3">
<Cable className="h-4 w-4 text-green-600" />
<div>
<p className="text-sm font-medium">{device.name}</p>
<p className="text-xs text-muted-foreground">{device.type}</p>
</div>
</div>
<div className="flex items-center gap-2">
<Badge variant="outline" className="text-xs">
{device.status}
</Badge>
<Link href={`/devices/${device.id}`}>
<Button size="sm" variant="ghost">
{t('common.view')}
</Button>
</Link>
</div>
</div>
))}
</div>
)}
</CardContent>
</Card>
);
}

29
local-tool/frontend/src/components/dashboard/stat-card.tsx Normal file
View File

@ -0,0 +1,29 @@
'use client';
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
import type { LucideIcon } from 'lucide-react';
interface StatCardProps {
title: string;
value: string | number;
subtitle?: string;
icon?: LucideIcon;
iconColor?: string;
}
export function StatCard({ title, value, subtitle, icon: Icon, iconColor }: StatCardProps) {
return (
<Card>
<CardHeader className="pb-2 flex flex-row items-center justify-between">
<CardTitle className="text-sm font-medium text-muted-foreground">
{title}
</CardTitle>
{Icon && <Icon className={`h-4 w-4 ${iconColor || 'text-muted-foreground'}`} />}
</CardHeader>
<CardContent>
<div className="text-3xl font-bold">{value}</div>
{subtitle && <p className="text-sm text-muted-foreground mt-1">{subtitle}</p>}
</CardContent>
</Card>
);
}

83
local-tool/frontend/src/components/devices/device-card.tsx Normal file
View File

@ -0,0 +1,83 @@
'use client';
import Link from 'next/link';
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
import { Button } from '@/components/ui/button';
import { DeviceStatusBadge } from './device-status';
import { useDeviceStore } from '@/stores/device-store';
import { useDevicePreferencesStore } from '@/stores/device-preferences-store';
import { useTranslation } from '@/lib/i18n';
import type { Device } from '@/types/device';
interface DeviceCardProps {
device: Device;
isFirstCard?: boolean;
}
export function DeviceCard({ device, isFirstCard }: DeviceCardProps) {
const { t } = useTranslation();
const { connectDevice, disconnectDevice } = useDeviceStore();
const prefs = useDevicePreferencesStore((s) => s.getPreferences(device.id));
const displayName = prefs.alias || device.name;
const isConnected = device.status === 'connected' || device.status === 'flashing' || device.status === 'inferencing';
return (
<Card>
<CardHeader className="pb-3">
<div className="flex items-start justify-between">
<div>
<CardTitle className="text-base">{displayName}</CardTitle>
{prefs.alias && (
<p className="text-xs text-muted-foreground">{device.name}</p>
)}
</div>
<DeviceStatusBadge status={device.status} />
</div>
</CardHeader>
<CardContent className="space-y-3">
<div className="grid grid-cols-2 gap-2 text-sm">
<div>
<p className="text-muted-foreground">{t('devices.type')}</p>
<p className="font-medium">{device.type}</p>
</div>
<div>
<p className="text-muted-foreground">{t('devices.firmware')}</p>
<p className="font-medium">{device.firmwareVersion || t('common.na')}</p>
</div>
{device.flashedModel && (
<div className="col-span-2">
<p className="text-muted-foreground">{t('devices.flashedModel')}</p>
<p className="font-medium">{device.flashedModel}</p>
</div>
)}
</div>
<div className="flex gap-2">
{isConnected ? (
<>
<Link href={`/devices/${device.id}`}>
<Button size="sm" variant="outline" {...(isFirstCard ? { 'data-tour-id': 'manage-device-btn' } : {})}>
{t('common.manage')}
</Button>
</Link>
<Button
size="sm"
variant="ghost"
onClick={() => disconnectDevice(device.id)}
>
{t('common.disconnect')}
</Button>
</>
) : (
<Button
size="sm"
onClick={() => connectDevice(device.id)}
{...(isFirstCard ? { 'data-tour-id': 'connect-device-btn' } : {})}
>
{t('common.connect')}
</Button>
)}
</div>
</CardContent>
</Card>
);
}

54
local-tool/frontend/src/components/devices/device-connection-log.tsx Normal file
View File

@ -0,0 +1,54 @@
'use client';
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
import { ScrollArea } from '@/components/ui/scroll-area';
import { useDevicePreferencesStore } from '@/stores/device-preferences-store';
import { useTranslation } from '@/lib/i18n';
import { cn } from '@/lib/utils';
interface DeviceConnectionLogProps {
deviceId: string;
}
export function DeviceConnectionLog({ deviceId }: DeviceConnectionLogProps) {
const { t } = useTranslation();
const connectionLog = useDevicePreferencesStore((s) => s.connectionLog);
const deviceLogs = connectionLog
.filter((entry) => entry.deviceId === deviceId)
.reverse()
.slice(0, 50);
return (
<Card>
<CardHeader>
<CardTitle className="text-base">{t('devices.connectionLog.title')}</CardTitle>
</CardHeader>
<CardContent>
{deviceLogs.length === 0 ? (
<p className="text-sm text-muted-foreground">{t('devices.connectionLog.noEvents')}</p>
) : (
<ScrollArea className="h-48">
<div className="space-y-2">
{deviceLogs.map((entry, i) => (
<div key={i} className="flex items-center justify-between text-sm">
<div className="flex items-center gap-2">
<div
className={cn(
'h-2 w-2 rounded-full',
entry.event === 'connected' ? 'bg-green-500' : 'bg-gray-400'
)}
/>
<span>{entry.event === 'connected' ? t('devices.connectionLog.connected') : t('devices.connectionLog.disconnected')}</span>
</div>
<span className="text-muted-foreground text-xs" suppressHydrationWarning>
{new Date(entry.timestamp).toLocaleString()}
</span>
</div>
))}
</div>
</ScrollArea>
)}
</CardContent>
</Card>
);
}

79
local-tool/frontend/src/components/devices/device-health-card.tsx Normal file
View File

@ -0,0 +1,79 @@
'use client';
import { useState, useEffect } from 'react';
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
import { DeviceStatusBadge } from './device-status';
import { useTranslation } from '@/lib/i18n';
import type { Device } from '@/types/device';
import { useDevicePreferencesStore } from '@/stores/device-preferences-store';
interface DeviceHealthCardProps {
device: Device;
}
function formatUptime(ms: number): string | null {
if (ms <= 0) return null;
const seconds = Math.floor(ms / 1000);
const minutes = Math.floor(seconds / 60);
const hours = Math.floor(minutes / 60);
if (hours > 0) return `${hours}h ${minutes % 60}m`;
if (minutes > 0) return `${minutes}m ${seconds % 60}s`;
return `${seconds}s`;
}
export function DeviceHealthCard({ device }: DeviceHealthCardProps) {
const { t } = useTranslation();
const connectionLog = useDevicePreferencesStore((s) => s.connectionLog);
const deviceLogs = connectionLog.filter((e) => e.deviceId === device.id);
const lastConnected = [...deviceLogs]
.reverse()
.find((e) => e.event === 'connected');
const lastSeen = deviceLogs.length > 0
? deviceLogs[deviceLogs.length - 1].timestamp
: null;
const isOnline = device.status === 'connected' || device.status === 'flashing' || device.status === 'inferencing';
const [uptimeMs, setUptimeMs] = useState(0);
useEffect(() => {
if (!lastConnected || !isOnline) {
setUptimeMs(0);
return;
}
setUptimeMs(Date.now() - lastConnected.timestamp);
const timer = setInterval(() => {
setUptimeMs(Date.now() - lastConnected.timestamp);
}, 1000);
return () => clearInterval(timer);
}, [lastConnected, isOnline]);
return (
<Card>
<CardHeader>
<CardTitle className="text-base">{t('devices.health.title')}</CardTitle>
</CardHeader>
<CardContent className="space-y-3">
<div className="flex justify-between">
<span className="text-muted-foreground">{t('devices.health.status')}</span>
<DeviceStatusBadge status={device.status} />
</div>
<div className="flex justify-between">
<span className="text-muted-foreground">{t('devices.health.firmwareVersion')}</span>
<span className="font-medium">{device.firmwareVersion || t('common.na')}</span>
</div>
<div className="flex justify-between">
<span className="text-muted-foreground">{t('devices.health.uptime')}</span>
<span className="font-medium" suppressHydrationWarning>{formatUptime(uptimeMs) || t('common.na')}</span>
</div>
<div className="flex justify-between">
<span className="text-muted-foreground">{t('devices.health.lastSeen')}</span>
<span className="text-sm" suppressHydrationWarning>
{lastSeen ? new Date(lastSeen).toLocaleString() : t('common.na')}
</span>
</div>
</CardContent>
</Card>
);
}

47
local-tool/frontend/src/components/devices/device-list.tsx Normal file
View File

@ -0,0 +1,47 @@
'use client';
import { HardDrive } from 'lucide-react';
import { DeviceCard } from './device-card';
import { EmptyState } from '@/components/ui/empty-state';
import { useTranslation } from '@/lib/i18n';
import { useDeviceStore } from '@/stores/device-store';
import type { Device } from '@/types/device';
interface DeviceListProps {
devices: Device[];
loading?: boolean;
}
export function DeviceList({ devices, loading }: DeviceListProps) {
const { t } = useTranslation();
const { scanDevices } = useDeviceStore();
if (loading) {
return (
<div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
{Array.from({ length: 3 }).map((_, i) => (
<div key={i} className="h-48 animate-pulse rounded-lg border bg-muted" />
))}
</div>
);
}
if (devices.length === 0) {
return (
<EmptyState
icon={HardDrive}
title={t('emptyState.devicesTitle')}
description={t('emptyState.devicesDesc')}
action={{ label: t('emptyState.devicesScan'), onClick: scanDevices }}
/>
);
}
return (
<div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
{devices.map((device, index) => (
<DeviceCard key={device.id} device={device} isFirstCard={index === 0} />
))}
</div>
);
}

65
local-tool/frontend/src/components/devices/device-settings-card.tsx Normal file
View File

@ -0,0 +1,65 @@
'use client';
import { useState, useEffect } from 'react';
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
import { Input } from '@/components/ui/input';
import { Button } from '@/components/ui/button';
import { useDevicePreferencesStore } from '@/stores/device-preferences-store';
import { useTranslation } from '@/lib/i18n';
import { showSuccess } from '@/lib/toast';
interface DeviceSettingsCardProps {
deviceId: string;
}
export function DeviceSettingsCard({ deviceId }: DeviceSettingsCardProps) {
const { t } = useTranslation();
const { getPreferences, setAlias, setNotes } = useDevicePreferencesStore();
const prefs = getPreferences(deviceId);
const [alias, setAliasLocal] = useState(prefs.alias);
const [notes, setNotesLocal] = useState(prefs.notes);
useEffect(() => {
const p = getPreferences(deviceId);
setAliasLocal(p.alias);
setNotesLocal(p.notes);
}, [deviceId, getPreferences]);
const handleSave = () => {
setAlias(deviceId, alias);
setNotes(deviceId, notes);
showSuccess(t('devices.settings.settingsSaved'));
};
return (
<Card>
<CardHeader>
<CardTitle className="text-base">{t('devices.settings.title')}</CardTitle>
</CardHeader>
<CardContent className="space-y-4">
<div>
<label className="text-sm font-medium text-muted-foreground">{t('devices.settings.alias')}</label>
<Input
className="mt-1"
placeholder={t('devices.settings.aliasPlaceholder')}
value={alias}
onChange={(e) => setAliasLocal(e.target.value)}
/>
</div>
<div>
<label className="text-sm font-medium text-muted-foreground">{t('devices.settings.notes')}</label>
<textarea
className="mt-1 flex min-h-[80px] w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"
placeholder={t('devices.settings.notesPlaceholder')}
value={notes}
onChange={(e) => setNotesLocal(e.target.value)}
/>
</div>
<Button size="sm" onClick={handleSave}>
{t('devices.settings.saveSettings')}
</Button>
</CardContent>
</Card>
);
}

38
local-tool/frontend/src/components/devices/device-status.tsx Normal file
View File

@ -0,0 +1,38 @@
'use client';
import { cn } from '@/lib/utils';
import { useTranslation } from '@/lib/i18n';
import type { DeviceStatus } from '@/types/device';
const statusColors: Record<string, string> = {
detected: 'bg-gray-400',
connecting: 'bg-yellow-400',
connected: 'bg-green-500',
flashing: 'bg-yellow-500',
inferencing: 'bg-blue-500',
error: 'bg-red-500',
disconnected: 'bg-gray-400',
};
export function DeviceStatusBadge({ status }: { status: DeviceStatus }) {
const { t } = useTranslation();
const statusLabels: Record<string, string> = {
detected: t('devices.status.detected'),
connecting: t('devices.status.connecting'),
connected: t('devices.status.connected'),
flashing: t('devices.status.flashing'),
inferencing: t('devices.status.inferencing'),
error: t('devices.status.error'),
disconnected: t('devices.status.disconnected'),
};
const color = statusColors[status] || statusColors.disconnected;
const label = statusLabels[status] || statusLabels.disconnected;
return (
<div className="flex items-center gap-2">
<div className={cn('h-2.5 w-2.5 rounded-full', color)} />
<span className="text-sm">{label}</span>
</div>
);
}

249
local-tool/frontend/src/components/guided-tour.tsx Normal file
View File

@ -0,0 +1,249 @@
'use client';
import { useEffect, useRef, useCallback } from 'react';
import { usePathname, useRouter } from 'next/navigation';
import { driver, type DriveStep, type Config } from 'driver.js';
import 'driver.js/dist/driver.css';
import { tourSteps } from '@/lib/tour-steps';
import { useTourStore } from '@/stores/tour-store';
import { useDeviceStore } from '@/stores/device-store';
import { useTranslation } from '@/lib/i18n';
function waitForElement(selector: string, timeout = 3000): Promise<Element | null> {
return new Promise((resolve) => {
const el = document.querySelector(selector);
if (el) return resolve(el);
const observer = new MutationObserver(() => {
const found = document.querySelector(selector);
if (found) {
observer.disconnect();
resolve(found);
}
});
observer.observe(document.body, { childList: true, subtree: true });
setTimeout(() => {
observer.disconnect();
resolve(null);
}, timeout);
});
}
export function GuidedTour() {
const { t } = useTranslation();
const pathname = usePathname();
const router = useRouter();
const { isActive, currentStepIndex, endTour, markTourCompleted, goToStep } = useTourStore();
const devices = useDeviceStore((s) => s.devices);
const driverRef = useRef<ReturnType<typeof driver> | null>(null);
const isNavigatingRef = useRef(false);
const pollingRef = useRef<ReturnType<typeof setInterval> | null>(null);
const getFirstConnectedDeviceId = useCallback(() => {
const connected = devices.find((d) => d.status === 'connected' || d.status === 'flashing' || d.status === 'inferencing');
if (connected) return connected.id;
return devices.length > 0 ? devices[0].id : null;
}, [devices]);
const resolvePagePath = useCallback((pageTpl: string) => {
const deviceId = getFirstConnectedDeviceId();
if (!deviceId) return pageTpl;
return pageTpl.replace('__DEVICE_ID__', deviceId);
}, [getFirstConnectedDeviceId]);
const cleanup = useCallback(() => {
if (driverRef.current) {
driverRef.current.destroy();
driverRef.current = null;
}
if (pollingRef.current) {
clearInterval(pollingRef.current);
pollingRef.current = null;
}
}, []);
// Clean up on unmount
useEffect(() => cleanup, [cleanup]);
// Main tour effect — runs whenever step changes or becomes active
useEffect(() => {
if (!isActive) {
cleanup();
return;
}
const step = tourSteps[currentStepIndex];
if (!step) {
markTourCompleted();
endTour();
cleanup();
return;
}
const targetPage = resolvePagePath(step.page);
// If we need to navigate to a different page
if (!pathname.startsWith(targetPage)) {
isNavigatingRef.current = true;
cleanup();
router.push(targetPage);
return;
}
// We're on the right page — wait for the element and highlight it
const highlight = async () => {
if (isNavigatingRef.current) {
await new Promise((r) => setTimeout(r, 500));
isNavigatingRef.current = false;
}
const el = await waitForElement(step.elementSelector);
cleanup();
const totalSteps = tourSteps.length;
const isLast = currentStepIndex === totalSteps - 1;
const isFirst = currentStepIndex === 0;
const stepComplete = step.isComplete();
const description = stepComplete
? t(step.descriptionKey)
: `${t(step.descriptionKey)}<br/><br/><span class="driver-pending-hint">⏳ ${t(step.pendingDescKey)}</span>`;
const driverSteps: DriveStep[] = [{
element: el ? step.elementSelector : undefined,
popover: {
title: `${t(step.titleKey)} <span class="driver-step-counter">(${currentStepIndex + 1} ${t('tour.of')} ${totalSteps})</span>`,
description,
side: step.side,
align: 'center',
},
}];
const config: Config = {
showProgress: false,
showButtons: ['next', 'previous', 'close'],
nextBtnText: isLast ? t('tour.done') : t('tour.next'),
prevBtnText: t('tour.prev'),
doneBtnText: t('tour.done'),
steps: driverSteps,
allowClose: true,
overlayClickBehavior: 'nextStep',
stagePadding: 8,
stageRadius: 8,
onCloseClick: () => {
endTour();
cleanup();
},
onNextClick: () => {
// Block advancing if step not complete
if (!step.isComplete()) return;
if (isLast) {
markTourCompleted();
endTour();
cleanup();
} else {
cleanup();
goToStep(currentStepIndex + 1);
}
},
onPrevClick: () => {
if (!isFirst) {
cleanup();
goToStep(currentStepIndex - 1);
}
},
onDestroyStarted: () => {
if (driverRef.current) {
driverRef.current.destroy();
driverRef.current = null;
}
},
};
if (isFirst) {
config.showButtons = ['next', 'close'];
}
const d = driver(config);
driverRef.current = d;
d.drive();
// Style the next button as disabled if step not complete
updateNextButtonState(stepComplete);
// Add the Exit Tour button in nav row
addExitButton(t('tour.exit'));
// Poll for step completion — refresh the popover when condition changes
if (!stepComplete) {
pollingRef.current = setInterval(() => {
if (step.isComplete()) {
// Step completed! Refresh the highlight to update description & enable Next
if (pollingRef.current) {
clearInterval(pollingRef.current);
pollingRef.current = null;
}
// Re-trigger highlight by re-setting the same step
cleanup();
goToStep(currentStepIndex);
}
}, 800);
}
};
highlight();
}, [isActive, currentStepIndex, pathname, t, router, resolvePagePath, endTour, markTourCompleted, goToStep, cleanup]);
// If user navigates away via sidebar during tour, end the tour
useEffect(() => {
if (!isActive) return;
const step = tourSteps[currentStepIndex];
if (!step) return;
const targetPage = resolvePagePath(step.page);
if (!pathname.startsWith(targetPage) && !isNavigatingRef.current) {
endTour();
cleanup();
}
}, [pathname, isActive, currentStepIndex, resolvePagePath, endTour, cleanup]);
return null;
}
/** Visually disable/enable the Next button */
function updateNextButtonState(enabled: boolean) {
requestAnimationFrame(() => {
const nextBtn = document.querySelector('.driver-popover-next-btn') as HTMLButtonElement | null;
if (!nextBtn) return;
if (enabled) {
nextBtn.classList.remove('driver-btn-disabled');
} else {
nextBtn.classList.add('driver-btn-disabled');
}
});
}
/** Inject an "Exit Tour" button into the navigation button row */
function addExitButton(exitText: string) {
requestAnimationFrame(() => {
const nav = document.querySelector('.driver-popover-navigation-btns');
if (!nav || nav.querySelector('.driver-exit-tour')) return;
const exitBtn = document.createElement('button');
exitBtn.className = 'driver-exit-tour';
exitBtn.textContent = exitText;
exitBtn.addEventListener('click', (e) => {
e.stopPropagation();
useTourStore.getState().endTour();
document.querySelectorAll('.driver-overlay, .driver-popover').forEach((el) => el.remove());
document.querySelectorAll('[class*="driver-active"]').forEach((el) => {
el.classList.remove('driver-active-element');
});
});
// Insert at the beginning of the nav row (left side)
nav.insertBefore(exitBtn, nav.firstChild);
});
}

48
local-tool/frontend/src/components/inference/classification-result.tsx Normal file
View File

@ -0,0 +1,48 @@
'use client';
import { BarChart, Bar, XAxis, YAxis, CartesianGrid, ResponsiveContainer, Cell } from 'recharts';
import type { ClassResult } from '@/types/inference';
import { useTranslation } from '@/lib/i18n';
interface ClassificationResultProps {
results: ClassResult[];
confidenceThreshold: number;
}
const COLORS = ['#8884d8', '#82ca9d', '#ffc658', '#ff7300', '#0088FE', '#00C49F', '#FFBB28', '#FF8042'];
export function ClassificationResult({ results, confidenceThreshold }: ClassificationResultProps) {
const { t } = useTranslation();
const filtered = results
.filter((r) => r.confidence >= confidenceThreshold)
.sort((a, b) => b.confidence - a.confidence)
.slice(0, 8);
const data = filtered.map((r) => ({
label: r.label,
confidence: +(r.confidence * 100).toFixed(1),
}));
if (data.length === 0) {
return (
<div className="flex h-48 items-center justify-center text-sm text-muted-foreground">
{t('inference.noResultsAboveThreshold')}
</div>
);
}
return (
<ResponsiveContainer width="100%" height={250}>
<BarChart data={data} layout="vertical" margin={{ left: 80, right: 20, top: 5, bottom: 5 }}>
<CartesianGrid strokeDasharray="3 3" />
<XAxis type="number" domain={[0, 100]} unit="%" />
<YAxis type="category" dataKey="label" width={70} fontSize={12} />
<Bar dataKey="confidence" radius={[0, 4, 4, 0]}>
{data.map((_, index) => (
<Cell key={`cell-${index}`} fill={COLORS[index % COLORS.length]} />
))}
</Bar>
</BarChart>
</ResponsiveContainer>
);
}

Some files were not shown because too many files have changed in this diff Show More