jim800121chen fb7da5d180 chore(autoflow): migrate .autoflow/ 共享層文件至 docs/autoflow/

依 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）。

2026-05-04 16:55:55 +08:00

8.4 KiB

Raw Blame History

7. 非功能性需求 — visionA Cloud

父文件：PRD.md

7.1 效能

7.1.1 API 回應時間

端點類型	Phase 0 目標	Phase 1 目標	備註
簡單 API（如 `/api/auth/me`、`/api/devices` 列表）	P95 < 200ms	P95 < 100ms	不過 tunnel 的
裝置操作（透過 tunnel）	P95 < 500ms + tunnel RTT	P95 < 300ms + tunnel RTT	含 tunnel 往返
模型上傳（100MB）	P95 < 60 秒	P95 < 30 秒（presigned）	網路頻寬限制
Pairing 產生 token	P95 < 100ms	P95 < 50ms	—

7.1.2 推論效能

指標	Phase 0 目標	Phase 1 目標
Camera 端到端延遲 P95	< 500ms	< 350ms
Camera FPS	>= 10 fps	>= 20 fps（視裝置 + 模型）
首次推論啟動時間	< 3 秒	< 2 秒

參考值：local-tool（本機）的 Camera 端到端延遲 ~150-250ms，visionA Cloud 多出的部分主要是 tunnel WAN RTT。

7.1.3 Tunnel 效能

指標	Phase 0 目標
Tunnel 建立時間	< 2 秒（含 TLS handshake + yamux handshake）
Tunnel 重連時間	< 5 秒（斷線偵測到重連成功）
Tunnel throughput	>= 5 Mbps（至少能跑 MJPEG 480p）
並發 yamux streams per session	>= 32

7.1.4 前端效能

指標	Phase 0 目標
首頁 FCP	< 2 秒（cold load）
頁面切換	< 300ms（App Router prefetch）
WebSocket 訊息處理	< 50ms
MJPEG 畫面渲染	維持 >= 20 fps

7.2 安全性

7.2.1 傳輸加密

必須使用 TLS（Phase 1 起強制，Phase 0 dev 環境可暫用 http）
Tunnel 必須用 wss://（不能走明文 WebSocket）
TLS 版本：>= 1.2，建議 1.3
HSTS header（Phase 1 起）

7.2.2 認證與授權

需求	Phase 0	Phase 1
使用者登入	Stub（不安全）	JWT + bcrypt
Session 管理	記憶體 token	Redis + rotation
Pairing Token 安全	一次性 + 15min TTL	+ DB hash 儲存 + rate limit
Session Token 安全	純字串存記憶體	+ DB hash + 撤銷機制 + rotation
API Rate Limiting	❌ 不做	✅ 必做（Auth 相關 endpoint）
CSRF 防護	❌（cookie-only）	SameSite=Strict cookies
XSS 防護	React 自動轉義	+ CSP header

7.2.3 資料隔離

Phase 0 即須滿足：

使用者 A 不能看到使用者 B 的裝置、模型、叢集
所有 API endpoint 必須檢查 resource 的 owner_user_id vs current user
WebSocket 連線也要做同樣檢查

7.2.4 敏感資料保護

資料	處理方式
密碼	Phase 0 不存（stub 只記 in-memory）；Phase 1 bcrypt
Session Token	不 log 出來
Pairing Token 產生後	只顯示一次，後端不可再查明文（Phase 1 存 hash）
使用者模型檔	存在 ObjectStorage，需 user 授權才能下載
推論影像 / 結果	Phase 0 不儲存；Phase 1 如有儲存需加密

7.2.5 依賴套件安全

Go：go mod audit（或 Snyk）每月掃一次
Node：npm audit 每週掃一次
Docker 映像：每月重 build 套新 base image
漏洞回應 SLA：Critical 1 週修，High 2 週修

7.3 可擴展性（Scalability）

7.3.1 Phase 0 定位：可跑得動就好

單機部署 OK
支援 ~10 同時使用者、~20 裝置同時在線
狀態 in-memory，重啟就沒了

7.3.2 Phase 1 定位：支援 100 人同時使用

接 PostgreSQL 作 persistent store
接 Redis 作 session store / tunnel session map（跨 api-server instance 共享）
api-server 可水平擴展（stateless）
remote-proxy 仍然有狀態（tunnel session 在記憶體），但可用 consistent hashing 分散

7.3.3 Phase 2+ 定位：支援 1000+ 使用者

Multi-region 部署
CDN 前置
S3 / MinIO 大檔儲存
remote-proxy 支援 session migration（裝置換一個 proxy 節點不會斷）

7.3.4 架構預留

Phase 0 就要預留的擴展點：

