User Profiles API
使用者資料完整 API — Profile CRUD、區間設定、目標、比賽紀錄。
GET /users/{uid}
取得使用者完整資料。
Headers
| Header | 值 | 必填 |
|---|---|---|
| `x-api-key` | API Key | ✅ |
Response (200)
| 欄位 | 類型 | 說明 |
|---|---|---|
| `user_id` | string | 使用者 ID（Firebase UID） |
| `username` | string | 使用者名稱（唯一） |
| `email` | string | |
| `display_name` | string | 顯示名稱 |
| `gender` | string | 性別（`male`, `female`, `other`） |
| `weight` | number | 體重（kg） |
| `height` | number | 身高（cm） |
| `membership_roles` | array | 角色列表 |
| `org_id` | string | 所屬組織 ID |
| `coach` | boolean | 是否為教練 |
| `integrations` | object | 第三方整合狀態 |
| `zones` | object | 心率/配速區間 |
| `app_version` | string | App 版本 |
| `platform` | string | 平台（`ios`, `android`） |
| `language` | string | 語言偏好 |
| `unit_system` | string | 單位系統（`metric`, `imperial`） |
| `country` | string | 國家 |
| `created_at` | number | 建立時間（epoch ms） |
| `last_login` | number | 最後登入時間（epoch ms） |
Integrations 物件
| 欄位 | 類型 | 說明 |
|---|---|---|
| `strava` | object | `{connected: bool, athlete_id: string}` |
| `garmin` | object | `{connected: bool, garmin_user_id: string}` |
| `apple_health` | object | `{connected: bool}` |
Zones 物件
| 欄位 | 類型 | 說明 |
|---|---|---|
| `heartrate` | object | 心率區間 |
| `pace` | object | 配速區間 |
Heartrate Zones
| 欄位 | 類型 | 說明 |
|---|---|---|
| `rest` | number | 安靜心率（bpm） |
| `max` | number | 最大心率（bpm） |
| `z1` | number | Z1 上限（bpm） |
| `z2` | number | Z2 上限（bpm） |
| `z3` | number | Z3 上限（bpm） |
| `z4` | number | Z4 上限（bpm） |
| `z5` | number | Z5 = max（bpm） |
Pace Zones
| 欄位 | 類型 | 說明 |
|---|---|---|
| `z1` | number | Z1 下限（秒/公里，最慢） |
| `z2_lower` | number | Z2 下限 |
| `z2_upper` | number | Z2 上限 |
| `z3_lower` | number | Z3 下限 |
| `z3_upper` | number | Z3 上限 |
| `z4_lower` | number | Z4 下限 |
| `z4_upper` | number | Z4 上限 |
| `z5` | number | Z5 上限（秒/公里，最快） |
GET /users
取得使用者列表。
Query Parameters
| 參數 | 類型 | 說明 |
|---|---|---|
| `page_size` | int | 每頁數量 |
PUT /users/{uid}
更新使用者資料。只傳需要更新的欄位。
Request Body（所有欄位選填）
| 參數 | 類型 | 說明 |
|---|---|---|
| `username` | string | 使用者名稱 |
| `display_name` | string | 顯示名稱 |
| `gender` | string | 性別 |
| `weight` | number | 體重（kg） |
| `height` | number | 身高（cm） |
| `zones` | object | 區間設定 |
| `language` | string | 語言 |
| `unit_system` | string | 單位系統 |
POST /users
建立使用者。
Request Body
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `username` | string | ✅ | 使用者名稱 |
| `email` | string | ✅ |
GET /users/{uid}/public
取得使用者的公開資料（有限欄位）。
GET /users/check-username
檢查使用者名稱是否可用。
Query Parameters
| 參數 | 類型 | 說明 |
|---|---|---|
| `username` | string | 要檢查的名稱 |
Response (200)
{"available": true}
PATCH /users/me/preferences
更新偏好設定。
Request Body
| 參數 | 類型 | 說明 |
|---|---|---|
| `language` | string | 語言（`zh-TW`, `en`, `ja`） |
| `unit_system` | string | 單位（`metric`, `imperial`） |
| `notification_enabled` | boolean | 通知開關 |
GET /users/{user_id}/goals
取得訓練目標。
Response (200)
| 欄位 | 類型 | 說明 |
|---|---|---|
| `monthly_distance` | number | 月跑量目標（km） |
| `weekly_runs` | number | 每週跑步次數 |
PUT /users/{user_id}/goals
更新訓練目標。
GET /users/{user_id}/race-histories
取得比賽紀錄列表。
POST /users/{user_id}/race-histories
新增比賽紀錄。
Request Body
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `race_name` | string | ✅ | 比賽名稱 |
| `race_date` | string | ✅ | 日期（YYYY-MM-DD） |
| `distance` | string | ✅ | 距離（`5k`, `10k`, `half`, `full`） |
| `finish_time` | string | ✅ | 完賽時間（HH:MM:SS） |
PUT /users/{user_id}/race-histories/{race_id}
更新比賽紀錄。
DELETE /users/{user_id}/race-histories/{race_id}
刪除比賽紀錄。