# Tennis Training Hub 功能特性说明

本文档描述当前项目的核心能力、已交付功能边界和后续增强方向。它和 `docs/verified-features.md` 配套使用：

- 本文档回答“系统现在具备什么能力”
- `verified-features.md` 回答“哪些能力已经通过自动测试或构建验证”

## 核心业务能力

### 用户与训练

- 用户名登录：无需注册，输入用户名即可进入训练工作台
- 训练计划：按技能等级和训练周期生成训练计划
- 训练进度：展示训练次数、时长、评分趋势、最近分析结果
- 每日打卡与提醒：支持训练打卡、提醒、通知记录

### 视频与分析

- 视频上传分析：上传 `webm/mp4` 视频进入视频库并触发分析流程
- 实时摄像头分析：浏览器端调用 MediaPipe，进行姿势识别和反馈展示
- 视频库：集中展示录制结果、上传结果和分析摘要

### 在线录制与媒体链路

- Go 媒体服务：独立处理录制会话、分段上传、marker、归档和回放资源
- WebRTC 推流：录制时并行建立低延迟实时推流链路
- MediaRecorder 分段：浏览器本地压缩录制并每 60 秒自动分段上传
- 自动标记：客户端通过轻量运动检测创建关键片段 marker
- 手动标记：录制中支持手动插入剪辑点
- 自动重连：摄像头 track 断开时自动尝试恢复
- 归档回放：worker 合并片段并生成 WebM，FFmpeg 可用时额外生成 MP4
- 视频库登记：归档完成后自动写回现有视频库

## 前端能力

### 移动端

- 安全区适配
- 底部导航
- 44px 触控热区
- 横屏视频优先布局
- 录制页和分析页防下拉刷新干扰
- 录制时按设备场景自动调整码率和控件密度

### 桌面端

- 统一工作台导航
- 仪表盘、训练、视频、录制、分析等模块一致的布局结构
- 为后续 PC 粗剪时间线预留媒体域与文档规范

## 架构能力

- Node 应用负责业务 API、登录、训练数据与视频库元数据
- Go 服务负责媒体链路与归档
- `Docker Compose + 宿主机 nginx` 作为标准单机部署方式
- 统一的本地验证命令：
  - `pnpm check`
  - `pnpm test`
  - `pnpm test:go`
  - `pnpm build`
  - `pnpm test:e2e`
  - `pnpm verify`

## 已知边界

- 浏览器录制兼容目标以 Chrome 为主
- 当前 WebRTC 重点是浏览器到服务端的实时上行，不是多观众直播分发
- 当前 PC 剪辑仍处于基础媒体域准备阶段，未交付完整多轨编辑器
- 当前存储策略为本地卷优先，未接入对象存储归档

## 后续增强方向

- PC 时间线粗剪与 clip plan 持久化
- 更细粒度的设备能力自适应
- 更强的媒体回放和片段导出能力
- 更深入的前端域拆分和懒加载优化