# Tennis Training Hub - 变更日志

## 2026.03.17-live-camera-relay-buffer (2026-03-17)

### 功能更新

- `/live-camera` 的同步观看改为播放 media 服务生成的滚动缓存视频，不再轮询 `live-frame.jpg` 单帧图片，因此观看端的画面会按最近 60 秒缓存视频平滑播放
- owner 端每个 60 秒的合成录像分段现在会额外上传到 `relay` 会话，worker 会在收到新分段后自动重建最近窗口的 `preview.webm`
- `relay` 会话只保留最近 60 秒视频分段，旧分段会从会话元数据和磁盘同步清理，避免观看端继续读到旧一分钟之前的缓存
- media worker 会自动清理超过 30 分钟无活动的 relay 会话、分段目录和公开缓存文件，降低磁盘堆积风险
- viewer 页面文案、加载提示和按钮文案已同步更新为“缓存视频 / 缓存回放”语义；预览阶段跳过 mp4 转码，Chrome 直接使用 webm，降低处理时延

### 测试

- `cd media && go test ./...`
- `pnpm vitest run client/src/lib/liveCamera.test.ts`
- `pnpm exec playwright test tests/e2e/app.spec.ts --grep "live camera page exposes camera startup controls|live camera starts analysis and produces scores|live camera switches into viewer mode when another device already owns analysis|live camera recovers mojibake viewer titles before rendering|live camera no longer opens viewer peer retries when server relay is active"`
- `pnpm check`
- `pnpm build`
- 线上 smoke：部署后确认 `https://te.hao.work/` 已提供新构建而不是旧资源版本，`/live-camera` viewer 端进入“服务端缓存同步”路径，首页与资源文件返回正确 MIME

### 线上 smoke

- 部署完成后已确认 `https://te.hao.work/` 提供的是本次新构建，而不是旧资源版本
- `https://te.hao.work/live-camera` 的 viewer 端会走“服务端缓存同步”路径，不再请求旧的 `live-frame.jpg` 单帧同步
- 首页、主 JS、主 CSS 与 `pose` 模块均返回 `200` 和正确 MIME，未再出现脚本/样式被回退成 `text/html` 的问题

### 仓库版本

- `63dbfd2+relay-buffer`

## 2026.03.17-live-camera-preview-recovery (2026-03-17)

### 功能更新

- `/live-camera` 的 runtime 标题恢复逻辑新增更严格的乱码筛除与二次 UTF-8 解码兜底，`服...` 这类异常标题会优先恢复为正常中文；无法恢复时会自动回退到稳定默认标题，避免继续显示脏字符串
- 同步观看退出时会完整重置 viewer 轮询、连接标记和帧版本，不再把旧的 viewer 状态带回 owner 或空闲态，修复退出同步后仍黑屏、仍显示“等待同步画面”的问题
- 本地摄像头预览增加独立重绑流程和多次 watchdog 重试，即使浏览器首帧没有及时绑定 `srcObject` 或 `play()` 被短暂中断，也会继续自动恢复本地预览
- 视频区域是否显示画面改为按当前 runtime 角色分别判断，避免 viewer 旧连接状态误导 owner 模式，导致本地没有预览时仍错误隐藏占位提示

### 测试

- `pnpm check`
- `pnpm vitest run client/src/lib/liveCamera.test.ts`
- `pnpm exec playwright test tests/e2e/app.spec.ts --grep "live camera"`
- `pnpm build`
- 线上 smoke：`curl -I https://te.hao.work/`
- 线上 smoke：`curl -I https://te.hao.work/assets/index-BJ7rV3xe.js`
- 线上 smoke：`curl -I https://te.hao.work/assets/index-tNGuStgv.css`
- 线上 smoke：`curl -I https://te.hao.work/assets/pose-CZKsH31a.js`

### 线上 smoke

- `https://te.hao.work/` 已切换到本次新构建
- 当前公开站点前端资源 revision：`assets/index-BJ7rV3xe.js`、`assets/index-tNGuStgv.css`、`assets/pose-CZKsH31a.js`
- 已确认 `index`、`css` 与 `pose` 模块均返回 `200`，且 MIME 分别为 `application/javascript`、`text/css`、`application/javascript`，不再出现此前的模块脚本和样式被当成 `text/html` 返回的问题

### 仓库版本

- `06b9701`

## 2026.03.16-live-camera-runtime-refresh (2026-03-16)

### 功能更新

- `/live-camera` 在打开拍摄引导、启用摄像头、开始分析前，都会先向服务端强制刷新 runtime 状态，避免旧的同步观看锁残留导致本机明明已释放却仍无法启动
- 新增 runtime 标题乱码恢复逻辑，可自动把 UTF-8 被误按 Latin-1 显示的标题恢复成正常中文，避免出现 `服...` 一类异常标题
- 摄像头启动链路改为以 `getUserMedia` 成功为准；即使本地预览 `<video>` 的 `srcObject` 或 `play()` 在当前浏览器中短暂失败，也不会直接把整次启动判死
- e2e mock 的媒体流补齐为带假视频轨道的流对象，并把 viewer 回归改为校验“服务端 relay、无 viewer-signal”行为，避免继续按旧 P2P 逻辑断言

### 测试

- `pnpm exec playwright test tests/e2e/app.spec.ts --grep "live camera page exposes camera startup controls|live camera switches into viewer mode when another device already owns analysis|live camera recovers mojibake viewer titles before rendering|live camera no longer opens viewer peer retries when server relay is active"`
- `pnpm build`
- 部署后线上 smoke：登录 `H1` 后访问 `https://te.hao.work/live-camera`，确认空闲态“启动摄像头”入口可见，不再被残留 viewer 锁卡住

### 线上 smoke

- `https://te.hao.work/` 已切换到本次新构建
- 当前公开站点前端资源 revision：`assets/index-33wVjC4p.js` 与 `assets/index-tNGuStgv.css`
- 真实验证已通过：登录 `H1` 后访问 `https://te.hao.work/live-camera`，页面会正常显示“摄像头未启动 / 启动摄像头”，说明旧的 viewer 锁残留不会再把空闲设备卡在同步观看模式

### 仓库版本

- `8e9e491`

## 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个核心功能测试