Tennis Training Hub - API接口文档
本文档详细描述了Tennis Training Hub的所有tRPC API接口，包括输入参数、输出格式和认证要求。
认证说明
所有标记为 需认证 的接口需要用户已登录（通过Session Cookie）。未认证请求将返回 UNAUTHORIZED 错误。
接口列表
1. 认证模块 (auth)
auth.me - 获取当前用户信息
| 属性 |
值 |
| 类型 |
Query |
| 认证 |
不需要 |
| 输入 |
无 |
| 输出 |
`User |
返回当前登录用户的完整信息，未登录返回 null。
auth.loginWithUsername - 用户名登录
| 属性 |
值 |
| 类型 |
Mutation |
| 认证 |
不需要 |
| 输入 |
{ username: string } |
| 输出 |
{ user: User, isNew: boolean } |
输入验证：
若用户名不存在则自动创建新账户。
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[] } |
| 输出 |
{ taskId: string, task: BackgroundTask } |
输入验证：
skillLevel："beginner" / "intermediate" / "advanced"durationDays：1-30focusAreas：可选，如 ["正手", "脚步"]
plan.list - 获取用户所有训练计划
| 属性 |
值 |
| 类型 |
Query |
| 认证 |
需认证 |
| 输出 |
TrainingPlan[] |
plan.active - 获取当前激活的训练计划
| 属性 |
值 |
| 类型 |
Query |
| 认证 |
需认证 |
| 输出 |
`TrainingPlan |
plan.adjust - AI自动调整训练计划
| 属性 |
值 |
| 类型 |
Mutation |
| 认证 |
需认证 |
| 输入 |
{ planId: number } |
| 输出 |
{ taskId: string, task: BackgroundTask } |
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, imageUrls?: string[], imageDataUrls?: string[] } |
| 输出 |
{ taskId: string, task: BackgroundTask } |
该接口始终走后台任务。若提供 imageUrls 或 imageDataUrls，服务端会优先走多模态纠正链路，并把相对地址规范化为可公网访问的绝对 URL。
analysis.list - 获取用户所有分析记录
| 属性 |
值 |
| 类型 |
Query |
| 认证 |
需认证 |
| 输出 |
PoseAnalysis[] |
analysis.getByVideo - 获取视频的分析结果
| 属性 |
值 |
| 类型 |
Query |
| 认证 |
需认证 |
| 输入 |
{ videoId: number } |
| 输出 |
`PoseAnalysis |
6. 训练记录模块 (record)
5.1 后台任务模块 (task)
task.list - 获取当前用户后台任务
| 属性 |
值 |
| 类型 |
Query |
| 认证 |
需认证 |
| 输入 |
{ limit?: number } |
| 输出 |
BackgroundTask[] |
task.get - 获取单个后台任务
| 属性 |
值 |
| 类型 |
Query |
| 认证 |
需认证 |
| 输入 |
{ taskId: string } |
| 输出 |
`BackgroundTask |
task.retry - 重试失败任务
| 属性 |
值 |
| 类型 |
Mutation |
| 认证 |
需认证 |
| 输入 |
{ taskId: string } |
| 输出 |
{ task: BackgroundTask } |
task.createMediaFinalize - 提交录制归档后台任务
| 属性 |
值 |
| 类型 |
Mutation |
| 认证 |
需认证 |
| 输入 |
{ sessionId: string, title: string, exerciseType?: string } |
| 输出 |
{ taskId: string, task: BackgroundTask } |
该接口会校验媒体会话所属用户，并由后台 worker 轮询 Go 媒体服务状态，归档完成后自动登记到视频库。
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 |
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" - 按击球数排名
