feat: async task pipeline for media and llm workflows

README.md

@@ -1,12 +1,13 @@
 # Tennis Training Hub
 
-网球训练管理与分析应用，提供训练计划、姿势分析、实时摄像头分析、在线视频录制与视频库管理。当前版本新增独立 Go 媒体服务，用于处理在线录制、分段上传、实时推流信令和归档回放。
+网球训练管理与分析应用，提供训练计划、姿势分析、实时摄像头分析、在线视频录制与视频库管理。当前版本在媒体服务之外新增数据库驱动的后台任务系统，用于承接训练计划生成、动作纠正、多模态分析和录制归档这类高延迟任务。
 
 ## Architecture
 
 - `client/`: React 19 + TypeScript + Tailwind CSS 4 + shadcn/ui
 - `server/`: Express + tRPC + Drizzle + MySQL/TiDB，负责业务 API、登录、训练数据与视频库元数据
 - `media/`: Go 媒体服务，负责录制会话、分段上传、WebRTC 信令、关键片段标记与 FFmpeg 归档
+- `server/worker.ts`: Node 后台 worker，负责执行重任务队列
 - `docker-compose.yml`: 单机部署编排
 - `deploy/nginx.te.hao.work.conf`: `te.hao.work` 的宿主机 nginx 入口配置
 
@@ -18,7 +19,27 @@
 - 浏览器端 `RTCPeerConnection` 同步建立 WebRTC 低延迟推流链路
 - 客户端运动检测自动写入关键片段 marker，也支持手动标记
 - 摄像头中断后自动重连，保留既有分段与会话
-- 服务端 worker 将分段合并归档，并产出 WebM 回放；FFmpeg 可用时额外生成 MP4
+- Go 媒体 worker 将分段合并归档，并产出 WebM 回放；FFmpeg 可用时额外生成 MP4
+- Node app worker 轮询媒体归档状态，归档完成后自动登记到视频库并向任务中心反馈结果
+
+## Background Tasks
+
+统一后台任务覆盖以下路径：
+
+- `training_plan_generate`
+- `training_plan_adjust`
+- `analysis_corrections`
+- `pose_correction_multimodal`
+- `media_finalize`
+
+前端提供全局任务中心，页面本地也会显示任务提交、执行中、完成或失败状态。训练页、分析页和录制页都可以在用户离开页面后继续完成后台任务。
+
+## Multimodal LLM
+
+- 文本类任务使用 `LLM_API_URL` / `LLM_API_KEY` / `LLM_MODEL`
+- 图片类任务可单独指定 `LLM_VISION_API_URL` / `LLM_VISION_API_KEY` / `LLM_VISION_MODEL`
+- 所有图片输入都要求可从公网访问，因此本地相对路径会通过 `APP_PUBLIC_BASE_URL` 规范化为绝对 URL
+- 若视觉模型链路不可用，系统会自动回退到结构化指标驱动的文本纠正，避免任务直接失败
 
 ## Quick Start
 
@@ -67,7 +88,7 @@ pnpm exec playwright install chromium
 单机部署推荐：
 
 1. 宿主机 nginx 处理 `80/443` 和 TLS
-2. `docker compose up -d --build` 启动 `app + media + worker + db`
+2. `docker compose up -d --build` 启动 `app + app-worker + media + media-worker + db`
 3. nginx 将 `/` 转发到宿主机 `127.0.0.1:3002 -> app:3000`，`/media/` 转发到 `127.0.0.1:8081 -> media:8081`
 4. 如需绕过 nginx 直连调试，也可通过公网 4 位端口访问主站：`http://te.hao.work:8302/`
 
@@ -100,6 +121,10 @@ pnpm exec playwright install chromium
 - `LLM_API_URL`
 - `LLM_API_KEY`
 - `LLM_MODEL`
+- `LLM_VISION_API_URL`
+- `LLM_VISION_API_KEY`
+- `LLM_VISION_MODEL`
+- `APP_PUBLIC_BASE_URL`
 - `LOCAL_STORAGE_DIR`
 - `MEDIA_SERVICE_URL`
 - `VITE_MEDIA_BASE_URL`