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）。
285 lines
8.4 KiB
Markdown
285 lines
8.4 KiB
Markdown
# 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)
|