# 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