Checkpoint: v4.0 media service, compose deploy, and verified docs

docs/FEATURES.md

@@ -1,94 +1,76 @@
-# Tennis Training Hub - 功能列表清单与开发记录
+# Tennis Training Hub 功能特性说明
 
-## 功能完成状态
+本文档描述当前项目的核心能力、已交付功能边界和后续增强方向。它和 `docs/verified-features.md` 配套使用：
 
-### 核心功能
+- 本文档回答“系统现在具备什么能力”
+- `verified-features.md` 回答“哪些能力已经通过自动测试或构建验证”
 
-| 编号 | 功能 | 状态 | 版本 | 说明 |
-|------|------|------|------|------|
-| F-001 | 用户名简单登录 | 已完成 | v1.0 | 输入用户名即可登录，自动创建账户 |
-| F-002 | 训练计划AI生成 | 已完成 | v1.0 | 支持初/中/高级，1-30天计划 |
-| F-003 | 视频上传功能 | 已完成 | v1.0 | 支持webm/mp4格式，S3存储 |
-| F-004 | MediaPipe姿势识别 | 已完成 | v1.0 | 浏览器端实时分析33个关键点 |
-| F-005 | 姿势矫正建议 | 已完成 | v1.0 | AI根据分析数据生成矫正方案 |
-| F-006 | 训练计划自动调整 | 已完成 | v1.0 | 基于分析结果智能调整计划 |
-| F-007 | 训练进度追踪 | 已完成 | v1.0 | 可视化图表展示训练历史 |
-| F-008 | 视频库管理 | 已完成 | v1.0 | 视频列表、详情、分析状态 |
+## 核心业务能力
 
-### 参考tennis_analysis增强功能
+### 用户与训练
 
-| 编号 | 功能 | 状态 | 版本 | 说明 |
-|------|------|------|------|------|
-| F-009 | 击球次数统计 | 已完成 | v1.0 | 基于手腕关键点位移检测 |
-| F-010 | 挥拍速度估算 | 已完成 | v1.0 | 手臂关键点帧间位移计算 |
-| F-011 | 运动轨迹可视化 | 已完成 | v1.0 | 身体中心点移动轨迹绘制 |
-| F-012 | 迷你球场叠加 | 已完成 | v1.0 | 视频分析界面球场示意图 |
-| F-013 | 球员统计面板 | 已完成 | v1.0 | Dashboard综合数据展示 |
-| F-014 | 帧级别关键时刻标注 | 已完成 | v1.0 | 自动标记击球、准备等关键帧 |
+- 用户名登录：无需注册，输入用户名即可进入训练工作台
+- AI 训练计划：按技能等级和训练周期生成个性化训练计划
+- 训练进度：展示训练次数、时长、评分趋势、最近分析结果
+- 每日打卡与提醒：支持训练打卡、提醒、通知记录
 
-### NTRP评分系统
+### 视频与分析
 
-| 编号 | 功能 | 状态 | 版本 | 说明 |
-|------|------|------|------|------|
-| F-015 | NTRP自动评分 | 已完成 | v1.0 | 1.0-5.0评分，五维度加权 |
-| F-016 | 历史评分自动更新 | 已完成 | v1.0 | 每次分析后自动重新计算 |
-| F-017 | 多维度评分展示 | 已完成 | v1.0 | 雷达图展示五维度得分 |
-| F-018 | 评分趋势图表 | 已完成 | v1.0 | 折线图展示评分变化趋势 |
+- 视频上传分析：上传 `webm/mp4` 视频进入视频库并触发分析流程
+- 实时摄像头分析：浏览器端调用 MediaPipe，进行姿势识别和反馈展示
+- 视频库：集中展示录制结果、上传结果和分析摘要
 
-### v2.0 新增功能
+### 在线录制与媒体链路
 
