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

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 录制不在当前目标内