jim800121chen
fb7da5d180
依 autoflow-agent workspace v2 設計把 PRD / 設計 / 架構 / 交付類 共享文件從個人層 .autoflow/（ignored）搬到 docs/autoflow/（進 git）， 讓團隊可共享產品與架構文件，個人層只留 progress / review / testing 等 per-branch 筆記。 - 02-prd/ 21 個檔（PRD、features、market-analysis 等） - 03-design/ 18 個檔（design-spec、wireframes、flows 等） - 04-architecture/ 31 個檔（TDD、design-doc、ADR×14、API 規格等） - 07-delivery/ 3 個檔（project-summary、phase-0.6-handover、stage-deployment-setup） 合計 73 檔。原檔已從 .autoflow/ 移除（migration 工具執行 git mv， 但因 .autoflow/ 在 .gitignore 中、git 將此操作視為新增、無 rename history）。
283 lines
12 KiB
Markdown
283 lines
12 KiB
Markdown
# 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`
|