187 行
6.9 KiB
Markdown
187 行
6.9 KiB
Markdown
# Tennis Training Hub - AI网球训练助手
|
||
|
||
一个基于AI的在家网球训练平台，通过MediaPipe姿势识别技术帮助用户在只有球拍的条件下进行科学训练，自动分析挥拍姿势并生成个性化训练计划。
|
||
|
||
## 功能概览
|
||
|
||
| 功能模块 | 描述 | 技术实现 |
|
||
|---------|------|---------|
|
||
| 用户名登录 | 无需注册，输入用户名即可使用 | tRPC + JWT Session |
|
||
| 训练计划生成 | 根据用户水平（初/中/高级）AI生成训练计划 | LLM结构化输出 |
|
||
| 视频上传分析 | 上传训练视频进行姿势识别 | MediaPipe Pose + S3 |
|
||
| 实时摄像头分析 | 手机/电脑摄像头实时捕捉分析 | MediaPipe实时推理 |
|
||
| 在线录制 | 稳定压缩流录制、断线重连、自动剪辑 | MediaRecorder API |
|
||
| 姿势矫正建议 | AI根据分析结果生成矫正方案 | LLM + 姿势数据 |
|
||
| NTRP自动评分 | 基于USTA标准的五维度加权评分 | 自动算法 |
|
||
| 训练计划自动调整 | 根据分析结果智能调整后续计划 | LLM + 历史数据 |
|
||
| 每日打卡 | 连续打卡追踪、训练时长记录 | 日期计算 + 数据库 |
|
||
| 成就徽章 | 24种成就徽章激励系统 | 自动检测 + 授予 |
|
||
| 社区排行榜 | NTRP评分、训练时长、击球数排名 | 数据库排序查询 |
|
||
| 训练进度追踪 | 可视化展示训练历史和改进趋势 | Recharts图表 |
|
||
| 视频库管理 | 保存管理所有训练视频及分析结果 | S3 + 数据库 |
|
||
| 移动端适配 | 全面响应式设计，手机摄像头优化 | Tailwind响应式 |
|
||
|
||
## 技术栈
|
||
|
||
**前端：**
|
||
- React 19 + TypeScript
|
||
- Tailwind CSS 4 + shadcn/ui
|
||
- MediaPipe Pose（浏览器端姿势识别）
|
||
- Recharts（数据可视化）
|
||
- Framer Motion（动画效果）
|
||
- wouter（路由）
|
||
|
||
**后端：**
|
||
- Express 4 + tRPC 11
|
||
- Drizzle ORM + MySQL/TiDB
|
||
- S3文件存储
|
||
- LLM集成（训练计划生成、姿势矫正建议）
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
tennis-training-hub/
|
||
├── client/
|
||
│ ├── src/
|
||
│ │ ├── pages/
|
||
│ │ │ ├── Home.tsx # 落地页
|
||
│ │ │ ├── Login.tsx # 用户名登录
|
||
│ │ │ ├── Dashboard.tsx # 仪表盘
|
||
│ │ │ ├── Training.tsx # 训练计划
|
||
│ │ │ ├── Analysis.tsx # 视频分析（MediaPipe）
|
||
│ │ │ ├── LiveCamera.tsx # 实时摄像头分析
|
||
│ │ │ ├── Recorder.tsx # 在线录制
|
||
│ │ │ ├── Videos.tsx # 视频库
|
||
│ │ │ ├── Progress.tsx # 训练进度
|
||
│ │ │ ├── Rating.tsx # NTRP评分详情
|
||
│ │ │ ├── Leaderboard.tsx # 社区排行榜
|
||
│ │ │ └── Checkin.tsx # 每日打卡+徽章
|
||
│ │ ├── components/
|
||
│ │ │ └── DashboardLayout.tsx # 侧边栏导航布局
|
||
│ │ ├── App.tsx # 路由配置
|
||
│ │ └── index.css # 主题样式
|
||
│ └── index.html
|
||
├── server/
|
||
│ ├── routers.ts # tRPC路由定义
|
||
│ ├── db.ts # 数据库查询助手
|
||
│ ├── storage.ts # S3存储助手
|
||
│ ├── features.test.ts # 功能测试（47个）
|
||
│ └── _core/ # 框架核心（勿修改）
|
||
├── drizzle/
|
||
│ └── schema.ts # 数据库表结构
|
||
└── shared/
|
||
└── const.ts # 共享常量
|
||
```
|
||
|
||
## 数据库设计
|
||
|
||
### 核心表
|
||
|
||
| 表名 | 用途 | 关键字段 |
|
||
|------|------|---------|
|
||
| `users` | 用户信息 | openId, name, skillLevel, ntrpRating, totalSessions, currentStreak |
|
||
| `username_accounts` | 用户名登录映射 | username, userId |
|
||
| `training_plans` | AI训练计划 | exercises(JSON), skillLevel, durationDays, version |
|
||
| `training_videos` | 训练视频 | fileKey, url, format, analysisStatus |
|
||
| `pose_analyses` | 姿势分析结果 | overallScore, shotCount, avgSwingSpeed, strokeConsistency |
|
||
| `training_records` | 训练记录 | exerciseName, durationMinutes, completed, poseScore |
|
||
| `rating_history` | NTRP评分历史 | rating, dimensionScores(JSON), analysisId |
|
||
| `daily_checkins` | 每日打卡 | checkinDate, streakCount, minutesTrained |
|
||
| `user_badges` | 成就徽章 | badgeKey, earnedAt |
|
||
|
||
## NTRP自动评分系统
|
||
|
||
评分基于USTA（美国网球协会）的NTRP标准，范围1.0-5.0，采用五维度加权计算：
|
||
|
||
| 维度 | 权重 | 说明 |
|
||
|------|------|------|
|
||
| 姿势正确性 | 30% | 基于MediaPipe关键点角度分析 |
|
||
| 击球一致性 | 25% | 多次挥拍动作的稳定性 |
|
||
| 脚步移动 | 20% | 身体重心移动和步法评估 |
|
||
| 动作流畅性 | 15% | 挥拍动作的连贯性和自然度 |
|
||
| 力量表现 | 10% | 基于挥拍速度估算 |
|
||
|
||
**评分映射规则：**
|
||
- 0-20分 → NTRP 1.0-1.5（初学者）
|
||
- 20-40分 → NTRP 1.5-2.5（初级）
|
||
- 40-60分 → NTRP 2.5-3.5（中级）
|
||
- 60-80分 → NTRP 3.5-4.5（中高级）
|
||
- 80-100分 → NTRP 4.5-5.0（高级）
|
||
|
||
评分会根据最近20次视频分析结果自动更新，近期分析权重更高。
|
||
|
||
## 成就徽章系统
|
||
|
||
共24种成就徽章，分为6个类别：
|
||
|
||
| 类别 | 徽章数 | 示例 |
|
||
|------|--------|------|
|
||
| 里程碑 | 1 | 初来乍到（首次登录） |
|
||
| 训练 | 6 | 初试身手、十次训练、百次训练、训练时长里程碑 |
|
||
| 连续打卡 | 4 | 三日坚持、一周达人、两周勇士、月度冠军 |
|
||
| 视频 | 3 | 影像记录、视频达人、视频大师 |
|
||
| 分析 | 4 | AI教练、优秀姿势、完美姿势、击球里程碑 |
|
||
| 评分 | 3 | NTRP 2.0/3.0/4.0 |
|
||
|
||
## 在线录制功能
|
||
|
||
在线录制模块提供专业级录制体验：
|
||
|
||
- **稳定压缩流**：使用MediaRecorder API，自适应码率（1-2.5Mbps），支持webm/mp4格式
|
||
- **断线自动重连**：摄像头意外断开时自动检测并重新连接，保存已录制片段
|
||
- **自动剪辑**：基于运动检测自动标记关键时刻，支持手动设置剪辑点
|
||
- **分段录制**：每60秒自动分段，防止数据丢失
|
||
- **手机摄像头优化**：支持前后摄像头切换，自适应分辨率
|
||
|
||
## 移动端适配
|
||
|
||
- 安全区域适配（iPhone X+刘海屏）
|
||
- 触摸友好的44px最小点击区域
|
||
- 横屏视频优化
|
||
- 防误触下拉刷新（录制/分析模式）
|
||
- 响应式侧边栏导航
|
||
- 移动端底部导航栏
|
||
|
||
## 测试
|
||
|
||
项目包含47个vitest测试用例，覆盖所有核心后端功能：
|
||
|
||
```bash
|
||
pnpm test
|
||
```
|
||
|
||
测试覆盖范围：
|
||
- 认证系统（登录、登出、用户名验证）
|
||
- 用户资料管理
|
||
- 训练计划生成（输入验证）
|
||
- 视频上传和管理
|
||
- 姿势分析保存和查询
|
||
- 训练记录创建和完成
|
||
- NTRP评分系统
|
||
- 每日打卡系统
|
||
- 成就徽章系统
|
||
- 社区排行榜
|
||
|
||
## 开发
|
||
|
||
```bash
|
||
# 安装依赖
|
||
pnpm install
|
||
|
||
# 启动开发服务器
|
||
pnpm dev
|
||
|
||
# 运行测试
|
||
pnpm test
|
||
|
||
# 类型检查
|
||
pnpm check
|
||
|
||
# 构建生产版本
|
||
pnpm build
|
||
```
|
||
|
||
## 许可证
|
||
|
||
MIT License
|