tennis-training-hub/docs/verified-features.md

# Verified Features

本文档记录当前已经通过自动化验证或构建验证的项目。更新时间：2026-03-15 01:39 CST。

## 最新完整验证记录

- 通过命令：`pnpm verify`
- 验证时间：2026-03-15 01:38 - 01:39 CST
- 结果摘要：`pnpm check` 通过，`pnpm test` 通过（95/95），`pnpm test:go` 通过，`pnpm build` 通过，`pnpm test:e2e` 通过（6/6）
- 数据库状态：已执行 `set -a && source .env && set +a && pnpm exec drizzle-kit migrate`，`0007_grounded_live_ops` 已成功应用

## 生产部署联测

| 项目 | 验证方式 | 状态 |
|------|----------|------|
| `https://te.hao.work/` HTTPS 访问 | `curl -I https://te.hao.work/` | 通过 |
| `https://te.hao.work/logs` 日志页访问 | `curl -I https://te.hao.work/logs` | 通过 |
| `https://te.hao.work/vision-lab` 视觉测试页访问 | `curl -I https://te.hao.work/vision-lab` | 通过 |
| `http://te.hao.work:8302/` 4 位端口访问 | `curl -I http://te.hao.work:8302/` | 通过 |
| 站点 TLS 证书 | Let’s Encrypt ECDSA 证书已签发并由宿主机 nginx 加载 | 通过 |
| 生产登录与首次进入工作台 | Playwright 登录真实站点并跳转 `/dashboard` | 通过 |
| 新用户邀请码校验 | Playwright 验证无邀请码被拦截、正确邀请码 `CA2026` 可创建新账号 | 通过 |
| 日志页访问 | Playwright 以 `H1` 登录并访问 `/logs` | 通过 |
| 生产训练 / 实时分析 / 录制 / 视频库页面加载 | Playwright 访问 `/training`、`/live-camera`、`/recorder`、`/videos` | 通过 |
| 生产训练计划后台任务提交 | Playwright 点击训练计划生成按钮并收到后台任务反馈 | 通过 |
| 生产移动端录制焦点视图 | Playwright 移动端视口打开 `/recorder` 并验证焦点入口与操作壳层 | 通过 |
| 生产前端运行时异常检查 | Playwright `pageerror` / `console.error` 检查 | 通过 |
| 媒体健康检查 | `curl http://127.0.0.1:8081/media/health` | 通过 |
| compose 自包含服务 | `docker compose ps -a` 中 `app` / `app-worker` / `db` / `media` / `media-worker` 正常运行，`migrate` 成功退出 | 通过 |

## 构建与编译通过

| 项目 | 验证方式 | 状态 |
|------|----------|------|
| 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` | 通过 |
| live analysis 会话保存 | `pnpm test` | 通过 |
| record | `pnpm test` | 通过 |
| rating | `pnpm test` | 通过 |
| achievement | `pnpm test` | 通过 |
| admin | `pnpm test` | 通过 |
| checkin 兼容路由 | `pnpm test` | 通过 |
| badge | `pnpm test` | 通过 |
| leaderboard | `pnpm test` | 通过 |
| tutorial / reminder / notification 路由校验 | `pnpm test` | 通过 |
| task 后台任务路由 | `pnpm test` / `pnpm test:e2e` | 通过 |
| media 工具函数 | `pnpm test` | 通过 |
| 媒体服务 `/media` 路径回退 | `pnpm test` | 通过 |
| 登录 URL 回退逻辑 | `pnpm test` | 通过 |

## Go 媒体服务验证

| 功能 | 验证方式 | 状态 |
|------|----------|------|
| `/media/health` | `go test ./...` | 通过 |
| 会话状态聚合 | `go test ./...` | 通过 |
| 单片段归档回放产物生成 | `go test ./...` | 通过 |

## 浏览器 E2E 已验证主流程

| 模块 | 验证内容 | 状态 |
|------|----------|------|
| 登录 | 用户名输入、登录提交、跳转仪表盘 | 通过 |
| 仪表盘 | 认证后主标题与入口按钮渲染 | 通过 |
| 训练计划 | 训练计划页加载与生成入口可见 | 通过 |
| 视频库 | 视频卡片渲染 | 通过 |
| 实时分析 | 摄像头启动入口渲染 | 通过 |
| 实时分析打分 | 启动分析后出现实时评分结果 | 通过 |
| 在线录制 | 启动摄像头、开始录制、手动标记、结束归档 | 通过 |
| 录制焦点视图 | 移动端最大化焦点视图与主操作按钮渲染 | 通过 |
| 录制结果入库 | 归档完成后视频库可见录制结果 | 通过 |

## LLM 模块验证

| 项目 | 验证方式 | 状态 |
|------|----------|------|
| `.env` 中的 `LLM_API_URL` / `LLM_API_KEY` / `LLM_MODEL` | `pnpm test:llm` | 通过 |
| `https://one.hao.work/v1/chat/completions` 联通性 | `pnpm test:llm` 实际返回文本 | 通过 |
| 视觉模型独立配置路径 | `server/_core/llm.test.ts` + 手工 smoke 检查 | 通过 |
| 视觉标准图库入库 | MySQL 中 `vision_reference_images` 已写入 5 张 Commons 网球参考图 | 通过 |
| 视觉测试结果入库 | MySQL 中 `vision_test_runs` 已写入 3 条真实测试结果 | 通过 |
| H1 全量可见性 | `H1` 用户已提升为 `admin`，可读取全部视觉测试记录；Playwright 真实站点检查通过 | 通过 |

## 已知非阻断警告

- 测试与开发日志中会出现 `OAUTH_SERVER_URL` 未配置提示；当前 mocked auth 和本地验证链路不依赖真实 OAuth 服务，因此不会导致失败
- `pnpm build` 仍有 Vite 大 chunk 警告；当前属于性能优化待办，不影响本次产物生成
- Playwright 运行依赖 mocked media/network，不等价于真机摄像头、真实弱网和真实 WebRTC 质量验收
- 当前上游视觉网关可能忽略 `LLM_VISION_MODEL` 并回退为文本模型；服务端已实现自动降级，任务不会因此直接失败
- 2026-03-15 的真实标准图测试中，正手 / 反手 / 发球三条记录均以 `fallback` 完成，说明当前上游视觉网关仍未稳定返回结构化视觉结果
- 开发服务器启动阶段仍会打印 `OAUTH_SERVER_URL` 未配置提示；当前用户名登录、mock auth 和自动化测试不受影响

## 当前未纳入自动验证的内容

- 真实摄像头权限与真实编码质量
- 真实 WebRTC 网络连通性
- 真正的 FFmpeg 多片段重编码质量
- 真机 iOS / Android 浏览器的真实媒体兼容差异

以上内容仍建议在预发或本地联调时补充人工验证。