Tennis Training Hub

网球训练管理与分析应用，提供训练计划、姿势分析、实时摄像头分析、在线视频录制与视频库管理。当前版本新增独立 Go 媒体服务，用于处理在线录制、分段上传、实时推流信令和归档回放。

Architecture

• client/: React 19 + TypeScript + Tailwind CSS 4 + shadcn/ui
• server/: Express + tRPC + Drizzle + MySQL/TiDB，负责业务 API、登录、训练数据与视频库元数据
• media/: Go 媒体服务，负责录制会话、分段上传、WebRTC 信令、关键片段标记与 FFmpeg 归档
• docker-compose.yml: 单机部署编排
• deploy/nginx.te.hao.work.conf: te.hao.work 的宿主机 nginx 入口配置

Online Recording

在线录制模块采用双链路设计：

• 浏览器端 MediaRecorder 本地压缩并每 60 秒自动分段上传
• 浏览器端 RTCPeerConnection 同步建立 WebRTC 低延迟推流链路
• 客户端运动检测自动写入关键片段 marker，也支持手动标记
• 摄像头中断后自动重连，保留既有分段与会话
• 服务端 worker 将分段合并归档，并产出 WebM 回放；FFmpeg 可用时额外生成 MP4

Quick Start

Local development

pnpm install
cp .env.example .env
pnpm dev

本地开发时：

• Node 应用默认运行在 http://localhost:3000
• 若设置 MEDIA_SERVICE_URL=http://127.0.0.1:8081，Express 会把 /media 代理到 Go 服务
• Go 媒体服务可单独启动：

cd media
go mod tidy
go run .

Checks

pnpm check
pnpm test
pnpm test:go
pnpm build
pnpm test:e2e
pnpm verify

cd media
go build ./...

首次运行浏览器测试前执行：

pnpm exec playwright install chromium

Production Deployment

单机部署推荐：

1. 宿主机 nginx 处理 80/443 和 TLS
2. docker compose up -d --build 启动 app + media + worker + db
3. nginx 将 / 转发到宿主机 127.0.0.1:3002 -> app:3000，/media/ 转发到 127.0.0.1:8081 -> media:8081

详细步骤见：

• docs/deploy.md
• docs/media-architecture.md
• docs/frontend-recording.md

Documentation Index

• docs/FEATURES.md: 当前功能特性与能力边界
• docs/testing.md: 自动测试分层与运行方式
• docs/verified-features.md: 已验证通过的项目清单
• docs/developer-workflow.md: 阶段可中断的开发与本地提交流程
• docs/deploy.md: 部署指南
• docs/media-architecture.md: 媒体服务架构
• docs/frontend-recording.md: 前端录制与移动端适配说明

Environment

关键环境变量见 .env.example，重点包括：

• DATABASE_URL
• JWT_SECRET
• MYSQL_DATABASE
• MYSQL_USER
• MYSQL_PASSWORD
• MYSQL_ROOT_PASSWORD
• LLM_API_URL
• LLM_API_KEY
• LLM_MODEL
• LOCAL_STORAGE_DIR
• MEDIA_SERVICE_URL
• VITE_MEDIA_BASE_URL

LLM 烟雾测试：

pnpm test:llm
pnpm test:llm -- "你好，做个自我介绍"

Notes

• 浏览器兼容目标以 Chrome 为主
• 录制文件优先产出 WebM，MP4 为服务端可选归档产物
• 存储策略当前为本地卷优先，适合单机 Compose 部署