tennis-training-hub/docs/CHANGELOG.md

Tennis Training Hub - 变更日志

2026.03.16-live-viewer-server-relay (2026-03-16)

功能更新

• /live-camera 的同步观看改为由 media 服务中转最新合成帧图，不再依赖浏览器之间的 P2P WebRTC viewer 连接
• owner 端会把“原视频 + 骨架/关键点 + 虚拟形象”的合成画布压缩成 JPEG 并持续上传到 media 服务
• viewer 端改为自动轮询 media 服务中的最新同步帧图，因此即使浏览器之间无法直连，也能继续看到同步画面和状态
• 同步观看模式文案已调整为明确提示“通过 media 服务中转”，等待阶段会继续自动刷新，而不是停留在 P2P 连接失败状态
• media 服务新增 live-frame 上传与静态分发能力，并记录最近同步帧时间，方便后续继续扩展更高频的服务端 relay

测试

• cd media && go test ./...
• pnpm build
• playwright-skill 线上 smoke：先用 media 服务创建 relay session、上传 live-frame，并把 H1 的 live_analysis_runtime 注入为 active viewer 场景；随后访问 https://te.hao.work/live-camera，确认页面进入“同步观看模式”、同步帧来自 /media/assets/sessions/.../live-frame.jpg，且 viewer-signal 请求数为 0

线上 smoke

• https://te.hao.work/ 已切换到本次新构建
• 当前公开站点前端资源 revision：assets/index-BC-IupO8.js 与 assets/index-tNGuStgv.css
• 真实验证已通过：viewer 端进入“同步观看模式”后，画面由 media 服务静态分发的 live-frame.jpg 提供，已确认不再触发 /viewer-signal P2P 观看请求

仓库版本

• bb46d26

2026.03.16-camera-startup-fallbacks (2026-03-16)

功能更新

• 修复部分设备在 /live-camera 和 /recorder 中因默认后置镜头、分辨率或帧率约束不兼容而直接启动摄像头失败的问题
• 摄像头请求现在会自动按当前画质、去掉高约束、低分辨率、备用镜头、任意可用镜头依次降级重试
• /recorder 在麦克风不可用或麦克风权限未给出时，会自动回退到仅视频模式，不再让整次预览启动失败
• 如果实际启用的是兼容镜头或降级模式，页面会显示提示，帮助区分“自动修复成功”与“仍然无法访问摄像头”

测试

• pnpm build
• playwright-skill 线上 smoke：通过注入 getUserMedia 回归验证 /live-camera 首轮高约束失败后会自动降级到兼容摄像头模式，/recorder 在麦克风不可用时会自动回退到仅视频模式并继续启动预览

线上 smoke

• https://te.hao.work/ 已切换到本次新构建
• 当前公开站点前端资源 revision：assets/index-CRxtWK07.js 与 assets/index-tNGuStgv.css
• 真实回归已通过：模拟高约束失败时，/live-camera 会提示“当前设备已自动切换到兼容摄像头模式”并继续启动；模拟麦克风不可用时，/recorder 会提示“麦克风不可用，已切换为仅视频模式”并继续显示录制入口

仓库版本

• a211562

2026.03.16-live-analysis-viewer-full-sync (2026-03-16)

功能更新

• 同账号多端同步观看时，viewer 端现在会按持有端 runtime snapshot 完整渲染，不再混用本地默认状态
• /live-camera viewer 端新增主端同步信息卡，可看到当前会话标题、训练模式、设备端、拍摄视角、画质模式、虚拟形象状态和最近同步时间
• viewer 端现在会同步显示主端当前处于“分析中 / 保存中 / 已保存 / 保存失败”的阶段状态
• viewer 页面在同步观看模式下会自动关闭拍摄校准弹窗，避免被“启用摄像头”引导遮挡画面和状态信息

测试

• pnpm exec playwright test tests/e2e/app.spec.ts --grep "live camera switches into viewer mode|viewer stream|recorder blocks"
• pnpm build
• playwright-skill 线上 smoke：同账号 H1 双端登录后，移动端 owner 开始实时分析，桌面端 /live-camera 进入同步观看并显示主端信息、同步视频流，owner 点击结束分析后 viewer 同步进入保存阶段

线上 smoke

