# 7. 非功能性需求 — visionA Cloud

> 父文件：[PRD.md](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](user-stories.md)
- 下一章：[介面契約](interface-contracts.md)
- 跳回：[PRD 索引](PRD.md)