# visionA 產品線 Phase 0 + Phase 0.5 交付總結

> **交付日期**：2026-04-22
> **階段**：Phase 0 雛形（visionA 雲端版） + Phase 0.5（visionA Agent）
> **狀態**：✅ 全部完成

---

## 一、專案全景

visionA 是 Innovedus 的 Edge AI 開發平台，目前由 **4 個子專案**構成：

| 子專案 | 位置 | 角色 | 狀態 |
|--------|------|------|------|
| **local-tool** | `visionA/local-tool/` | 離線版桌面應用（Wails + Next.js + Go）| 既有，不動 |
| **visionA-frontend** | `visionA/visionA-frontend/` | 雲端 web 前端（Next.js）| Phase 0 雛形完成 |
| **visionA-backend** | `visionA/visionA-backend/` | 雲端後端（Go；api-server + remote-proxy 雙 binary）| Phase 0 雛形完成 |
| **visionA Agent（local-agent）** | `visionA/local-agent/` | 雲端版 local 端代理（Wails + Next.js + Go） | Phase 0.5 完成 |

未來還會加：
- **kneron_model_converter**（轉檔網站，獨立專案）
- 會員系統、Billing、Admin Console（Phase 1+）

---

## 二、產品定位

### 兩種使用模式並存

- **離線模式**：使用者裝 `local-tool` → 前端連 localhost server → 本機操作 Kneron 裝置
- **雲端模式**：使用者裝 `visionA Agent`（local 端代理）+ 使用雲端 web UI（瀏覽器開 `visionA-frontend`）→ 前端連雲端 `visionA-backend` → 經 remote-proxy tunnel 到 local-agent → 本機 Kneron 裝置

**兩個 Wails app 可同機共存**：
- Bundle ID 獨立（`com.innovedus.visiona-local` vs `com.innovedus.visiona-agent`）
- Data dir 獨立（`visiona-local/` vs `visiona-agent/`）
- Port 不撞（local-tool 用 `3721`；Agent 內部綁 `127.0.0.1:random`，不對外）

---

## 三、4 大核心原則（使用者定）

1. **local-tool 完全不動**，需要時 fork
2. **雲端 vs 本機差異只在前端部署位置**（其他一樣）
3. **cloud agent 的 server ≈ local-tool 的 server**（差別在沒本機操作 UI + 多 tunnel client + 多配對 UI）
4. **雲端 web UI 先抄 local-tool**，Phase 0 不發明新 UI

---

## 四、技術堆疊

### Frontend（共通）
- Next.js 16.x + React 19.x + TypeScript 5
- Tailwind CSS 4 + Radix UI + Lucide
- Zustand 5（狀態）、自訂 i18n（繁中 + English）
- Vitest + React Testing Library

### Backend（visionA-backend）
- Go 1.26 + Gin + gorilla/websocket + hashicorp/yamux
- 雙 binary：`cmd/api-server`（3721）+ `cmd/remote-proxy`（tunnel 3800 / internal 3801）
- in-memory store（Phase 1 換 Postgres/Redis）
- S3-compat 抽象層（LocalFS 雛形 / S3 / MinIO 未定）

### visionA Agent
- Wails v2 桌面外殼 + Next.js（output: 'export'）靜態嵌入
- Tunnel client（從 POC 複製，backoff bug 已修）
- AES-GCM + scrypt + machineID-衍生 passphrase 的 Token storage
- YAML config + 結構化 log + zip 匯出
- 三平台安裝包：macOS DMG / Windows EXE / Linux AppImage

---

## 五、架構圖