• https://te.hao.work/ 已切换到本次新构建
• 当前公开站点前端资源 revision：assets/index-HRdM3fxq.js 与 assets/index-tNGuStgv.css
• 真实双端验证已通过：同账号 H1 在移动端开启实时分析后，桌面端 /live-camera 会自动进入同步观看模式，显示主端设备信息、最近同步时间和远端视频流；owner 点击结束分析后，viewer 会同步进入“保存中”阶段

仓库版本

• 922a9fb

2026.03.16-live-analysis-lock-hardening (2026-03-16)

功能更新

• 修复同账号多端实时分析在旧登录态下仍可重复占用摄像头的问题；缺少 sid 的旧 token 现在会按 token 本身派生唯一会话标识
• /live-camera 的同步观看模式新增自动重试；当持有端刚启动推流、viewer 首次连接返回 viewer stream not ready 时，会继续重连，不再长时间停留在无画面状态
• /recorder 接入实时分析占用锁；其他设备正在实时分析时，本页会禁止再次启动摄像头和开始录制，并提示前往 /live-camera 查看同步画面
• 应用启动改为先监听 HTTP 端口、再后台串行执行教程图同步和标准库预热，修复新容器上线时公网长时间返回 502

测试

• curl -I https://te.hao.work/
• pnpm check
• pnpm exec vitest run server/_core/sdk.test.ts server/features.test.ts
• pnpm exec playwright test tests/e2e/app.spec.ts --grep "viewer mode|viewer stream|recorder blocks"
• playwright-skill 线上校验：登录 H1 后访问 /changelog，确认 2026.03.16-live-analysis-lock-hardening 与仓库版本 f9db6ef 已展示
• pnpm build
• Playwright 线上 smoke：H1 手机端开启实时分析后，PC 端 /live-camera 自动进入同步观看并显示同步画面，/recorder 禁止启动摄像头；结束分析后会话可正常释放

线上 smoke

• https://te.hao.work/ 已切换到本次新构建，不再返回 502
• 当前公开站点前端资源 revision：assets/index-mi8CPCFI.js 与 assets/index-Cp_VJ8sf.css
• 真实双端验证已通过：同账号 H1 手机端开始实时分析后，PC 端 /live-camera 进入同步观看模式且可拉起同步流，/recorder 页面会阻止再次占用摄像头

仓库版本

• f9db6ef

2026.03.16-live-analysis-runtime-migration (2026-03-16)

功能更新

• 修复生产环境缺失 live_analysis_runtime 表导致 /live-camera 启动实时分析时报 SQL 查询失败的问题
• 生产库已补建 live_analysis_runtime 表，并写入缺失的 0011_live_analysis_runtime 迁移记录，避免后续重复报错
• 仓库内 drizzle/meta/_journal.json 已补齐 0011_live_analysis_runtime 条目，后续 docker compose 部署可正确识别该迁移
• 实时分析 runtime 锁恢复正常后，同账号多端互斥与同步观看流程可继续工作

测试

• pnpm check
• pnpm exec vitest run server/features.test.ts
• pnpm build
• docker compose exec -T db mysql ... SHOW TABLES LIKE 'live_analysis_runtime'
• curl -I https://te.hao.work/live-camera
• Playwright smoke：登录 H1 后访问 /live-camera，analysis.runtimeGet / analysis.runtimeAcquire / analysis.runtimeRelease 全部返回 200

线上 smoke

• https://te.hao.work/ 已切换到本次新构建
• 当前公开站点前端资源 revision：assets/index-B3BN5hY-.js 与 assets/index-BL6GQzUF.css
• /live-camera 已恢复可用，线上不再出现 live_analysis_runtime 缺表导致的 SQL 查询失败

仓库版本

• 2b72ef9

2026.03.16-live-camera-multidevice-viewer (2026-03-16)

功能更新

• /live-camera 新增同账号多端 runtime 锁；一个设备开始实时分析后，其他设备不能再次启动摄像头或分析
• 其他设备会自动进入“同步观看模式”，可查看持有端同步推送的实时画面、当前动作、评分、反馈和最近动作片段
• 同步观看复用 media 服务新增的 /viewer-signal WebRTC 通道，直接订阅“原视频 + 骨架 + 关键点 + 虚拟形象”的合成画面
• runtime 心跳按 sid 维度识别持有端，兼容旧 token 缺失可选字段的情况；超过 15 秒无心跳会自动释放陈旧锁
• /live-camera 前端新增 owner / viewer 双模式切换，观看端会禁用镜头切换、重新校准、质量调整和分析启动
• e2e mock 新增 viewer 模式和 runtime 接口覆盖，保证浏览器测试可以直接验证多端互斥与同步观看

