hao/tennis-training-hub
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动
文件
669497e6257e2fa5a1ef58ef6a92ef17e849ceab
tennis-training-hub/docs/API.md
cryptocommuniums-afk 20e183d2da feat: async task pipeline for media and llm workflows
2026-03-15 00:12:26 +08:00

385 行
9.2 KiB
Markdown
原始文件 Blame 文件历史

此文件含有模棱两可的 Unicode 字符
此文件含有可能会与其他字符混淆的 Unicode 字符。 如果您是想特意这样的，可以安全地忽略该警告。 使用 Escape 按钮显示他们。
# 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[] }` |
| 输出 | `{ taskId: string, task: BackgroundTask }` |
**输入验证：**
- `skillLevel`：`"beginner"` / `"intermediate"` / `"advanced"`
- `durationDays`：1-30
- `focusAreas`：可选，如 `["正手", "脚步"]`
#### `plan.list` - 获取用户所有训练计划
| 属性 | 值 |
|------|-----|
| 类型 | Query |
| 认证 | **需认证** |
| 输出 | `TrainingPlan[]` |
#### `plan.active` - 获取当前激活的训练计划
| 属性 | 值 |
|------|-----|
| 类型 | Query |
| 认证 | **需认证** |
| 输出 | `TrainingPlan | null` |
#### `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 | null` |
---
### 6. 训练记录模块 (`record`)
### 5.1 后台任务模块 (`task`)
#### `task.list` - 获取当前用户后台任务
| 属性 | 值 |
|------|-----|
| 类型 | Query |
| 认证 | **需认证** |
| 输入 | `{ limit?: number }` |
| 输出 | `BackgroundTask[]` |
#### `task.get` - 获取单个后台任务
| 属性 | 值 |
|------|-----|
| 类型 | Query |
| 认证 | **需认证** |
| 输入 | `{ taskId: string }` |
| 输出 | `BackgroundTask | null` |
#### `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 | 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"` - 按击球数排名
在新工单中引用 查看 Git Blame 复制永久链接