```
                                              ┌─────────────────────────┐
                                              │  visionA-frontend       │
                                              │  (Next.js on CDN)       │
                                              └───────────┬─────────────┘
                                                          │ HTTPS
                                              ┌───────────▼─────────────┐
                                              │  visionA-backend        │
                                   ┌──────────┤  cmd/api-server :3721   │
                                   │          │  (無狀態，可水平擴展)     │
                                   │          └───────────┬─────────────┘
                                   │                      │ internal HTTP :3801
                                   │                      │ (查 session / raw forward)
                       internal ──>│          ┌───────────▼─────────────┐
                       HTTP        │          │  visionA-backend        │
                                   │          │  cmd/remote-proxy       │
                                   │          │  tunnel :3800 / int :3801│
                                   │          │  (有狀態，持 session)    │
                                   │          └───────────┬─────────────┘
                                   │                      │ WebSocket + yamux
                                   │                      │ (tunnel)
                                   │                      │
                                   │          ┌───────────▼─────────────┐
                                   │          │  local-agent            │
                                   │          │  visiona-agent (Wails)  │
                                   │          │  ├─ tunnel client       │
                                   │          │  ├─ local HTTP :random  │
                                   │          │  │  (綁 127.0.0.1)      │
                                   │          │  └─ visiona-agent-server│
                                   │          │     (Kneron/camera/...)  │
                                   │          └───────────┬─────────────┘
                                   │                      │ USB / IP
                                   │          ┌───────────▼─────────────┐
                                   │          │  Kneron 裝置            │
                                   │          │  (KL520/KL720/KL730)    │
                                   │          └─────────────────────────┘

  離線模式：使用者只用 local-tool，前端連 localhost:3721 直接操作
```

---

## 六、交付物總覽

### 文件（`.autoflow/`）
- **PRD**：`02-prd/` — 21 個檔（索引 + 10 章節 + 10 features）
- **設計規格**：`03-design/` — 15 個檔（含 visionA Agent spec）
- **架構 / TDD**：`04-architecture/` — 14 個檔（含 visionA Agent TDD + 9 個 ADR）
- **健檢 / Review**：`00-onboarding/` + `05-implementation/review/` — 10+ 份

### 程式碼
- **visionA-frontend**：Next.js 應用，13 頁面、30+ 元件、94 tests、static export 就緒
- **visionA-backend**：雙 binary Go 應用，20+ endpoints、100+ tests、Docker compose 就緒、E2E test 5 milestone 全綠
- **visionA Agent**：Wails 桌面應用，tunnel client + 3 個配置頁（狀態/配對/設定）、90 tests、DMG 已 build（160 MB）

### 安裝包
- macOS DMG：✅ 已驗（160 MB，本機 build）
- Windows EXE：`.github/workflows/build.yml` 就緒，由 CI 驗
- Linux AppImage：同上

---

## 七、關鍵 Milestone & Integration Tests

### visionA-backend E2E
`cmd/api-server/b5_integration_test.go` 等：5 段完整路徑
- **Browser → api-server → Forwarder → remote-proxy → yamux → fake tunnel client → fake local server**

### visionA-backend + visionA Agent E2E（AB13）
`cmd/api-server/e2e_full_flow_test.go`：5 個 milestone
1. Pairing Exchange（產 pairing → 兌換 session token）
2. Tunnel Connect（session token 用 yamux 建立 tunnel）
3. API Forward（透過完整鏈路轉發業務請求）
4. Token Reuse 防護（同 pairing token 再用 → 401 PAIRING_TOKEN_USED）
5. Tunnel Drop Failover（agent 斷線 → 502 TUNNEL_DISCONNECTED）

### visionA Agent 本機 E2E（AB6）
`local-agent/visiona-agent/internal/tunnel/integration_test.go`：
- fake relay → yamux → agent handleStream → local server
- 20 並行 stream 無交錯
- 502 / 500 錯誤處理

---

## 八、使用者裁決紀錄（15 個）

### Phase 0 雲端版雛形（7 個）
| # | 議題 | 決策 |
|---|------|------|
| Q1 | 雛形進程模型 | C：雙 binary + internal HTTP，不引入 Redis |
| Q2 | POC 程式碼 | A：複製到 visionA-backend，POC 保留 |
| Q3 | Local Agent | 本次雛形用 POC edge-ai-server 暫代，Phase 0.5 做獨立 Agent |
| Q4 | 雛形 Auth | C：StaticAuthService 回 demo-user |
| Q5 | Session 覆蓋 | A：沿用 POC，後連覆蓋前連 |
| Q6 | local-tool-only 元件 | A：雛形隱藏 OnboardingDialog / ServerStatusDashboard / ServerLogViewer |
| Q7 | Pairing Token 顯示 | API 回純 hex，前端顯示加空格 |

### Phase 0.5 visionA Agent（8 個）
| # | 議題 | 決策 |
|---|------|------|
| A3 | Agent 範圍 | 純橋樑：tunnel + 配對 UI + 設定，無本機操作 UI |
| — | App Name | visionA Agent（Bundle ID `com.innovedus.visiona-agent`）|
| — | local-tool 關係 | 2026-04-22 fork，獨立演進、不主動 sync |
| — | Tray UI | 不做（過去踩過坑）|
| — | 開機自啟 | 預設關閉 |
| — | Log 介面 | 基本 log + 匯出 zip |
| C1 | Frontend 框架 | Next.js 沿用（不換 Vite）|
| C2 | Tunnel client | 從 POC 複製（visionA-backend 的已刪）|