测试

• pnpm check
• pnpm exec vitest run server/features.test.ts
• go test ./...
• go build ./...
• pnpm build
• pnpm exec playwright test tests/e2e/app.spec.ts --grep "live camera"
• pnpm exec playwright test tests/e2e/app.spec.ts --grep "recorder flow archives a session and exposes it in videos"
• curl -I https://te.hao.work/live-camera

线上 smoke

• https://te.hao.work/live-camera 已切换到本次新前端构建
• 公开站点确认已经提供本次发布的最新前端资源

仓库版本

• 4e4122d

2026.03.16-live-analysis-overlay-archive (2026-03-16)

功能更新

• /live-camera 新增 10 个免费动物虚拟形象，可将主体实时替换为猩猩、猴子、狗、猪、猫、狐狸、熊猫、狮子、老虎、兔子
• /live-camera 再新增 4 个免费的全身 3D Avatar 示例，可直接覆盖人物轮廓，并提供对应的 CC0 模型源链接
• /live-camera 新增实时分析自动录像，按 60 秒自动切段归档；归档视频写入视频库并标记为“实时分析”
• 实时分析录像改为录制“视频画面 + 骨架线 + 关键点 + 虚拟形象覆盖”的合成画布，回放中可直接看到分析叠层
• 实时分析记录与视频库解耦，用户删除视频库中的“实时分析”录像后，不会删除已保存的分析数据和训练记录
• 增加形象别名输入，当前可按输入内容自动映射到内置形象
• 实时分析动作稳定器从短窗口切换为 24 帧时间窗口，降低 1-2 秒内频繁跳动作的问题
• 动作切换新增确认阶段与延迟入库逻辑，连续动作区间改为只按稳定动作聚合
• 画面内新增稳定动作、原始候选、窗口占比、切换确认状态等实时状态提示
• 实时分析会话保存新增稳定窗口、动作切换次数、原始波动率、虚拟形象状态等指标
• 动物头像素材切换为本地集成的免费 Twemoji SVG，避免外链依赖
• 新增 Open Source Avatars 的本地优化透明 WebP 全身素材，减少全身替身叠加时的页面流量和首帧加载时间

测试

• pnpm check
• pnpm test
• pnpm build
• pnpm test:e2e
• Playwright 线上 smoke：
  • https://te.hao.work/live-camera 真实登录 H1 后可完成引导、启用摄像头、开始分析、结束分析
  • https://te.hao.work/videos 可见“实时分析”录像条目
  • https://te.hao.work/changelog 已展示 2026.03.16-live-analysis-overlay-archive 条目与对应摘要
  • 最终线上资源 revision：assets/index-BWEXNszf.js 与 assets/index-BL6GQzUF.css

仓库版本

• 4fb2d09

2026.03.15-live-analysis-leave-hint (2026-03-15)

功能更新

• 实时分析进行中显示“不要关闭浏览器或切走页面”提示
• 点击“结束分析”后，保存阶段显示“请暂时停留当前页面”提示
• 保存完成后明确提示“现在可以关闭浏览器或切换到其他页面”
• 分析中和保存中增加离开页面提醒，减少误关导致的数据丢失

测试

• pnpm check
• pnpm build

仓库版本

• 5c2dcf2

2026.03.15-training-generator-collapse (2026-03-15)

功能更新

• 训练页右侧“重新生成计划”面板在桌面端默认折叠到右侧
• 点击右侧折叠栏后展开完整生成器，可调整周期并重新生成计划
• 移动端继续保持完整面板直接可见
• 未生成计划时点击“前往生成训练计划”会先自动展开，再滚动到面板位置

测试

• pnpm check
• pnpm build

仓库版本

• 1ce94f6

2026.03.15-progress-time-actions (2026-03-15)

功能更新

