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

2026-03-14 21:45:31 +08:00
--- a/docs/FEATURES.md
+++ b/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 持久化
+- 更细粒度的设备能力自适应
+- 更强的媒体回放和片段导出能力
+- 更深入的前端域拆分和懒加载优化
--- a/docs/deploy.md
+++ b/docs/deploy.md
@@ -0,0 +1,60 @@
+# Deployment Guide
+
+## Topology
+
+- 宿主机 nginx：负责 `te.hao.work` 的 TLS、反向代理与大文件上传入口
+- `app` 容器：Node 应用，端口 `3000`
+- `media` 容器：Go 媒体服务，端口 `8081`
+- `worker` 容器：Go 媒体归档 worker，共享媒体卷
+- `media-data` 卷：录制片段、会话状态、归档成片
+
+## Required files
+
+- `.env`
+- `docker-compose.yml`
+- `deploy/nginx.te.hao.work.conf`
+
+## Startup
+
+```bash
+cp .env.example .env
+docker compose up -d --build
+```
+
+## nginx
+
+将 `deploy/nginx.te.hao.work.conf` 放到宿主机 nginx 站点目录，确认：
+
+- `ssl_certificate`
+- `ssl_certificate_key`
+- `proxy_pass http://127.0.0.1:3000` 对应前端与业务 API
+- `proxy_pass http://127.0.0.1:8081` 对应媒体服务
+
+启用后重载 nginx：
+
+```bash
+nginx -t
+systemctl reload nginx
+```
+
+## Health checks
+
+- `curl http://127.0.0.1:3000/api/trpc/auth.me`
+- `curl http://127.0.0.1:8081/media/health`
+
+## Persistent data
+
+媒体数据默认位于 Docker volume `media-data` 下，目录结构：
+
+- `sessions/<session_id>/session.json`
+- `sessions/<session_id>/segments/*.webm`
+- `public/sessions/<session_id>/recording.webm`
+- `public/sessions/<session_id>/recording.mp4`
+
+## Rollback
+
+1. 保留 `.env` 和 `media-data`
+2. 回退 Git 版本
+3. 重新执行 `docker compose up -d --build`
+
+如果只需停止录制链路，可单独关闭 `media` 与 `worker`，主站业务仍可继续运行。
--- a/docs/developer-workflow.md
+++ b/docs/developer-workflow.md
@@ -0,0 +1,73 @@
+# Developer Workflow
+
+## Working model
+
+本项目采用“阶段可停可跑”的开发方式。任何较大的改动都应满足：
+
+- 阶段结束即可本地启动
+- 阶段结束即可执行验证命令
+- 阶段结束即可提交本地 commit
+
+## Recommended loop
+
+```bash
+pnpm check
+pnpm test
+pnpm test:go
+pnpm build
+pnpm test:e2e
+```
+
+全部通过后再提交：
+
+```bash
+git status
+git add .
+git commit -m "..."
+```
+
+## Interrupt-safe development
+
+如果业务开发中被打断，恢复时按以下顺序：
+
+1. `git status` 查看当前工作树
+2. 先跑 `pnpm check`
+3. 再跑 `pnpm test`
+4. 若涉及媒体链路，再跑 `pnpm test:go`
+5. 最后跑 `pnpm test:e2e`
+
+不要在一半状态下长时间保留“能编译但主流程不可用”的改动。
+
+## Media-related changes
+
+修改录制链路时至少检查：
+
+- `client/src/lib/media.ts`
+- `client/src/pages/Recorder.tsx`
+- `media/main.go`
+- `server/routers.ts`
+- `server/_core/mediaProxy.ts`
+
+媒体改动完成后至少验证：
+
+- 会话创建
+- marker 写入
+- finalize
+- 视频库登记
+
+## Documentation discipline
+
+以下改动必须同步更新文档：
+
+- 新增脚本或验证入口
+- 新增或变更媒体 API
+- 部署拓扑变化
+- 功能能力边界变化
+- 新增自动化测试覆盖范围
+
+至少更新：
+
+- `README.md`
+- `docs/testing.md`
+- `docs/verified-features.md`
+- 相关专题文档
--- a/docs/frontend-recording.md
+++ b/docs/frontend-recording.md
@@ -0,0 +1,44 @@
+# Frontend Recording Flow
+
+## UX goals
+
+- Chrome 优先的低流量录制
+- 录制和实时推流并行
+- 断线后尽量自动恢复
+- 移动端可直接使用
+
+## Browser pipeline
+
+1. 用户启动摄像头预览
+2. 点击开始录制时创建媒体会话
+3. 复用已有预览流，避免重复申请摄像头
+4. 同一条 `MediaStream` 同时接入：
+   - `MediaRecorder`
+   - `RTCPeerConnection`
+5. 每 60 秒主动 `requestData()` 形成一个上传分段
+6. 画面抽样比较生成自动 marker
+7. 结束录制后 flush 队列并调用 finalize
+8. 轮询归档状态，完成后把结果注册进视频库
+
+## Mobile adaptation
+
+- 使用安全区样式 `env(safe-area-inset-*)`
+- 底部固定导航
+- 最小点击区域 `44px`
+- 横屏时保留尽量大的预览画面
+- 录制页容器使用 `overscroll-behavior-y: contain`，避免下拉刷新干扰
+
+## Reconnect behavior
+
+- 摄像头 track 结束时触发重连
+- 主动停止摄像头时使用 suppression 标志，避免误判为故障
+- 重连过程：
+  - 停止 recorder
+  - 保留已上传和待上传分段
+  - 重新获取摄像头
+  - 重建 WebRTC 连接
+  - 恢复 recorder
+
+## Video library sync
+
+归档完成后前端调用 `video.registerExternal`，把回放资源登记到现有视频库中，避免重写整个视频管理模块。
--- a/docs/media-architecture.md
+++ b/docs/media-architecture.md
@@ -0,0 +1,65 @@
+# Media Architecture
+
+## Responsibilities
+
+Node 应用负责：
+
+- 用户登录
+- 训练计划与分析业务
+- 视频库元数据写入
+- 开发时 `/media` 同源代理
+
+Go 媒体服务负责：
+
+- 创建录制会话
+- WebRTC 信令交换
+- 接收分段上传
+- 写入关键片段标记
+- 会话 finalize
+- 归档与回放资源生成
+
+## HTTP API
+
+- `POST /media/sessions`
+- `POST /media/sessions/{id}/signal`
+- `POST /media/sessions/{id}/segments?sequence={n}&durationMs={ms}`
+- `POST /media/sessions/{id}/markers`
+- `POST /media/sessions/{id}/finalize`
+- `GET /media/sessions/{id}`
+- `GET /media/sessions/{id}/playback`
+- `GET /media/health`
+
+## Session lifecycle
+
+- `created`: 会话已建立，等待录制
+- `recording`: 正在录制或接收分段
+- `streaming`: WebRTC 连接已建立
+- `reconnecting`: 摄像头或连接中断，客户端正在恢复
+- `finalizing`: 会话完成，等待 worker 归档
+- `archived`: 回放已生成
+- `failed`: 上传、信令或归档失败
+
+## Storage model
+
+每个会话目录包含：
+
+- `session.json`: 会话状态和 marker 元数据
+- `segments/`: 原始分段
+- `concat.txt`: FFmpeg 拼接清单
+- `public/sessions/<id>/recording.webm`
+- `public/sessions/<id>/recording.mp4`
+
+## Archive flow
+
+1. 浏览器 `finalize`
+2. 会话状态变为 `ArchiveQueued`
+3. worker 读取全部分段
+4. 优先直接 concat，失败则重新编码为 WebM
+5. 可用时生成 MP4 归档
+6. 写回 playback URL 和文件大小
+
+## Constraints
+
+- 当前为单机本地卷模型，不依赖对象存储
+- 当前 WebRTC 仅用于浏览器到服务端的实时上行，不做多观众直播分发
+- Safari 原生 MP4 录制不在当前目标内
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -0,0 +1,77 @@
+# Testing Guide
+
+## Test layers
+
+项目当前采用四层测试结构：
+
+### 1. 静态检查
+
+- `pnpm check`
+- `pnpm build`
+- `go build ./...`
+
+用于保证类型、打包和 Go 媒体服务编译可通过。
+
+### 2. 单元测试
+
+- `pnpm test`
+
+当前覆盖：
+
+- Node/tRPC 路由输入校验与权限检查
+- 媒体工具函数，例如录制时长格式化与码率选择
+
+### 3. Go 媒体服务测试
+
+- `pnpm test:go`
+
+当前覆盖：
+
+- `media/health`
+- 会话创建与状态聚合
+- 归档流程的基础回放产物生成
+
+### 4. 浏览器 E2E
+
+- `pnpm test:e2e`
+
+使用 Playwright。为保证稳定性：
+
+- 启动本地测试服务器 `pnpm dev:test`
+- 通过路由拦截模拟 tRPC 和 `/media` 接口
+- 注入假媒体设备、假 `MediaRecorder` 和假 `RTCPeerConnection`
+
+这样可以自动验证前端主流程，而不依赖数据库、真实摄像头权限和真实 WebRTC 网络环境。
+
+## Unified verification
+
+一次性执行全部自动验证：
+
+```bash
+pnpm verify
+```
+
+执行顺序：
+
+1. `pnpm check`
+2. `pnpm test`
+3. `pnpm test:go`
+4. `pnpm build`
+5. `pnpm test:e2e`
+
+## Local browser prerequisites
+
+首次运行 Playwright 前执行：
+
+```bash
+pnpm exec playwright install chromium
+```
+
+## Notes
+
+- E2E 目前验证的是“模块主流程是否正常”，不是媒体编码质量本身
+- 若需要真实录制验证，可额外用本地 Chrome 和真实摄像头做手工联调
+- 若 `pnpm test:e2e` 失败，优先检查：
+  - `PORT=3100` 是否被占用
+  - 浏览器依赖是否安装
+  - 前端路由或测试标识是否被改动
--- a/docs/verified-features.md
+++ b/docs/verified-features.md
@@ -0,0 +1,69 @@
+# Verified Features
+
+本文档记录当前已经通过自动化验证或构建验证的项目。更新时间：2026-03-14 21:44 CST。
+
+## 最新完整验证记录
+
+- 通过命令：`pnpm verify`
+- 验证时间：2026-03-14 21:44 CST
+- 结果摘要：`pnpm check` 通过，`pnpm test` 通过（69/69），`pnpm test:go` 通过，`pnpm build` 通过，`pnpm test:e2e` 通过（5/5）
+
+## 构建与编译通过
+
+| 项目 | 验证方式 | 状态 |
+|------|----------|------|
+| TypeScript 类型检查 | `pnpm check` | 通过 |
+| Node 应用生产构建 | `pnpm build` | 通过 |
+| Go 媒体服务编译 | `pnpm test:go` 中的 `go build ./...` | 通过 |
+
+## 单元与路由验证
+
+| 模块 | 验证方式 | 状态 |
+|------|----------|------|
+| auth | `pnpm test` | 通过 |
+| profile | `pnpm test` | 通过 |
+| plan | `pnpm test` | 通过 |
+| video | `pnpm test` | 通过 |
+| analysis | `pnpm test` | 通过 |
+| record | `pnpm test` | 通过 |
+| rating | `pnpm test` | 通过 |
+| checkin | `pnpm test` | 通过 |
+| badge | `pnpm test` | 通过 |
+| leaderboard | `pnpm test` | 通过 |
+| tutorial / reminder / notification 路由校验 | `pnpm test` | 通过 |
+| media 工具函数 | `pnpm test` | 通过 |
+
+## Go 媒体服务验证
+
+| 功能 | 验证方式 | 状态 |
+|------|----------|------|
+| `/media/health` | `go test ./...` | 通过 |
+| 会话状态聚合 | `go test ./...` | 通过 |
+| 单片段归档回放产物生成 | `go test ./...` | 通过 |
+
+## 浏览器 E2E 已验证主流程
+
+| 模块 | 验证内容 | 状态 |
+|------|----------|------|
+| 登录 | 用户名输入、登录提交、跳转仪表盘 | 通过 |
+| 仪表盘 | 认证后主标题与入口按钮渲染 | 通过 |
+| 训练计划 | 训练计划页加载与生成入口可见 | 通过 |
+| 视频库 | 视频卡片渲染 | 通过 |
+| 实时分析 | 摄像头启动入口渲染 | 通过 |
+| 在线录制 | 启动摄像头、开始录制、手动标记、结束归档 | 通过 |
+| 录制结果入库 | 归档完成后视频库可见录制结果 | 通过 |
+
+## 已知非阻断警告
+
+- 测试与开发日志中会出现 `OAUTH_SERVER_URL` 未配置提示；当前 mocked auth 和本地验证链路不依赖真实 OAuth 服务，因此不会导致失败
+- `pnpm build` 仍有 Vite 大 chunk 警告；当前属于性能优化待办，不影响本次产物生成
+- Playwright 运行依赖 mocked media/network，不等价于真机摄像头、真实弱网和真实 WebRTC 质量验收
+
+## 当前未纳入自动验证的内容
+
+- 真实摄像头权限与真实编码质量
+- 真实 WebRTC 网络连通性
+- 真正的 FFmpeg 多片段重编码质量
+- 真机 iOS / Android 浏览器的真实媒体兼容差异
+
+以上内容仍建议在预发或本地联调时补充人工验证。