---

## 九、跨文件矛盾修訂紀錄（Phase 0）

三方審閱後修訂 12 項，關鍵：
- **M-1** Pairing Token 格式：`vAc_` + 32 hex / `vAs_` + 64 hex（三方對齊）
- **M-2** Token TTL：兩階段（Pairing 15 min + Session 90 天）
- **M-3** Auth 雙層：AuthProvider（handler）+ AuthService（middleware）
- **M-4** Converter API：REST Resource 風格（`POST /v1/jobs`）
- **M-5** 心跳：10 秒心跳 + 30 秒判定掉線
- **M-8** Non-Goal：雛形僅單 instance

---

## 十、Phase 1 TODO（彙整）

### 安全
- 真實 Auth（Clerk / OIDC / 自建），取代 StaticAuthProvider
- Agent token 改用 OS keychain（macOS Keychain / Windows Credential Manager / Linux Secret Service）
- remote-proxy 向 api-server 驗證 session token（不只是驗格式）
- TLS 終止策略、rate limit、audit log
- macOS Notarization / Windows Authenticode code signing

### 資料持久化
- PostgreSQL + migration（golang-migrate）
- 所有 InMemory*Repository → Postgres*Repository
- S3 / MinIO 真實接入（取代 LocalFS）

### 水平擴展
- 多 remote-proxy 節點 session metadata 共享
- api-server → proxy 跨節點路由
- 評估 Redis / Consul / Gossip

### 功能
- Converter 真實 API 對接（目前 stub，契約已定）
- Billing / 訂閱
- 多組織 Org / Team
- API key for programmatic access
- 裝置 multi-tab 同時觀看（目前 Q5 single session 限制）
- WebSocket proxy 真實實作（目前 501 stub）

### Agent 專屬
- Log rotation
- 自動更新機制（從 POC update/ 搬）
- System Tray（使用者過去踩過坑，非高優先級）
- SaveFileDialog（目前 ExportLog 只回 temp path）

### Observability
- 結構化 JSON log
- Prometheus metrics + Grafana
- OpenTelemetry tracing
- SLO dashboards + alert rules

### DevOps
- CI 真實跑通 Windows / Linux build（workflow 已設定）
- Staging 環境、Blue-green / Canary deploy
- 備份 / DR 演練

---

## 十一、下一步建議

### A. 端到端跑通（立即）
```bash
# 1. 起 visionA-backend
cd visionA-backend
cp .env.example .env
make dev

# 2. 起 visionA-frontend（另一個 terminal）
cd visionA-frontend
cp .env.local.example .env.local
pnpm dev

# 3. 手動測 visionA Agent（另一個 terminal）
cd local-agent
make wails-macos  # 或直接安裝 dist/visiona-agent.dmg
```

### B. CI 驗三平台 build
推 branch 觸發 `.github/workflows/build.yml`，驗 macOS/Windows/Linux 都能產出 artifact

### C. 進 Phase 1
根據 Phase 1 TODO 清單，選要先做的（建議優先序：真實 Auth → DB → S3 → 轉檔整合）

### D. 內部測試
乾淨機器安裝 local-tool + visionA Agent 驗共存、真實 Kneron 裝置跑一次配對 + 推論

---

## 十二、文件索引

- **產品**：`.autoflow/02-prd/PRD.md`（雲端版）
- **設計**：`.autoflow/03-design/design-spec.md`（雲端版）+ `visiona-agent-spec.md`（Agent）
- **架構**：`.autoflow/04-architecture/design-doc.md` + `TDD.md`（雲端版）+ `visiona-agent-tdd.md`（Agent）
- **ADR**：`.autoflow/04-architecture/adr/adr-001` ~ `adr-009`
- **健檢**：`.autoflow/00-onboarding/health-check.md`
- **Review**：`.autoflow/02-prd/review/` + `03-design/review/` + `04-architecture/review/` + `05-implementation/review/`
- **進度**：`.autoflow/progress.md`
- **Build 驗證**：`local-agent/docs/BUILD-VERIFICATION.md`