API 規格

Previous Next

API 概述

Base URL

Production:  https://api.solidfocus.com/v1
Staging:     https://api-staging.solidfocus.com/v1
Development: http://localhost:8000/v1

注意：Base URL 為預想值，需與 SolidFocus RD 團隊確認。

架構設計 (v3.0)

離線優先設計 (Offline-First Design):

  • APP 是運動數據的真實來源 (Source of Truth)
  • Server 扮演歸檔與同步協調者角色 (「數據歸檔中心」)
  • APP 在本地計算所有指標 (卡路里、距離、XP)
  • 使用批次上傳策略進行 session 同步
  • Store-and-Forward 模式：APP 先寫入本地 SQLite，上線後再同步

核心原則:

  • 離線優先 (Offline First)：APP 是第一個資料儲存點 (Source of Truth)
  • 異質數據標準化：使用 PostgreSQL JSONB 儲存異質裝置數據 (bike, rower, treadmill)
  • 儲存後轉發 (Store-and-Forward)：APP 總是先寫入本地 DB，之後批次同步

以下項目尚未定義 - 需要討論:

  • Content-Type 格式 (假設為 JSON)
  • 日期/時間格式 (假設為 ISO 8601 UTC)
  • Request/Response body 結構
  • 錯誤回應格式
  • HTTP status codes
  • Authentication header 格式

狀態：這些項目應與 SolidFocus RD 團隊討論並達成共識。

身份驗證與授權

預設的身份驗證方式

  • JWT (JSON Web Token) 為基礎的身份驗證
  • Bearer token scheme (預設)
  • Access token + Refresh token 模式 (預設)

狀態：需與 SolidFocus RD 團隊確認:

  • Token 格式與 claims
  • Token 過期時間
  • Authorization header 格式
  • Token 撤銷機制

身份驗證 APIs

目前定義了以下身份驗證端點與描述。尚未提供 request/response 格式。

Method Endpoint 客戶描述
POST /auth/register 帳號註冊 (僅限 Email/Password)
POST /auth/login 帳號登入 (回傳 JWT)
POST /auth/password/request-reset 忘記密碼 (寄送驗證碼/信件)
POST /auth/password/reset 重設密碼 (帶入驗證碼)
POST /auth/sso/{provider} SSO 登入 (provider = apple/google/facebook)
POST /auth/logout 登出 (撤銷 Refresh Token)
POST /auth/refresh 刷新 Access Token

需要討論的項目:

  1. Request/response body 結構
  2. 錯誤回應格式
  3. 要使用的 HTTP status codes
  4. 欄位命名慣例
  5. Token 過期時間

使用者 APIs

目前定義了以下使用者端點與描述。尚未提供 request/response 格式。

Method Endpoint 客戶描述
GET /users/me 取得個人資料 (含 UserStat)
PATCH /users/me 更新身高、體重、暱稱、性別
PATCH /users/me/stats 同步累計數據 (強制以 APP 端的累計里程/XP/等級覆蓋伺服器)
POST /users/me/avatar 上傳大頭貼

課程 APIs

目前定義了以下課程端點:

Method Endpoint 客戶描述
GET /trainings 取得課程列表 (支援設備篩選、分頁)
GET /trainings/{id} 取得單一課程詳細設定
  • 支援使用 device_type 參數篩選
  • 回傳課程 metadata，包含影片 URLs
  • 使用 JSONB 儲存彈性的 settings 與 detail 欄位 (參見資料庫 schema)

運動紀錄 APIs

目前定義了以下 session 端點:

Method Endpoint 客戶描述
POST /sessions/batch_upload 批次同步 離線生成的運動紀錄
POST /sessions 單筆運動紀錄上傳
GET /sessions 取得歷史運動列表
GET /sessions/{id} 取得運動詳情 (含曲線圖數據)
DELETE /sessions/{id} 刪除運動紀錄

規格架構設計:

冪等性設計 (Idempotency Design):

  • APP 產生 client_session_uuid (UUIDv4)
  • Server 在建立前檢查 client_session_uuid 是否已存在
  • 重複上傳回傳成功 (冪等行為)

批次上傳流程 (來自客戶 sequence diagram):

APP → POST /sessions/batch_upload
     Header: X-Idempotency-Key (規格中提及)

Server 檢查 client_session_uuid
├─ 已存在 → 200 OK (忽略寫入)
└─ 新紀錄 → 201 Created → 更新 UserStats

離線優先模式 (Offline-First Pattern):

  • APP 在本地儲存 sessions，狀態為 Status: PENDING
  • 網路可用時批次上傳
  • 上傳成功後標記為 Status: SYNCED

資料庫 Schema (WorkoutSession model):

  • 使用 PostgreSQL JSONB 儲存裝置無關的 metrics 資料
  • 欄位：client_session_id, device_type, source_type, metrics_summary, time_series_data
  • 完整 schema 請參見 資料模型

Meta APIs

目前定義了以下 meta 端點:

Method Endpoint 客戶描述
GET /meta/schemas 取得各器材 (Rower/Bike) 的數據欄位定義 (供 VUE 後台動態渲染)
GET /meta/app_version 檢查 APP 是否需要強制更新

用途:

  • /meta/schemas：提供裝置特定的欄位定義，供後台管理介面動態渲染使用
  • /meta/app_version：檢查版本，判斷是否需要強制更新 APP

內容總結

目前已定義:

  1. Endpoint 路徑與 HTTP methods
  2. 高階描述 (中文)
  3. 資料庫 schema (SQLModel classes 與欄位型別)
  4. 架構概念 (Offline-First, Store-and-Forward, JSONB 使用)
  5. Sequence diagram 顯示同步流程

尚未定義:

  1. Request body 結構
  2. Response body 結構
  3. HTTP status codes (200, 201, 400, 403, etc.)
  4. 錯誤回應格式
  5. 錯誤代碼 (例如：validation_error, duplicate_session)
  6. Header 需求 (除了提及 X-Idempotency-Key)
  7. 分頁細節
  8. Query parameter 格式
API 概要 資料模型