Groups API
跑團群組完整 API — CRUD、活動列表、群組統計。
POST /groups
建立群組。
Headers
| Header | 值 | 必填 |
|---|---|---|
| `x-api-key` | API Key | ✅ |
Request Body
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `name` | string | ✅ | 群組名稱 |
| `owner_id` | string | ✅ | 擁有者 ID |
| `description` | string | ❌ | 描述 |
| `privacy` | string | ❌ | 隱私設定（`public` / `private`，預設 `public`） |
Response (201)
{"group_id": "abc123", "message": "Group created"}
GET /groups
取得群組列表。
行為
- 教練（membership_roles 含
coach，有 org_id）：回傳組織的所有群組 - 選手：回傳自己擁有/加入的群組
Query Parameters
| 參數 | 類型 | 說明 |
|---|---|---|
| `user_id` | string | 使用者 ID |
| `page_size` | int | 每頁數量（預設 20） |
Response (200)
| 欄位 | 類型 | 說明 |
|---|---|---|
| `groups` | array | 群組列表 |
| `count` | number | 總數 |
| `page_size` | number | 每頁數量 |
Group 物件
| 欄位 | 類型 | 說明 |
|---|---|---|
| `group_id` | string | 群組 ID |
| `name` | string | 名稱 |
| `description` | string | 描述 |
| `owner_id` | string | 擁有者 ID |
| `org_id` | string | 組織 ID |
| `privacy` | string | 隱私設定 |
| `members_count` | number | 成員數 |
| `created_at` | number | 建立時間（epoch ms） |
GET /groups/{group_id}
取得群組詳情。
PUT /groups/{group_id}
更新群組。
Request Body
| 參數 | 類型 | 說明 |
|---|---|---|
| `name` | string | 新名稱 |
| `description` | string | 新描述 |
| `privacy` | string | 新隱私設定 |
DELETE /groups/{group_id}
刪除群組。
GET /groups/{group_id}/activities
取得群組成員的活動列表（Activity Feed）。
Query Parameters
| 參數 | 類型 | 說明 |
|---|---|---|
| `page_size` | int | 每頁數量 |
| `last_created_at` | number | 分頁游標 |
GET /groups/{group_id}/stats
取得群組統計。
Response (200)
| 欄位 | 類型 | 說明 |
|---|---|---|
| `total_members` | number | 成員總數 |
| `active_members` | number | 本週活躍成員 |
| `total_distance` | number | 總跑量（公尺） |
| `total_activities` | number | 總活動數 |
| `avg_distance_per_member` | number | 人均跑量 |