• 最近训练记录摘要行默认显示到秒的具体时间，统一按 Asia/Shanghai 展示
• 录制类训练记录在列表中直接显示动作数、主动作和前 3 个动作统计
• 训练记录展开态中的动作明细改为中文动作标签，便于直接阅读
• 提醒页通知时间统一切换为 Asia/Shanghai

测试

• pnpm check
• pnpm build

仓库版本

• 71caf0d

2026.03.15-session-changelog (2026-03-15)

功能更新

• 用户名登录生成独立 sid，同一账号在多个设备或浏览器上下文中登录时不再互相顶掉 session
• 新增应用内更新日志页面 /changelog，展示版本号、发布日期、仓库版本和测试记录
• 训练进度页最近训练记录支持展开，展示具体上海时间、动作数、主动作、动作明细、录制有效性和备注
• 录制页补齐动作抽样摘要、无效录制标记与 media 预归档状态的前端展示
• Dashboard、任务中心、管理台、训练页、评分页、日志页、视觉测试页、视频库等高频页面统一使用 Asia/Shanghai 时间显示

测试

• pnpm check
• pnpm test
• pnpm test:go
• pnpm build
• Playwright 线上 smoke：
  • https://te.hao.work/ 使用两个浏览器上下文分别登录 H1，两端 dashboard 均保持有效
  • 当前线上 /changelog 仍返回旧前端构建，待部署最新版本后需要复测该页面

仓库版本

• a9ea94f

v3.0.0 (2026-03-14)

新增功能

• 训练视频教程库：分类浏览（正手/反手/发球/截击/脚步/体能），含要点说明和常见错误
• 教程自评系统：星级自评、学习笔记、已学标记、学习进度追踪
• 训练提醒通知：支持训练/打卡/分析多类型提醒，自定义时间和重复日期
• 浏览器通知推送：Notification API集成，权限管理和状态提示
• 通知记录管理：未读计数、全部标记已读、历史记录浏览
• 文案调整：去除冗余描述，简化为直接信息反馈

数据库变更

• 新增 tutorial_videos 表（教程视频库）
• 新增 tutorial_progress 表（学习进度追踪）
• 新增 training_reminders 表（训练提醒设置）
• 新增 notification_log 表（通知记录）

测试

• 测试用例从47个增加到65个
• 新增教程库、提醒、通知相关测试

---

v2.0.0 (2026-03-14)

新增功能

• 社区排行榜：支持按NTRP评分、训练时长、训练次数、击球数四种维度排名
• 每日打卡系统：日历视图展示打卡记录，自动计算连续打卡天数
• 成就徽章系统：24种成就徽章，涵盖里程碑、训练、连续打卡、视频、分析、评分6个类别
• 实时摄像头分析：支持手机/电脑摄像头实时捕捉和MediaPipe姿势分析
• 摄像头位置确认提示：引导用户调整摄像头位置
• 在线录制系统：稳定压缩流录制，自适应码率1-2.5Mbps
• 断线自动重连：摄像头意外断开时自动检测并重新连接
• 自动剪辑功能：基于运动检测自动标记关键时刻
• 移动端适配：安全区域、触摸优化、横屏支持
• 手机摄像头优化：前后摄像头切换、自适应分辨率

数据库变更

• 新增 daily_checkins 表
• 新增 user_badges 表
• users 表新增 currentStreak、longestStreak、totalShots 字段

测试

• 测试用例从15个增加到47个
• 新增打卡、徽章、排行榜相关测试

文档

• 新增 README.md
• 新增API接口文档
• 新增数据库设计文档
• 新增功能列表清单
• 新增代码规范文档
• 新增变更日志

---

v1.0.0 (2026-03-14)

初始版本

• 用户名简单登录系统
• AI训练计划生成（初/中/高级）
• 视频上传功能（webm/mp4）
• MediaPipe浏览器端姿势识别
• 姿势矫正建议系统（AI生成）
• 训练计划自动调整
• NTRP自动评分系统（五维度加权）
• 训练进度追踪（可视化图表）
• 视频库管理
• 击球次数统计
• 挥拍速度估算
• 运动轨迹可视化
• 帧级别关键时刻标注
• 球员统计面板

数据库

• 初始9张表设计
• Drizzle ORM集成
• 3次数据库迁移

测试

• 15个核心功能测试