341 行
7.9 KiB
Markdown
341 行
7.9 KiB
Markdown
# Tennis Training Hub - API接口文档
|
||
|
||
本文档详细描述了Tennis Training Hub的所有tRPC API接口，包括输入参数、输出格式和认证要求。
|
||
|
||
## 认证说明
|
||
|
||
所有标记为 **需认证** 的接口需要用户已登录（通过Session Cookie）。未认证请求将返回 `UNAUTHORIZED` 错误。
|
||
|
||
## 接口列表
|
||
|
||
### 1. 认证模块 (`auth`)
|
||
|
||
#### `auth.me` - 获取当前用户信息
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 类型 | Query |
|
||
| 认证 | 不需要 |
|
||
| 输入 | 无 |
|
||
| 输出 | `User | null` |
|
||
|
||
返回当前登录用户的完整信息，未登录返回 `null`。
|
||
|
||
#### `auth.loginWithUsername` - 用户名登录
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 类型 | Mutation |
|
||
| 认证 | 不需要 |
|
||
| 输入 | `{ username: string }` |
|
||
| 输出 | `{ user: User, isNew: boolean }` |
|
||
|
||
**输入验证：**
|
||
- `username`：1-64个字符
|
||
|
||
若用户名不存在则自动创建新账户。
|
||
|
||
#### `auth.logout` - 退出登录
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 类型 | Mutation |
|
||
| 认证 | 不需要 |
|
||
| 输出 | `{ success: true }` |
|
||
|
||
---
|
||
|
||
### 2. 用户资料模块 (`profile`)
|
||
|
||
#### `profile.stats` - 获取用户统计数据
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 类型 | Query |
|
||
| 认证 | **需认证** |
|
||
| 输出 | `UserStats` |
|
||
|
||
#### `profile.update` - 更新用户资料
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 类型 | Mutation |
|
||
| 认证 | **需认证** |
|
||
| 输入 | `{ skillLevel?: "beginner" \| "intermediate" \| "advanced", trainingGoals?: string }` |
|
||
| 输出 | `{ success: true }` |
|
||
|
||
---
|
||
|
||
### 3. 训练计划模块 (`plan`)
|
||
|
||
#### `plan.generate` - AI生成训练计划
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 类型 | Mutation |
|
||
| 认证 | **需认证** |
|
||
| 输入 | `{ skillLevel: enum, durationDays: number, focusAreas?: string[] }` |
|
||
| 输出 | `{ planId: number, plan: TrainingPlanData }` |
|
||
|
||
**输入验证：**
|
||
- `skillLevel`：`"beginner"` / `"intermediate"` / `"advanced"`
|
||
- `durationDays`：1-30
|
||
- `focusAreas`：可选，如 `["正手", "脚步"]`
|
||
|
||
#### `plan.list` - 获取用户所有训练计划
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 类型 | Query |
|
||
| 认证 | **需认证** |
|
||
| 输出 | `TrainingPlan[]` |
|
||
|
||
#### `plan.active` - 获取当前激活的训练计划
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 类型 | Query |
|
||
| 认证 | **需认证** |
|
||
| 输出 | `TrainingPlan | null` |
|
||
|
||
#### `plan.adjust` - AI自动调整训练计划
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 类型 | Mutation |
|
||
| 认证 | **需认证** |
|
||
| 输入 | `{ planId: number }` |
|
||
| 输出 | `{ success: true, adjustmentNotes: string }` |
|
||
|
||
---
|
||
|
||
### 4. 视频管理模块 (`video`)
|
||
|
||
#### `video.upload` - 上传训练视频
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 类型 | Mutation |
|
||
| 认证 | **需认证** |
|
||
| 输入 | `{ title: string, format: string, fileSize: number, fileBase64: string, exerciseType?: string }` |
|
||
| 输出 | `{ videoId: number, url: string }` |
|
||
|
||
#### `video.list` - 获取用户视频列表
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 类型 | Query |
|
||
| 认证 | **需认证** |
|
||
| 输出 | `TrainingVideo[]` |
|
||
|
||
#### `video.get` - 获取视频详情
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 类型 | Query |
|
||
| 认证 | **需认证** |
|
||
| 输入 | `{ videoId: number }` |
|
||
| 输出 | `TrainingVideo` |
|
||
|
||
#### `video.updateStatus` - 更新视频分析状态
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 类型 | Mutation |
|
||
| 认证 | **需认证** |
|
||
| 输入 | `{ videoId: number, status: "pending" \| "analyzing" \| "completed" \| "failed" }` |
|
||
| 输出 | `{ success: true }` |
|
||
|
||
---
|
||
|
||
### 5. 姿势分析模块 (`analysis`)
|
||
|
||
#### `analysis.save` - 保存姿势分析结果
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 类型 | Mutation |
|
||
| 认证 | **需认证** |
|
||
| 输入 | 见下表 |
|
||
| 输出 | `{ analysisId: number }` |
|
||
|
||
**输入参数：**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| videoId | number | 是 | 关联视频ID |
|
||
| overallScore | number | 否 | 总体评分(0-100) |
|
||
| poseMetrics | object | 否 | 关节角度等详细指标 |
|
||
| detectedIssues | array | 否 | 检测到的问题列表 |
|
||
| exerciseType | string | 否 | 动作类型 |
|
||
| framesAnalyzed | number | 否 | 分析帧数 |
|
||
| shotCount | number | 否 | 击球次数 |
|
||
| avgSwingSpeed | number | 否 | 平均挥拍速度 |
|
||
| maxSwingSpeed | number | 否 | 最大挥拍速度 |
|
||
| totalMovementDistance | number | 否 | 总移动距离 |
|
||
| strokeConsistency | number | 否 | 击球一致性(0-100) |
|
||
| footworkScore | number | 否 | 脚步评分(0-100) |
|
||
| fluidityScore | number | 否 | 流畅性评分(0-100) |
|
||
| keyMoments | array | 否 | 关键时刻标记 |
|
||
| movementTrajectory | array | 否 | 运动轨迹数据 |
|
||
|
||
保存分析结果后会自动触发NTRP评分重新计算。
|
||
|
||
#### `analysis.getCorrections` - AI生成矫正建议
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 类型 | Mutation |
|
||
| 认证 | **需认证** |
|
||
| 输入 | `{ poseMetrics: object, exerciseType: string, detectedIssues: array }` |
|
||
| 输出 | `{ corrections: string }` |
|
||
|
||
#### `analysis.list` - 获取用户所有分析记录
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 类型 | Query |
|
||
| 认证 | **需认证** |
|
||
| 输出 | `PoseAnalysis[]` |
|
||
|
||
#### `analysis.getByVideo` - 获取视频的分析结果
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 类型 | Query |
|
||
| 认证 | **需认证** |
|
||
| 输入 | `{ videoId: number }` |
|
||
| 输出 | `PoseAnalysis | null` |
|
||
|
||
---
|
||
|
||
### 6. 训练记录模块 (`record`)
|
||
|
||
#### `record.create` - 创建训练记录
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 类型 | Mutation |
|
||
| 认证 | **需认证** |
|
||
| 输入 | `{ exerciseName: string, planId?: number, durationMinutes?: number, notes?: string, poseScore?: number }` |
|
||
| 输出 | `{ recordId: number }` |
|
||
|
||
#### `record.complete` - 标记训练完成
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 类型 | Mutation |
|
||
| 认证 | **需认证** |
|
||
| 输入 | `{ recordId: number, poseScore?: number }` |
|
||
| 输出 | `{ success: true }` |
|
||
|
||
#### `record.list` - 获取训练记录列表
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 类型 | Query |
|
||
| 认证 | **需认证** |
|
||
| 输入 | `{ limit?: number }` (默认50) |
|
||
| 输出 | `TrainingRecord[]` |
|
||
|
||
---
|
||
|
||
### 7. 评分模块 (`rating`)
|
||
|
||
#### `rating.history` - 获取NTRP评分历史
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 类型 | Query |
|
||
| 认证 | **需认证** |
|
||
| 输出 | `RatingHistory[]` |
|
||
|
||
#### `rating.current` - 获取当前NTRP评分
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 类型 | Query |
|
||
| 认证 | **需认证** |
|
||
| 输出 | `{ rating: number }` |
|
||
|
||
---
|
||
|
||
### 8. 打卡模块 (`checkin`)
|
||
|
||
#### `checkin.today` - 获取今日打卡状态
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 类型 | Query |
|
||
| 认证 | **需认证** |
|
||
| 输出 | `DailyCheckin | null` |
|
||
|
||
#### `checkin.do` - 执行打卡
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 类型 | Mutation |
|
||
| 认证 | **需认证** |
|
||
| 输入 | `{ notes?: string, minutesTrained?: number }` (可选) |
|
||
| 输出 | `{ checkin: DailyCheckin, streak: number, newBadges: Badge[] }` |
|
||
|
||
打卡后会自动检查并授予新徽章。
|
||
|
||
#### `checkin.history` - 获取打卡历史
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 类型 | Query |
|
||
| 认证 | **需认证** |
|
||
| 输入 | `{ limit?: number }` (默认60) |
|
||
| 输出 | `DailyCheckin[]` |
|
||
|
||
---
|
||
|
||
### 9. 徽章模块 (`badge`)
|
||
|
||
#### `badge.list` - 获取用户徽章（含未获得）
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 类型 | Query |
|
||
| 认证 | **需认证** |
|
||
| 输出 | `BadgeWithStatus[]` |
|
||
|
||
返回所有24种徽章，标记已获得/未获得状态。
|
||
|
||
#### `badge.check` - 检查并授予新徽章
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 类型 | Mutation |
|
||
| 认证 | **需认证** |
|
||
| 输出 | `{ newBadges: Badge[] }` |
|
||
|
||
#### `badge.definitions` - 获取所有徽章定义
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 类型 | Query |
|
||
| 认证 | 不需要 |
|
||
| 输出 | `BadgeDefinition[]` |
|
||
|
||
---
|
||
|
||
### 10. 排行榜模块 (`leaderboard`)
|
||
|
||
#### `leaderboard.get` - 获取排行榜
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 类型 | Query |
|
||
| 认证 | **需认证** |
|
||
| 输入 | `{ sortBy?: enum, limit?: number }` |
|
||
| 输出 | `LeaderboardEntry[]` |
|
||
|
||
**sortBy选项：**
|
||
- `"ntrpRating"` - 按NTRP评分排名（默认）
|
||
- `"totalMinutes"` - 按训练时长排名
|
||
- `"totalSessions"` - 按训练次数排名
|
||
- `"totalShots"` - 按击球数排名
|