tennis-training-hub/docs/FEATURES.md

Tennis Training Hub 功能特性说明

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

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

核心业务能力

用户与训练

• 用户名登录：无需注册，输入用户名即可进入训练工作台
• 新用户邀请：首次创建用户名账号需要邀请码 CA2026
• 训练计划：按技能等级和训练周期生成训练计划，改为后台异步生成
• 训练进度：展示训练次数、时长、评分趋势、最近分析结果
• 成就系统与提醒：训练日聚合、成就进度、连练统计、提醒、通知记录

视频与分析

• 视频上传分析：上传 webm/mp4 视频进入视频库并触发分析流程
• 实时摄像头分析：浏览器端调用 MediaPipe，自动识别 forehand/backhand/serve/volley/overhead/slice/lob/unknown
• 识别稳定化：最近 6 帧动作结果会做时序加权和 winner/runner-up 比较，降低动作标签抖动
• 连续动作片段：自动聚合连续同类动作区间，单段不超过 10 秒，并保存得分、置信度与反馈摘要
• 实时分析录制：分析阶段可同步保留浏览器端本地录制视频，停止分析后自动登记到系统
• 训练数据回写：实时分析与录制数据自动写入训练记录、日训练聚合、成就系统和 NTRP 评分
• 动作纠正：支持文本纠正和多模态纠正两条链路，统一通过后台任务执行
• 多模态图片输入：上传关键帧后会转换为公网可访问的绝对 URL，再提交给视觉模型
• 视觉结果规范化：即使上游模型返回的是宽松 JSON、Markdown 包裹 JSON 或缺失数组字段，服务端也会先做结构兼容与默认值补齐
• 视觉标准图库：内置网球公网参考图，可直接发起视觉识别测试并保存结果
• 历史视觉修复：vision-lab 支持对旧的 fallback/failed 视觉记录重新排队修复，admin 可批量修复历史降级记录
• 视频库：集中展示录制结果、上传结果和分析摘要
• PC 轻剪辑：视频库内可直接打开轻剪辑工作台，支持预览、设定入点/出点、建议片段和草稿导出

在线录制与媒体链路

• Go 媒体服务：独立处理录制会话、分段上传、marker、归档和回放资源
• Node app worker：统一处理训练计划、动作纠正和录制归档结果登记
• WebRTC 推流：录制时并行建立低延迟实时推流链路
• MediaRecorder 分段：浏览器本地压缩录制并每 60 秒自动分段上传
• 自动标记：客户端通过轻量运动检测创建关键片段 marker
• 手动标记：录制中支持手动插入剪辑点
• 自动重连：摄像头 track 断开时自动尝试恢复
• 归档回放：worker 合并片段并生成 WebM，FFmpeg 可用时额外生成 MP4
• 归档状态可视化：录制页在“合并分段 / 生成回放”阶段显示任务进度、已上传体积、待上传体积和片段总数
• 视频库登记：归档完成后由 app worker 自动写回现有视频库
• 上传稳定性：媒体分段上传遇到 502/503/504 会自动重试

评分、成就与管理

• 每日异步 NTRP：系统会在每日零点后自动排队全量 NTRP 刷新任务
• 用户手动刷新：普通用户可刷新自己的 NTRP；管理员可刷新任意用户或全量用户
• NTRP 快照：每次刷新都会生成可追踪的快照，保存维度评分和数据来源摘要
• 成就定义表：成就系统已独立于旧徽章表，支持大规模扩展、分层、隐藏成就与分类
• 管理系统：/admin 提供用户管理、任务列表、实时分析会话列表、应用设置和审计日志
• H1 管理能力：当 H1 被配置为 admin 后，可查看全部视觉测试数据与后台管理数据

前端能力

移动端

• 安全区适配
• 底部导航
• 44px 触控热区
• 横屏视频优先布局
• 录制页和分析页防下拉刷新干扰
• 录制时按设备场景自动调整码率和控件密度
• 实时分析页支持竖屏最大化预览，主要操作按钮放在侧边

桌面端

• 统一工作台导航
• 仪表盘、训练、视频、录制、分析等模块一致的布局结构
• 全局任务中心：桌面侧边栏和移动端头部都可查看后台任务
• Admin 视觉测试页：H1 这类 admin 用户可查看全部视觉测试数据
• 视频库内置轻剪辑工作台，可在桌面端快速完成粗剪草稿、建议片段复核和导出

架构能力

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

已知边界

• 浏览器录制兼容目标以 Chrome 为主
• 当前 WebRTC 重点是浏览器到服务端的实时上行，不是多观众直播分发
• 当前 PC 剪辑已交付轻量草稿工作台，但未交付完整多轨编辑器、批量转码和最终成片渲染
• 当前存储策略为本地卷优先，未接入对象存储归档
• 当前 .env 配置的视觉网关若忽略 LLM_VISION_MODEL，系统会回退到文本纠正；代码已支持独立视觉模型配置，但上游网关能力仍需单独确认
• 当前实时动作识别仍基于姿态启发式分类，不是专门训练的动作识别模型

后续增强方向

移动端个性化增强

• 根据网络、机型和电量状态动态切换录制档位、分段大小与上传节流策略
• 将录制焦点视图扩展为单手操作布局，支持拇指热区、自定义主按钮顺序和横竖屏独立面板
• 为不同训练项目提供场景化预设，例如发球、正手、反手、步伐训练各自保存摄像头方向、裁切比例和提示文案
• 增加弱网回传面板，向用户展示排队片段、预计上传耗时和失败重试建议

PC 轻剪与训练回放

• 在当前轻剪辑工作台基础上继续交付单轨时间线粗剪：片段拖拽、片段删除、关键帧封面和 marker 跳转
• 增加“剪辑计划”实体，允许把自动 marker、手动 marker 和 AI 建议片段一起保存
• 提供双栏回放模式：左侧原视频，右侧姿态轨迹、节奏评分和文字纠正同步滚动
• 支持从视频库直接发起导出任务，在后台生成训练集锦或问题片段合集

高性能前端重构

• 将训练、分析、录制、视频库拆分为按域加载的路由包，继续降低首屏主包体积
• 把共享媒体状态、任务状态和用户状态从页面本地逻辑收拢为稳定的数据域层
• 统一上传、任务轮询、错误提示和绝对 URL 规范化逻辑，减少当前多处重复实现
• 为重计算页面增加惰性加载、按需图表加载和更严格的移动端资源预算