◀ Previous: Chapter 1 | Next: Chapter 3 ▶
本章以高階視角說明系統之主要架構設計與元件責任分工，涵蓋行動應用程式（App）、後端服務與雲端資源之間的關係，以及各元件在系統中的角色定位。
本章重點在於描述系統的核心組成、跨元件的主要資料流與使用者操作的主流程（happy path），以協助不同角色（App 工程師、後端工程師、設備與系統整合人員）快速理解整體系統運作方式與設計假設。
為避免重複或過早進入實作細節，本章不涵蓋以下內容：¶
- BLE 裝置之 GATT/Characteristic 細節與通訊規格
- API 之逐一 endpoint 定義、request/response schema
- 資料庫 table schema 與索引設計
- 各類錯誤處理、例外情境與重試策略
上述細部設計與規格將於後續章節（Component-level Design、Data & Contract Specs、Error Handling & Operational Flows）中分別說明。
Component Diagram¶
┌────────────────────────────────────────────────────────────────────┐
│ 系統組件圖 │
│ │
│ ┌──────────────┐ │
│ │ 健身設備 │◄──── FTMS/BLE │
│ │ │ │
│ └──────────────┘ │
│ ▲ │
│ │ │
│ │ ┌────────────────────────────┐ │
│ │ │ App │ │
│ │ │ │ │
│ │ │ ┌──────────────────────┐ │ │
│ └──────────────────────┼──│ Course Presets │ │ │
│ │ │ Interaction │ │ │
│ ┌──────────────┐ │ │ Settings │ │ │
│ │ 其他設備 │◄──── BLE │ └──────────────────────┘ │ │
│ │ (如心率帶) │ │ │ │
│ └──────────────┘ │ ┌──────────────────────┐ │ │
│ │ │ UI │ │ │
│ │ └──────────────────────┘ │ │
│ │ │ │
│ │ ┌──────────────────────┐ │ │
│ │ │ Workout Engine │ │ │
│ │ └──────────────────────┘ │ │
│ │ │ │
│ │ ┌──────────────────────┐ │ │
│ │ │ Local Storage │ │ │
│ │ │ Auth │ │ │
│ │ └──────────────────────┘ │ │
│ │ │ │
│ │ ┌──────────────────────┐ │ │
│ │ │ BLE Manager │ │ │
│ │ │ Pose Service │ │ │
│ │ │ API Client │ │ │
│ │ └──────────────────────┘ │ │
│ └────────┬───────────────────┘ │
│ │ │
│ │ HTTPS │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Cloud │ │
│ │ │ │
│ │ Python Backend │ │
│ │ API │ │
│ │ │ │
│ │ Object Storage │ │
│ │ │ │
│ └─────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────┘本圖為系統之 Component Diagram，說明 App、後端服務與雲端資源之主要元件構成與責任分工。App 端以 Workout Engine 為核心，整合健身設備、相機與使用者操作所產生之事件，並透過 API 與雲端服務互動。本圖僅描述高階結構與元件關係，細部實作與資料規格將於後續章節說明。
Deployment / Cloud Architecture¶
本區為 Fugu 先暫時列出，實際上仍由城紹規劃決定。
雲端架構概述¶
- 後端服務：單體 Python 應用（FastAPI/Flask）
- 資料庫：PostgreSQL（單一實例）
- 物件儲存：AWS S3/Azure Blob Storage/Google Cloud Storage
- CDN：CloudFront/Azure CDN（用於影片串流）
- 部署環境：單一區域（台灣或亞太）
- 負載平衡：基本 Load Balancer（AWS ALB/Azure Load Balancer）
影片內容託管策略¶
- 儲存：原始 mp4 影片存放於 Object Storage
- 串流：透過 CDN 加速分發
High-level User Workout Flow¶
以下為使用者完成一次運動的主要路徑（Happy Path）之序列圖：
User App Auth BLE Fitness Workout Local Backend Database
Mgr Device Engine Storage API
│ │ │ │ │ │ │ │ │
│─(1)───>│ │ │ │ │ │ │ │
│ Open │ │ │ │ │ │ │ │
│ app │ │ │ │ │ │ │ │
│ │─(2)───>│ │ │ │ │ │ │
│ │ Check │ │ │ │ │ │ │
│ │ login │ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │
│ │ └───┐ │ │ │ │ │ │
│ │ ┌───┘ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │
│ │<───────┤ │ │ │ │ │ │
│ │ No │ │ │ │ │ │ │
│ │ session│ │ │ │ │ │ │
│<───────┤ │ │ │ │ │ │ │
│ Show │ │ │ │ │ │ │ │
│ login │ │ │ │ │ │ │ │
│ screen │ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │
│ │ │─(3)────────────────────────────────────────>│ │
│ │ │ Token │ │ │ │ │ │
│ │ │ valid? │ │ │ │ │ │
│ │ │ │ │ │ │ │─(4)───>│
│ │ │ │ │ │ │ │Validate│
│ │ │ │ │ │ │ │<───────┤
│ │ │ │ │ │ │ │ OK │
│ │ │<────────────────────────────────────────────┤ │
│ │ │ │ │ │ │ OK│ │
│ │<─(5)───┤ │ │ │ │ │ │
│ │ Logged │ │ │ │ │ │ │
│ │ in │ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │
│ │─(6)────────────>│ │ │ │ │ │
│ │ Check │ │ │ │ │ │ │
│ │ BLE │ │ │ │ │ │ │
│ │ perms │ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │
│ │ │ └───┐ │ │ │ │ │
│ │ │ ┌───┘ │ │ │ │ │
│ │ │ │ Scan │ │ │ │ │
│ │ │ │ │ │ │ │ │
│ │ │ │─(7)───>│ │ │ │ │
│ │ │ │Connect │ │ │ │ │
│ │ │ │─(8)───>│ │ │ │ │
│ │ │ │Subscribe │ │ │ │
│ │ │ │ notify │ │ │ │ │
│ │ │ │<───────┤ │ │ │ │
│ │ │ │ Ready │ │ │ │ │
│ │<─(9)───────────┤ │ │ │ │ │
│ │ Device │ │ │ │ │ │ │
│ │ ready │ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │
│─(10)──>│ │ │ │ │ │ │ │
│ Start │ │ │ │ │ │ │ │
│workout │ │ │ │ │ │ │ │
│ │─(11)───────────────────────────>│ │ │ │
│ │ │ │ Start │ │ │ │ │
│ │ │ │ session│ │ │ │ │
│ │ │ │ │<─(12)──┤ │ │ │
│ │ │ │ │ Start │ │ │ │
│ │ │ │ │workout │ │ │ │
│ │ │ │ │(ctrl) │ │ │ │
│ │ │ │ │ │ │ │ │
│ │ │ ┌───────────────────────────┐ │ │ │
│ │ │ │ LOOP: During workout │ │ │ │
│ │ │ │ │ │ │ │ │ │ │
│ │ │ │ │ │─(13)──>│ │ │ │ │
│ │ │ │ │ │ Live │ │ │ │ │
│ │ │ │ │ │metrics │ │ │ │ │
│ │ │ │ │<───────┼────────┤ │ │ │ │
│ │ │ │ │Metrics │ │ │ │ │ │
│ │ │ │ │ events │ │ │ │ │ │
│ │ │ │ │ │ │─(14)──>│ │ │ │
│ │ │ │ │ │ │ Append │ │ │ │
│ │ │ │ │ │ │records │ │ │ │
│ │ │ └───────────────────────────┘ │ │ │
│ │ │ │ │ │ │ │ │
│─(15)──>│ │ │ │ │ │ │ │
│ End │ │ │ │ │ │ │ │
│workout │ │ │ │ │ │ │ │
│ │─(16)───────────────────────────>│ │ │ │
│ │ │ │ End │ │ │ │ │
│ │ │ │ session│ │ │ │ │
│ │ │ │ │<─(17)──┤ │ │ │
│ │ │ │ │ Stop │ │ │ │
│ │ │ │ │workout │ │ │ │
│ │ │ │ │ │─(18)──>│ │ │
│ │ │ │ │ │Finalize│ │ │
│ │ │ │ │ │summary │ │ │
│ │ │ │ │ │ │ │ │
│ │ │ │ │ │─(19)───────────>│ │
│ │ │ │ │ │ Upload │ │ │
│ │ │ │ │ │summary │ │ │
│ │ │ │ │ │ and │ │ │
│ │ │ │ │ │metrics │ │ │
│ │ │ │ │ │ │ │─(20)──>│
│ │ │ │ │ │ │ │Persist │
│ │ │ │ │ │ │ │<───────┤
│ │ │ │ │ │ │ │ Stored │
│ │ │ │ │ │<─(21)──────────┤ │
│ │ │ │ │ │ Upload │ │ │
│ │ │ │ │ │success │ │ │
│ │<─(22)──────────────────────────┤ │ │ │
│ │ Show │ │ │ │ │ │ │
│ │workout │ │ │ │ │ │ │
│ │ result │ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │流程說明：
此流程描述使用者完成一次運動的主要路徑：App 啟動後先確認登入狀態，必要時透過後端 API 驗證或更新憑證。使用者開始運動後，Workout Engine 建立 session 並透過 BLE Manager 連接健身設備、訂閱即時數據通知；運動過程中接收的 metrics 事件會持續寫入本機儲存。運動結束時，Workout Engine 完成本次 session 的摘要資料，並將 summary 與 metrics 上傳至後端，由後端寫入資料庫，最後 App 顯示運動結果與摘要資訊。