狀態抽象（SessionStore 介面）→ 換 Redis 不動業務邏輯
AuthProvider 介面 → 換真實 Auth 不動業務邏輯
ObjectStorage 介面 → 換 S3 不動業務邏輯
api-server 儘量 stateless（除了 Auth 快取）
config-driven（環境變數 / YAML）

7.4 可用性（Availability）

7.4.1 Phase 0 SLO（內部使用）

指標	目標
api-server uptime	95%（有 bug 接受）
remote-proxy uptime	99%（影響面大，較嚴）
前端可訪問	99%（CDN）

7.4.2 Phase 1 SLO（外部早期採用者）

指標	目標
Overall uptime	99%（月最多 7 小時 downtime）
Tunnel session 存活率	99.5%
API 成功率	99.5%

7.4.3 降級策略

Tunnel 斷線時：

前端顯示「裝置離線」狀態，推論頁面明確提示
自動重連（指數退避）
不要讓整個 session 失效

Backend 崩潰時：

前端顯示「服務暫時無法使用」Offline Overlay（沿用 local-tool 的 pattern）
WebSocket 自動重連
使用者重新整理頁面即可恢復

Converter API 不可用時（Phase 2）：

轉檔功能暫時不可用，但其他功能不受影響
UI 顯示「轉檔服務暫時中斷」

7.4.4 Graceful Shutdown

api-server / remote-proxy 關機時：

不再接受新連線
已有連線完成後才關
廣播 system.shutdown-imminent WebSocket 事件讓前端做準備
（沿用 local-tool 的 /api/system/shutdown-notify pattern）

7.5 可觀測性（Observability）

7.5.1 Phase 0 最小要求

結構化 log：JSON 格式，含 user_id / request_id / device_id
log level：INFO / WARN / ERROR / DEBUG
記錄每個 API 請求（method、path、status、duration、user_id）
記錄每個 tunnel session 生命週期事件（建立、斷線、重連）

7.5.2 Phase 1 加強

Metrics：Prometheus 格式
- HTTP 請求數 / 延遲分佈 by endpoint
- Tunnel session 數 by status
- 推論請求數 by user / device
- 錯誤率 by endpoint
Tracing：OpenTelemetry，跨 api-server ↔ remote-proxy ↔ agent 的 trace
Dashboards：Grafana，關鍵指標視覺化
Alerting：錯誤率異常、tunnel 大量斷線等

7.5.3 Phase 2 加強

使用者層級的 analytics（需尊重 privacy）
Business metrics：WAD、Pairing conversion、推論量

7.6 相容性與支援

7.6.1 瀏覽器支援

瀏覽器	支援版本
Chrome	最新 3 個版本
Firefox	最新 3 個版本
Safari	最新 2 個版本
Edge	最新 3 個版本
IE	❌ 不支援

7.6.2 Local Agent 支援

平台	支援版本
macOS	14+ (x86_64)
Windows	10+ (x64)
Linux	Ubuntu 22.04+ (x86_64)
ARM	❌ Phase 0 不支援（local-tool 限制）

7.6.3 多語系（i18n）

Phase 0：繁體中文 + English（沿用 local-tool）
Phase 2：加簡體中文、日文

7.6.4 無障礙（a11y）

Phase 0：沿用 local-tool 的 a11y 水準（Radix UI 內建 a11y）
基本要求：鍵盤操作可行、重要元素有 aria-label
Phase 1：做 WCAG 2.1 AA 自動化測試（axe-core）

7.7 部署與維運

7.7.1 部署方式

Phase 0：

Docker Compose 本機啟動
兩個 container：api-server + remote-proxy
前端：靜態部署（Vercel / Netlify / S3+CloudFront）
儲存：local filesystem

Phase 1：

仍以 Docker 為主
加上 PostgreSQL + Redis
Cloud-agnostic（AWS / GCP / self-hosted 皆可）
加 ALB / Cloud LB

Phase 2：

Kubernetes（如有需要多節點）
Multi-region

7.7.2 CI/CD

Phase 0：手動 build + deploy（GitHub Actions on main push 可選）
Phase 1：GitHub Actions，每 PR 跑測試，merge 自動 deploy 到 staging
Phase 2：Blue/green deployment

7.7.3 Backup

Phase 1 起：DB 每日 backup，保留 30 天
模型檔：S3 有 versioning

7.8 法規與合規（Phase 1+ 才認真處理）

Phase 0 內部使用，不需要。Phase 1 外部開放前要完成：

Terms of Service
Privacy Policy（明列哪些資料被收集、如何使用）
Cookie Policy（有用 cookie）
GDPR（如果要對歐洲用戶開放）
台灣個資法（主場市場）

連結

上一章：User Stories
下一章：介面契約
跳回：PRD 索引

8.4 KiB Raw Blame History Unescape Escape