本章節記錄 Fugu 開發的行動應用程式 與 SolidFocus 後端 之間的 API 串接設計。

目前後端設計提供的內容:

• Endpoint 路徑與 HTTP methods
• 高階描述 (中文)
• 資料庫 schema (SQLModel classes)
• 架構概念 (Offline-First, JSONB 使用)
• Sequence diagrams 展示同步流程

尚未提供的內容:

• Request/response body 結構
• HTTP status codes 與錯誤回應
• 身份驗證細節 (JWT 格式、token 過期時間)
• 欄位層級驗證規則
• 分頁格式

📚 本章節文件結構¶

API 規格說明¶

• 目前定義的 endpoints
• Request/Response 格式：客戶未定義 - 需要討論
• 錯誤處理：客戶未定義 - 需要討論

資料模型¶

• 資料庫 Schema (v3.0)
• 實體關聯圖 (ERD)
• 欄位描述與限制條件
• 已更新：與客戶的 SQLModel 規格對齊
• 重大變更：欄位重新命名 (例如：workout_total_duration → total_duration_seconds)

🔄 v3.0 主要變更摘要¶

1. 離線優先架構 (Offline-First Architecture)：以 APP 為中心的設計
2. 批次上傳 (Batch Upload)：新增 POST /sessions/batch_upload endpoint
3. 移除 User.bound_device_id
4. 強制同步統計 (Force-Sync Stats)：PATCH /users/me/stats 讓 APP 覆寫伺服器資料
5. 統一 SSO (Unified SSO)：單一 POST /auth/sso/{provider} endpoint
6. Meta APIs：Schema 探索與 app 版本檢查
7. 欄位重新命名 (Field Renames)：與客戶規格對齊