-| 编号 | 功能 | 状态 | 版本 | 说明 |
-|------|------|------|------|------|
-| F-019 | 社区排行榜 - NTRP排名 | 已完成 | v2.0 | 按评分排序的用户排名 |
-| F-020 | 社区排行榜 - 训练时长排名 | 已完成 | v2.0 | 按训练分钟排序 |
-| F-021 | 社区排行榜 - 训练次数排名 | 已完成 | v2.0 | 按训练次数排序 |
-| F-022 | 社区排行榜 - 击球数排名 | 已完成 | v2.0 | 按总击球数排序 |
-| F-023 | 每日打卡系统 | 已完成 | v2.0 | 日历视图、连续天数追踪 |
-| F-024 | 成就徽章系统 | 已完成 | v2.0 | 24种徽章，6个类别 |
-| F-025 | 实时摄像头分析 | 已完成 | v2.0 | 手机/电脑摄像头实时捕捉 |
-| F-026 | 摄像头位置确认提示 | 已完成 | v2.0 | 引导用户调整摄像头位置 |
-| F-027 | 在线录制 | 已完成 | v2.0 | 稳定压缩流录制 |
-| F-028 | 断线自动重连 | 已完成 | v2.0 | 摄像头断开自动恢复 |
-| F-029 | 自动剪辑 | 已完成 | v2.0 | 基于运动检测标记关键片段 |
-| F-030 | 移动端全面适配 | 已完成 | v2.0 | 响应式设计、安全区域、触摸优化 |
-| F-031 | 手机摄像头优化 | 已完成 | v2.0 | 前后摄像头切换、自适应分辨率 |
+- Go 媒体服务：独立处理录制会话、分段上传、marker、归档和回放资源
+- WebRTC 推流：录制时并行建立低延迟实时推流链路
+- MediaRecorder 分段：浏览器本地压缩录制并每 60 秒自动分段上传
+- 自动标记：客户端通过轻量运动检测创建关键片段 marker
+- 手动标记：录制中支持手动插入剪辑点
+- 自动重连：摄像头 track 断开时自动尝试恢复
+- 归档回放：worker 合并片段并生成 WebM，FFmpeg 可用时额外生成 MP4
+- 视频库登记：归档完成后自动写回现有视频库
 
-### v3.0 新增功能
+## 前端体验能力
 
-| 编号 | 功能 | 状态 | 版本 | 说明 |
-|------|------|------|------|------|
-| F-032 | 训练视频教程库 | 已完成 | v3.0 | 分类浏览、要点说明、常见错误、学习进度 |
-| F-033 | 教程自评系统 | 已完成 | v3.0 | 星级自评、学习笔记、已学标记 |
-| F-034 | 训练提醒通知 | 已完成 | v3.0 | 多类型提醒、自定义时间和重复日期 |
-| F-035 | 浏览器通知推送 | 已完成 | v3.0 | Notification API集成、权限管理 |
-| F-036 | 通知记录管理 | 已完成 | v3.0 | 未读计数、全部已读、历史记录 |
-| F-037 | 去除冗余文字 | 已完成 | v3.0 | 简化UI文案，直接信息反馈 |
+### 移动端
 
-## 开发时间线
+- 安全区适配
+- 底部导航
+- 44px 触控热区
+- 横屏视频优先布局
+- 录制页和分析页防下拉刷新干扰
+- 录制时按设备场景自动调整码率和控件密度
 
-| 日期 | 版本 | 里程碑 |
-|------|------|--------|
-| 2026-03-14 | v1.0 | 项目初始化、数据库设计、核心功能开发 |
-| 2026-03-14 | v1.0 | 完成所有核心页面、MediaPipe集成、NTRP评分 |
-| 2026-03-14 | v2.0 | 添加排行榜、打卡、徽章、实时摄像头、在线录制 |
-| 2026-03-14 | v2.0 | 移动端适配、测试套件、文档编写 |
-| 2026-03-14 | v3.0 | 教程库、训练提醒、通知系统、文案优化 |
+### 桌面端
 
-## 测试覆盖
+- 统一工作台导航
+- 仪表盘、训练、视频、录制、分析等模块一致的布局结构
+- 为后续 PC 粗剪时间线预留媒体域与文档规范
 
-| 模块 | 测试数 | 覆盖内容 |
-|------|--------|---------|
-| auth | 5 | me查询、logout、用户名登录验证 |
-| profile | 4 | 认证检查、技能等级验证 |
-| plan | 5 | 生成验证、列表、激活计划、调整 |
-| video | 4 | 上传验证、列表、详情 |
-| analysis | 4 | 保存验证、矫正建议、列表、视频查询 |
-| record | 4 | 创建验证、完成、列表 |
-| rating | 2 | 历史、当前评分 |
-| checkin | 5 | 今日状态、打卡、历史 |
-| badge | 5 | 列表、检查、定义、数据完整性 |
-| leaderboard | 3 | 认证、排序参数、无效参数 |
-| tutorial | 4 | 列表查询、分类过滤、进度更新 |
-| reminder | 5 | 创建验证、切换、删除、认证 |
-| notification | 4 | 列表、未读计数、标记已读 |
-| **总计** | **65** | **全部通过** |
+## 架构能力
+
+- 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 持久化
+- 更细粒度的设备能力自适应
+- 更强的媒体回放和片段导出能力
+- 更深入的前端域拆分和懒加载优化