chore(contracts): 引入 opendance-web v0.1.0 契约只读快照

2026-09-14 20:40:15 +08:00
commit 568664a9aa
9 changed files with 1431 additions and 0 deletions
@@ -0,0 +1,28 @@
+# Gradle
+# 注意：不能用裸 "build/" —— 它会连本项目根目录下的 build/（打包与验证脚本）
+# 一起忽略掉。必须锚定到 Gradle 真正的产物目录。
+.gradle/
+/app/build/
+/app/release/
+local.properties
+
+# 签名材料：绝不入库
+keystore/
+*.jks
+*.keystore
+keystore.properties
+
+# 发布产物
+dist-release/
+*.apk
+*.aab
+
+# IDE
+.idea/
+*.iml
+.vscode/
+captures/
+
+# 系统
+.DS_Store
+Thumbs.db
@@ -0,0 +1,8 @@
+# OpenDance Studio 契约版本
+# 规则：任何字段级变更必须提升对应条目版本，并回到 opendance-web 修改后再向另两端建迁移任务。
+rest-api: 0.1.0
+websocket-keypoints: 0.1.0
+data-models: 0.1.0
+skeleton-topology: 0.1.0
+model-formats: 0.1.0
+database: 0.1.0
@@ -0,0 +1,150 @@
+# contracts/data-models.md — 数据模型契约 v0.1.0
+
+Web 服务端是唯一权威定义，本文件是另两端消费的**稳定视图**。
+字段名在 JSON 中统一 `camelCase`；数据库列名 `snake_case`（见 `database.md`）。
+
+## 1. 通用约定
+
+- 所有资源返回 `id: number`（BIGINT，超出 2^53 前不会发生）。
+- 所有时间为 ISO 8601 UTC 字符串，例：`2026-09-14T10:00:00.000Z`。
+- 列表接口统一分页响应：
+
+```json
+{ "items": [], "total": 0, "page": 1, "pageSize": 20 }
+```
+
+- 错误响应统一：
+
+```json
+{ "statusCode": 400, "message": "…", "error": "Bad Request", "details": {} }
+```
+
+- **来源（出处）五元组**是必填项，出现在 `songs` / `motions` / `models` 三处：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `sourceType` | enum | 见 1.1 |
+| `sourceName` | string | 来源名称，如「官方曲库」「作者名」 |
+| `sourceUrl` | string | 来源链接，必须为 http(s) |
+| `license` | string | 许可标识，如 `CC-BY-4.0`、`MIT`、`proprietary`、`unknown` |
+| `author` | string | 作者 / 权利人 |
+
+### 1.1 `SourceType` 枚举
+
+```
+original      原创
+licensed      已获授权
+cc            Creative Commons
+public_domain 公共领域
+user_upload   用户上传（需审核）
+other         其他（须在 sourceName 说明）
+```
+
+### 1.2 `PublishStatus` 枚举
+
+```
+draft      草稿，仅管理端可见
+pending    待审核
+published  已发布，客户端可见
+rejected   已驳回
+```
+
+## 2. `Song`
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `id` | number | 读 | |
+| `title` | string | ✅ | 曲名，≤200 |
+| `artist` | string | ✅ | 演唱者，≤200 |
+| `album` | string | | 专辑，≤200 |
+| `language` | string | | `zh` / `en` / `ja` / `ko` / `instrumental` |
+| `durationMs` | number | | 时长毫秒 |
+| `bpm` | number | | 节拍 |
+| `difficulty` | number | | 1..5 |
+| `tags` | string[] | | |
+| `coverUrl` | string\|null | | 封面访问地址 |
+| `audioUrl` | string\|null | | 音频访问地址 |
+| `source*` | | ✅ | 来源五元组 |
+| `status` | `PublishStatus` | | 默认 `draft` |
+| `createdAt` / `updatedAt` | string | 读 | |
+
+## 3. `Motion`（动作数据）
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `id` | number | 读 | |
+| `songId` | number\|null | | 关联曲目 |
+| `name` | string | ✅ | 动作名称，≤200 |
+| `format` | enum | ✅ | `bvh` / `fbx` / `gltf` / `glb` / `keypoints-json` |
+| `fileUrl` | string | 读 | 原始动作文件 |
+| `fileSize` | number | 读 | 字节 |
+| `fps` | number\|null | | 原始帧率 |
+| `frameCount` | number\|null | | 原始帧数 |
+| `durationMs` | number\|null | | |
+| `keypointFormat` | string\|null | 读 | 预处理后固定为 `mediapipe33@0.1.0` |
+| `keypointUrl` | string\|null | 读 | 预处理产物（NDJSON 或 .npz 的 JSON 封装） |
+| `keypointFrames` | number\|null | 读 | 关键点帧数 |
+| `preprocessState` | enum | 读 | `none` / `running` / `done` / `failed` |
+| `preprocessError` | string\|null | 读 | |
+| `source*` | | ✅ | 来源五元组 |
+| `status` | `PublishStatus` | | |
+| `createdAt` / `updatedAt` | string | 读 | |
+
+## 4. `Model`（角色模型，VRM 优先）
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `id` | number | 读 | |
+| `name` | string | ✅ | 模型名称，≤200 |
+| `format` | enum | ✅ | `vrm` / `glb` / `gltf` / `fbx` |
+| `vrmVersion` | string\|null | 读 | `0.x` / `1.0`，非 VRM 为 null |
+| `isPrimary` | boolean | | 全局默认模型；**同一时刻全库至多一个 `true`** |
+| `fileUrl` | string | 读 | |
+| `fileSize` | number | 读 | |
+| `thumbnailUrl` | string\|null | 读 | |
+| `source*` | | ✅ | 来源五元组 |
+| `status` | `PublishStatus` | | |
+| `createdAt` / `updatedAt` | string | 读 | |
+
+### 4.1 VRM 优先规则（冻结）
+
+客户端选择默认模型的顺序：
+
+```
+1. 显式指定 modelId（曲目动作绑定）
+2. models 中 format = 'vrm' 且 status = 'published' 且 is_primary = 1
+3. models 中 format = 'vrm' 且 status = 'published'，按 id 升序取第一个
+4. models 中 status = 'published'，按 (format='vrm' DESC, id ASC) 取第一个
+5. 无可用模型 → 客户端使用内置占位模型
+```
+
+`isPrimary` 通过 `POST /api/models/:id/primary` 设置，服务端保证互斥（同一事务内先清零）。
+
+## 5. `ReviewRecord`（审核流水）
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `id` | number | |
+| `targetType` | enum | `song` / `motion` / `model` |
+| `targetId` | number | |
+| `action` | enum | `submit` / `approve` / `reject` / `withdraw` |
+| `fromStatus` / `toStatus` | `PublishStatus` | |
+| `reviewer` | string\|null | 审核人标识 |
+| `comment` | string\|null | 审核意见 |
+| `createdAt` | string | |
+
+## 6. `CatalogBundle`（客户端一次性拉取，`GET /api/catalog/export`）
+
+```json
+{
+  "contractVersion": { "rest-api": "0.1.0", "data-models": "0.1.0", "skeleton-topology": "0.1.0", "websocket-keypoints": "0.1.0" },
+  "generatedAt": "2026-09-14T10:00:00.000Z",
+  "songs": [],
+  "motions": [],
+  "models": [],
+  "defaultModelId": 3
+}
+```
+
+- 仅包含 `status = 'published'` 的记录。
+- `defaultModelId` 由 4.1 的规则解析得出，客户端无需自行实现优先级。
@@ -0,0 +1,58 @@
+# contracts/database.md — 数据库契约 v0.1.0
+
+## 环境
+
+- 类型：MySQL 兼容实例（外部提供）。**当前部署实际为 MariaDB 10.11.19**，TypeORM
+  使用 `mysql` driver（`mysql2`）连接，SQL 语法限制在 MySQL 5.7 / MariaDB 10.5+
+  共同子集内，不使用 MySQL 8 专有语法（窗口函数 CTE 递归除外）。
+- 数据库名：`dpendance`（由部署方提供，通过 `DB_NAME` 注入；文档默认值 `opendance` 可覆盖）
+- 字符集：`utf8mb4` / `utf8mb4_general_ci`（沿用现有实例默认排序规则）
+- 迁移工具：TypeORM migration，**不使用 `DB_SYNCHRONIZE`**
+
+## 连接信息（由部署方提供）
+
+host / port / user / password 一律通过环境变量注入，**不入库、不入仓**。
+
+```bash
+DB_HOST=192.168.150.10
+DB_PORT=3306
+DB_USER=dpendance
+DB_PASS=<部署方提供>
+DB_NAME=dpendance
+DB_SYNCHRONIZE=false
+DB_LOGGING=false
+```
+
+## 约定
+
+- 所有表名使用 `snake_case`，复数形式（`songs` / `motions` / `models`）
+- 主键统一为 `BIGINT AUTO_INCREMENT`，字段名 `id`
+- 时间字段统一 `DATETIME`，`created_at` / `updated_at`，`updated_at` 由应用层维护
+- 软删除统一使用 `deleted_at DATETIME NULL`（`@DeleteDateColumn`）
+- 布尔字段使用 `TINYINT(1)`
+- 来源（出处）字段为 5 元组，任何资产入库必须齐备：
+  `source_type` / `source_name` / `source_url` / `license` / `author`
+- 不使用 `DB_SYNCHRONIZE`，所有表结构变更走 migration
+- 每个 migration 必须可逆（提供 `down` 方法）
+- 迁移文件名格式：`<timestamp>-<kebab-name>.ts`
+
+## 表清单（v0.1.0）
+
+| 表 | 用途 | 任务 |
+|---|---|---|
+| `songs` | 曲目元数据 | T-WEB-003 |
+| `assets` | 上传文件元数据（去重、sha256、物理路径） | T-WEB-004 |
+| `motions` | 动作数据（BVH/FBX…）+ 来源 + 预处理产物 | T-WEB-004 / 006 |
+| `models` | 角色模型（VRM 优先）+ 来源 | T-WEB-005 |
+| `review_records` | 上传审核流水 | T-WEB-007 |
+
+## 状态机（`status` 列，v0.1.0）
+
+```
+draft ──submit──▶ pending ──approve──▶ published
+                     │
+                     └──reject──▶ rejected ──submit──▶ pending
+```
+
+- `published` 才可被 Windows 客户端 / Android App 消费
+- `/api/catalog/export` 只导出 `published` 记录
@@ -0,0 +1,83 @@
+# contracts/model-formats.md — 模型与动作格式契约 v0.1.0
+
+## 1. 角色模型（models）
+
+| 格式 | 扩展名 | 支持级别 | 说明 |
+|---|---|---|---|
+| VRM | `.vrm` | **首选（P0）** | glTF 2.0 二进制 + VRM 扩展；Windows 端 godot-vrm 直接加载 |
+| glTF Binary | `.glb` | P1 | 需含骨骼（skin）；无骨骼则仅作静态展示 |
+| glTF | `.gltf` (+ `.bin`, 贴图) | P2 | 多文件，管理端需打包为 zip 上传 |
+| FBX | `.fbx` | P2 | 需 Assimp 转换，管理端仅归档，不保证重定向质量 |
+
+**VRM 优先**的选取顺序见 `data-models.md` §4.1。
+
+VRM 版本识别：读取 GLB 的 JSON chunk，检查 `extensions.VRM`（0.x）或
+`extensions.VRMC_vrm`（1.0），写入 `models.vrm_version`。
+
+## 2. 动作数据（motions）
+
+| 格式 | 扩展名 | 预处理支持 | 说明 |
+|---|---|---|---|
+| BVH | `.bvh` | ✅ 内置纯 TS 解析器 | 文本格式，服务端直接解析 → FK → MediaPipe33 |
+| FBX | `.fbx` | ⚠️ 需 Assimp | 服务端调用 `assimp` 可执行文件导出为 BVH/glTF 后再解析；未安装则 `preprocessState=failed` |
+| glTF/GLB | `.gltf` / `.glb` | ⚠️ 需 Assimp | 同上 |
+| 关键点 JSON | `.json` | ✅ 直通校验 | 已是 `mediapipe33@0.1.0` 结构，仅做校验与归一化 |
+
+### 2.1 预处理产物（冻结）
+
+- 格式：NDJSON（`application/x-ndjson`），每行一帧，UTF-8 无 BOM
+- 一行结构：
+
+```json
+{"frame":0,"timeMs":0.0,"points":[[0.5,0.5,0.0,1.0],"…33 项"],"angles":[1.0,"…9 项"]}
+```
+
+- `points[i] = [x, y, z, confidence]`，语义与 `websocket-keypoints.md` 解码后完全一致
+- `angles` 为 `skeleton-topology.md` §5 定义的 9 个关节角余弦，顺序固定：
+  `[shoulder_L, shoulder_R, elbow_L, elbow_R, hip_L, hip_R, knee_L, knee_R, spine]`
+- 帧率：保留源帧率；`fps` 写入 `motions.fps`，缺省 30
+- 坐标系换算：所有 3D 动作数据统一转到 **Y 轴向上、右手系、骨盆为原点**，
+  再投影到 MediaPipe 归一化图像空间：
+  `x_img = 0.5 + x_world * scale`，`y_img = 0.5 - y_world * scale`，`z_img = -z_world * scale`，
+  `scale = 0.35 / max(|x|,|y|,|z|)`（按整段动作的最大范围自适应，保证不出画）
+- 缺失关节（BVH 中不存在对应骨骼）：`confidence = 0.0`，坐标沿用最近可用父节点
+
+### 2.2 BVH 关节名映射（默认表，可在 `web-server/src/preprocess/joint-map.ts` 扩展）
+
+| MediaPipe 点 | 常见 BVH 关节名（不区分大小写，按序匹配） |
+|---|---|
+| 0 nose | `Head`, `Neck1`, `Head_Nub` |
+| 11 left_shoulder | `LeftShoulder`, `LeftArm`, `LShoulder` |
+| 12 right_shoulder | `RightShoulder`, `RightArm`, `RShoulder` |
+| 13 left_elbow | `LeftForeArm`, `LeftElbow`, `LElbow` |
+| 14 right_elbow | `RightForeArm`, `RightElbow`, `RElbow` |
+| 15 left_wrist | `LeftHand`, `LeftWrist`, `LHand` |
+| 16 right_wrist | `RightHand`, `RightWrist`, `RHand` |
+| 23 left_hip | `LeftUpLeg`, `LeftHip`, `LHipJoint` |
+| 24 right_hip | `RightUpLeg`, `RightHip`, `RHipJoint` |
+| 25 left_knee | `LeftLeg`, `LeftKnee`, `LKnee` |
+| 26 right_knee | `RightLeg`, `RightKnee`, `RKnee` |
+| 27 left_ankle | `LeftFoot`, `LeftAnkle`, `LAnkle` |
+| 28 right_ankle | `RightFoot`, `RightAnkle`, `RAnkle` |
+| 31 left_foot_index | `LeftToeBase`, `LeftToe`, `LToe` |
+| 32 right_foot_index | `RightToeBase`, `RightToe`, `RToe` |
+
+未映射到的点按 `skeleton-topology.md` §5 的层级由父节点推算，
+并置 `confidence` 降低（`0.5`），表示估算而非实测。
+
+## 3. 上传限制
+
+| 项 | 值 |
+|---|---|
+| 单文件上限 | 512 MiB（`UPLOAD_MAX_BYTES` 可覆盖） |
+| 允许扩展名 | 上表全部；其他一律 422 |
+| 存储路径 | `${STORAGE_DIR}/{kind}/{yyyy}/{mm}/{sha256前2位}/{sha256}.{ext}` |
+| 去重 | 相同 sha256 复用同一 `assets` 记录，不重复落盘 |
+| 文件名 | 服务端不使用原始文件名做路径，只存 `assets.original_name` |
+
+## 4. 开源依赖与许可证（引用 `open-source-credits.md`）
+
+- `bvh`（MIT）— BVH 解析参考实现
+- `Assimp`（BSD-3-Clause）— FBX/glTF 转换，**可选外部依赖**
+- `@pixiv/three-vrm`（MIT）— 管理端 VRM 预览
+- `three`（MIT）— 管理端 3D 预览
@@ -0,0 +1,31 @@
+# contracts/open-source-credits.md — 开源声明锚点 v0.1.0
+
+三端发布产物中的 `THIRD_PARTY.md` 与各自「关于」页面必须包含下表全部条目。
+本文件是**唯一来源**，任一端新增依赖须回到 `opendance-web` 更新此表。
+
+| # | 项目 | 许可证 | 源链接 | 使用端 |
+|---|---|---|---|---|
+| 1 | MediaPipe | Apache License 2.0 | https://github.com/google-ai-edge/mediapipe | Android |
+| 2 | Three.js | MIT | https://github.com/mrdoob/three.js | Web 管理端 |
+| 3 | @pixiv/three-vrm | MIT | https://github.com/pixiv/three-vrm | Web 管理端 |
+| 4 | Assimp | BSD-3-Clause | https://github.com/assimp/assimp | Web 服务端 / Windows |
+| 5 | Godot Engine | MIT | https://github.com/godotengine/godot | Windows |
+| 6 | godot-vrm | MIT | https://github.com/V-Sekai/godot-vrm | Windows |
+| 7 | NestJS | MIT | https://github.com/nestjs/nest | Web 服务端 |
+| 8 | TypeORM | MIT | https://github.com/typeorm/typeorm | Web 服务端 |
+| 9 | OkHttp | Apache License 2.0 | https://github.com/square/okhttp | Android |
+| 10 | bvh | MIT | https://github.com/aimoonchen/bvh | Web 服务端 / Android |
+| 11 | React | MIT | https://github.com/facebook/react | Web 管理端 |
+| 12 | Vite | MIT | https://github.com/vitejs/vite | Web 管理端 |
+| 13 | CameraX | Apache License 2.0 | https://developer.android.com/jetpack/androidx/releases/camera | Android |
+| 14 | Jetpack Compose | Apache License 2.0 | https://developer.android.com/jetpack/compose | Android |
+| 15 | mysql2 | MIT | https://github.com/sidorares/node-mysql2 | Web 服务端 |
+
+> 注意：文档模板中列出的 10 项为**最低要求**；第 11–15 项为实际引入的构建期/运行时依赖，
+> 一并声明更完整。发布时必须保留各许可证副本（见 `web-server/LICENSE-THIRD-PARTY/`）。
+
+## 版权声明补充
+
+- MediaPipe: Copyright 2023 Google LLC
+- Godot Engine: Copyright Godot Engine contributors
+- 其余项目版权归各自作者所有
@@ -0,0 +1,817 @@
+openapi: 3.0.3
+info:
+  title: OpenDance Studio Web 管理服务端 API
+  version: 0.1.0
+  description: |
+    OpenDance Studio 的唯一数据源与契约权威。
+    契约版本见 contracts/VERSION。字段语义见 contracts/data-models.md。
+
+    - 所有 JSON 字段 camelCase
+    - 列表接口统一 { items, total, page, pageSize }
+    - 来源五元组（sourceType/sourceName/sourceUrl/license/author）在三类资产上均为必填
+servers:
+  - url: http://localhost:3000
+    description: 本地开发
+  - url: http://<host>:3000
+    description: Docker 部署
+
+tags:
+  - name: health
+  - name: songs
+  - name: motions
+  - name: models
+  - name: reviews
+  - name: catalog
+  - name: assets
+
+paths:
+  /health:
+    get:
+      tags: [health]
+      summary: 健康检查（含数据库连通性）
+      responses:
+        '200':
+          description: 服务与数据库均正常
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Health'
+        '503':
+          description: 数据库不可用
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Health'
+
+  /api/songs:
+    get:
+      tags: [songs]
+      summary: 曲目列表
+      parameters:
+        - $ref: '#/components/parameters/Page'
+        - $ref: '#/components/parameters/PageSize'
+        - name: q
+          in: query
+          schema: { type: string }
+          description: 按 title/artist/album 模糊匹配
+        - name: status
+          in: query
+          schema: { $ref: '#/components/schemas/PublishStatus' }
+        - name: artist
+          in: query
+          schema: { type: string }
+      responses:
+        '200':
+          description: 分页曲目
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SongPage'
+    post:
+      tags: [songs]
+      summary: 新建曲目
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SongCreate'
+      responses:
+        '201':
+          description: 已创建
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Song' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+
+  /api/songs/{id}:
+    parameters: [{ $ref: '#/components/parameters/Id' }]
+    get:
+      tags: [songs]
+      summary: 曲目详情
+      responses:
+        '200':
+          description: 曲目
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Song' }
+        '404': { $ref: '#/components/responses/NotFound' }
+    patch:
+      tags: [songs]
+      summary: 更新曲目
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/SongUpdate' }
+      responses:
+        '200':
+          description: 更新后的曲目
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Song' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '404': { $ref: '#/components/responses/NotFound' }
+    delete:
+      tags: [songs]
+      summary: 删除曲目（软删除）
+      responses:
+        '204': { description: 已删除 }
+        '404': { $ref: '#/components/responses/NotFound' }
+
+  /api/songs/{id}/audio:
+    parameters: [{ $ref: '#/components/parameters/Id' }]
+    post:
+      tags: [songs]
+      summary: 上传曲目音频
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required: [file]
+              properties:
+                file: { type: string, format: binary }
+      responses:
+        '201':
+          description: 上传后的曲目
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Song' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+
+  /api/songs/{id}/cover:
+    parameters: [{ $ref: '#/components/parameters/Id' }]
+    post:
+      tags: [songs]
+      summary: 上传曲目封面
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required: [file]
+              properties:
+                file: { type: string, format: binary }
+      responses:
+        '201':
+          description: 上传后的曲目
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Song' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+
+  /api/motions:
+    get:
+      tags: [motions]
+      summary: 动作列表
+      parameters:
+        - $ref: '#/components/parameters/Page'
+        - $ref: '#/components/parameters/PageSize'
+        - name: q
+          in: query
+          schema: { type: string }
+        - name: songId
+          in: query
+          schema: { type: integer, format: int64 }
+        - name: format
+          in: query
+          schema: { type: string, enum: [bvh, fbx, gltf, glb, keypoints-json] }
+        - name: status
+          in: query
+          schema: { $ref: '#/components/schemas/PublishStatus' }
+      responses:
+        '200':
+          description: 分页动作
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/MotionPage' }
+    post:
+      tags: [motions]
+      summary: 上传动作文件 + 来源信息
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required: [file, name, sourceType, sourceName, sourceUrl, license, author]
+              properties:
+                file: { type: string, format: binary }
+                name: { type: string }
+                songId: { type: integer, format: int64 }
+                fps: { type: number }
+                sourceType: { $ref: '#/components/schemas/SourceType' }
+                sourceName: { type: string }
+                sourceUrl: { type: string }
+                license: { type: string }
+                author: { type: string }
+                status: { $ref: '#/components/schemas/PublishStatus' }
+                autoPreprocess: { type: boolean, default: false }
+      responses:
+        '201':
+          description: 已创建
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Motion' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '422':
+          description: 文件格式不支持或无法解析
+
+  /api/motions/{id}:
+    parameters: [{ $ref: '#/components/parameters/Id' }]
+    get:
+      tags: [motions]
+      summary: 动作详情
+      responses:
+        '200':
+          description: 动作
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Motion' }
+        '404': { $ref: '#/components/responses/NotFound' }
+    patch:
+      tags: [motions]
+      summary: 更新动作元数据
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/MotionUpdate' }
+      responses:
+        '200':
+          description: 更新后的动作
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Motion' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+    delete:
+      tags: [motions]
+      summary: 删除动作（软删除）
+      responses:
+        '204': { description: 已删除 }
+
+  /api/motions/{id}/preprocess:
+    parameters: [{ $ref: '#/components/parameters/Id' }]
+    post:
+      tags: [motions]
+      summary: 触发 BVH/FBX → MediaPipe33 关键点序列预处理（同步执行）
+      description: |
+        同步执行并返回最终状态：成功时 preprocessState=done；
+        失败时返回 422，且 Motion.preprocessError 记录可读原因。
+      responses:
+        '200':
+          description: 预处理完成
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Motion' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '422':
+          description: 预处理失败，reason 见 preprocessError
+
+  /api/motions/{id}/keypoints:
+    parameters: [{ $ref: '#/components/parameters/Id' }]
+    get:
+      tags: [motions]
+      summary: 下载关键点序列（NDJSON，每行一帧）
+      responses:
+        '200':
+          description: |
+            application/x-ndjson，每行一个帧对象：
+            {"frame":0,"timeMs":0,"points":[[x,y,z,conf], …33],"angles":[9 个余弦]}
+          content:
+            application/x-ndjson:
+              schema: { type: string }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '409':
+          description: 尚未完成预处理
+
+  /api/models:
+    get:
+      tags: [models]
+      summary: 模型列表
+      parameters:
+        - $ref: '#/components/parameters/Page'
+        - $ref: '#/components/parameters/PageSize'
+        - name: q
+          in: query
+          schema: { type: string }
+        - name: format
+          in: query
+          schema: { type: string, enum: [vrm, glb, gltf, fbx] }
+        - name: status
+          in: query
+          schema: { $ref: '#/components/schemas/PublishStatus' }
+      responses:
+        '200':
+          description: 分页模型
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ModelPage' }
+    post:
+      tags: [models]
+      summary: 上传模型 + 来源信息（VRM 优先）
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required: [file, name, sourceType, sourceName, sourceUrl, license, author]
+              properties:
+                file: { type: string, format: binary }
+                name: { type: string }
+                isPrimary: { type: boolean }
+                sourceType: { $ref: '#/components/schemas/SourceType' }
+                sourceName: { type: string }
+                sourceUrl: { type: string }
+                license: { type: string }
+                author: { type: string }
+                status: { $ref: '#/components/schemas/PublishStatus' }
+      responses:
+        '201':
+          description: 已创建
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Model' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '422':
+          description: 不支持的模型格式
+
+  /api/models/{id}:
+    parameters: [{ $ref: '#/components/parameters/Id' }]
+    get:
+      tags: [models]
+      summary: 模型详情
+      responses:
+        '200':
+          description: 模型
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Model' }
+        '404': { $ref: '#/components/responses/NotFound' }
+    patch:
+      tags: [models]
+      summary: 更新模型元数据
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/ModelUpdate' }
+      responses:
+        '200':
+          description: 更新后的模型
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Model' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+    delete:
+      tags: [models]
+      summary: 删除模型（软删除）
+      responses:
+        '204': { description: 已删除 }
+
+  /api/models/{id}/primary:
+    parameters: [{ $ref: '#/components/parameters/Id' }]
+    post:
+      tags: [models]
+      summary: 设为全局默认模型（互斥，同事务清零其余）
+      responses:
+        '200':
+          description: 设置后的模型
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Model' }
+        '404': { $ref: '#/components/responses/NotFound' }
+
+  /api/reviews:
+    get:
+      tags: [reviews]
+      summary: 审核流水 / 待审列表
+      parameters:
+        - name: targetType
+          in: query
+          schema: { type: string, enum: [song, motion, model] }
+        - name: targetId
+          in: query
+          schema: { type: integer, format: int64 }
+        - name: status
+          in: query
+          schema: { $ref: '#/components/schemas/PublishStatus' }
+          description: 传入时改为返回该状态的待审资产列表（合并三类）
+        - $ref: '#/components/parameters/Page'
+        - $ref: '#/components/parameters/PageSize'
+      responses:
+        '200':
+          description: 审核流水或待审资产
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: '#/components/schemas/ReviewPage'
+                  - $ref: '#/components/schemas/PendingPage'
+
+  /api/reviews/{targetType}/{id}/submit:
+    parameters:
+      - name: targetType
+        in: path
+        required: true
+        schema: { type: string, enum: [song, motion, model] }
+      - $ref: '#/components/parameters/Id'
+    post:
+      tags: [reviews]
+      summary: 提交审核
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                reviewer: { type: string }
+                comment: { type: string }
+      responses:
+        '200': { description: 状态已流转 }
+        '409': { description: 当前状态不允许该操作 }
+
+  /api/reviews/{targetType}/{id}/approve:
+    parameters:
+      - name: targetType
+        in: path
+        required: true
+        schema: { type: string, enum: [song, motion, model] }
+      - $ref: '#/components/parameters/Id'
+    post:
+      tags: [reviews]
+      summary: 审核通过 → published
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                reviewer: { type: string }
+                comment: { type: string }
+      responses:
+        '200': { description: 状态已流转 }
+        '409': { description: 当前状态不允许该操作 }
+
+  /api/reviews/{targetType}/{id}/withdraw:
+    parameters:
+      - name: targetType
+        in: path
+        required: true
+        schema: { type: string, enum: [song, motion, model] }
+      - $ref: '#/components/parameters/Id'
+    post:
+      tags: [reviews]
+      summary: 撤回审核 → draft
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                reviewer: { type: string }
+                comment: { type: string }
+      responses:
+        '200': { description: 状态已流转 }
+        '409': { description: 当前状态不允许该操作 }
+
+  /api/reviews/{targetType}/{id}/history:
+    parameters:
+      - name: targetType
+        in: path
+        required: true
+        schema: { type: string, enum: [song, motion, model] }
+      - $ref: '#/components/parameters/Id'
+    get:
+      tags: [reviews]
+      summary: 单个资产的审核历史
+      responses:
+        '200':
+          description: 审核流水（按时间倒序）
+          content:
+            application/json:
+              schema:
+                type: array
+                items: { $ref: '#/components/schemas/ReviewRecord' }
+        '404': { $ref: '#/components/responses/NotFound' }
+
+  /api/reviews/{targetType}/{id}/reject:
+    parameters:
+      - name: targetType
+        in: path
+        required: true
+        schema: { type: string, enum: [song, motion, model] }
+      - $ref: '#/components/parameters/Id'
+    post:
+      tags: [reviews]
+      summary: 审核驳回 → rejected
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [comment]
+              properties:
+                reviewer: { type: string }
+                comment: { type: string }
+      responses:
+        '200': { description: 状态已流转 }
+        '400': { description: 驳回必须填写理由 }
+        '409': { description: 当前状态不允许该操作 }
+
+  /api/catalog/export:
+    get:
+      tags: [catalog]
+      summary: 客户端一次性拉取已发布目录
+      responses:
+        '200':
+          description: CatalogBundle
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/CatalogBundle' }
+
+  /api/catalog/version:
+    get:
+      tags: [catalog]
+      summary: 契约版本与目录指纹（客户端增量同步用）
+      responses:
+        '200':
+          description: 版本信息
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  contractVersion: { type: object, additionalProperties: { type: string } }
+                  revision: { type: string, description: 目录内容 sha256，变化即需重新拉取 }
+
+components:
+  parameters:
+    Id:
+      name: id
+      in: path
+      required: true
+      schema: { type: integer, format: int64 }
+    Page:
+      name: page
+      in: query
+      schema: { type: integer, minimum: 1, default: 1 }
+    PageSize:
+      name: pageSize
+      in: query
+      schema: { type: integer, minimum: 1, maximum: 200, default: 20 }
+
+  responses:
+    BadRequest:
+      description: 参数校验失败（含来源五元组缺失）
+      content:
+        application/json:
+          schema: { $ref: '#/components/schemas/ApiError' }
+    NotFound:
+      description: 资源不存在
+      content:
+        application/json:
+          schema: { $ref: '#/components/schemas/ApiError' }
+
+  schemas:
+    SourceType:
+      type: string
+      enum: [original, licensed, cc, public_domain, user_upload, other]
+    PublishStatus:
+      type: string
+      enum: [draft, pending, published, rejected]
+    MotionFormat:
+      type: string
+      enum: [bvh, fbx, gltf, glb, keypoints-json]
+    ModelFormat:
+      type: string
+      enum: [vrm, glb, gltf, fbx]
+
+    ApiError:
+      type: object
+      properties:
+        statusCode: { type: integer }
+        message: { oneOf: [{ type: string }, { type: array, items: { type: string } }] }
+        error: { type: string }
+
+    SourceFields:
+      type: object
+      required: [sourceType, sourceName, sourceUrl, license, author]
+      properties:
+        sourceType: { $ref: '#/components/schemas/SourceType' }
+        sourceName: { type: string, maxLength: 200 }
+        sourceUrl: { type: string, maxLength: 500, description: 必须为 http(s) URL }
+        license: { type: string, maxLength: 100 }
+        author: { type: string, maxLength: 200 }
+
+    Health:
+      type: object
+      properties:
+        status: { type: string, enum: [ok, degraded] }
+        uptimeSec: { type: number }
+        version: { type: string }
+        contractVersion: { type: object, additionalProperties: { type: string } }
+        database:
+          type: object
+          properties:
+            connected: { type: boolean }
+            server: { type: string, description: '如 MariaDB 10.11.19' }
+            database: { type: string }
+            migrationsPending: { type: integer }
+
+    Song:
+      allOf:
+        - $ref: '#/components/schemas/SourceFields'
+        - type: object
+          properties:
+            id: { type: integer, format: int64 }
+            title: { type: string }
+            artist: { type: string }
+            album: { type: string, nullable: true }
+            language: { type: string, nullable: true }
+            durationMs: { type: integer, nullable: true }
+            bpm: { type: number, nullable: true }
+            difficulty: { type: integer, nullable: true, minimum: 1, maximum: 5 }
+            tags: { type: array, items: { type: string } }
+            coverUrl: { type: string, nullable: true }
+            audioUrl: { type: string, nullable: true }
+            status: { $ref: '#/components/schemas/PublishStatus' }
+            createdAt: { type: string, format: date-time }
+            updatedAt: { type: string, format: date-time }
+
+    SongCreate:
+      allOf:
+        - $ref: '#/components/schemas/SourceFields'
+        - type: object
+          required: [title, artist]
+          properties:
+            title: { type: string, maxLength: 200 }
+            artist: { type: string, maxLength: 200 }
+            album: { type: string, maxLength: 200 }
+            language: { type: string }
+            durationMs: { type: integer }
+            bpm: { type: number }
+            difficulty: { type: integer, minimum: 1, maximum: 5 }
+            tags: { type: array, items: { type: string } }
+            status: { $ref: '#/components/schemas/PublishStatus' }
+
+    SongUpdate:
+      type: object
+      description: 所有字段可选；提供 source* 时必须五元组同时提供
+      properties:
+        title: { type: string }
+        artist: { type: string }
+        album: { type: string }
+        language: { type: string }
+        durationMs: { type: integer }
+        bpm: { type: number }
+        difficulty: { type: integer, minimum: 1, maximum: 5 }
+        tags: { type: array, items: { type: string } }
+        status: { $ref: '#/components/schemas/PublishStatus' }
+        sourceType: { $ref: '#/components/schemas/SourceType' }
+        sourceName: { type: string }
+        sourceUrl: { type: string }
+        license: { type: string }
+        author: { type: string }
+
+    SongPage:
+      type: object
+      properties:
+        items: { type: array, items: { $ref: '#/components/schemas/Song' } }
+        total: { type: integer }
+        page: { type: integer }
+        pageSize: { type: integer }
+
+    Motion:
+      allOf:
+        - $ref: '#/components/schemas/SourceFields'
+        - type: object
+          properties:
+            id: { type: integer, format: int64 }
+            songId: { type: integer, format: int64, nullable: true }
+            name: { type: string }
+            format: { $ref: '#/components/schemas/MotionFormat' }
+            fileUrl: { type: string, nullable: true }
+            fileSize: { type: integer, nullable: true }
+            fps: { type: number, nullable: true }
+            frameCount: { type: integer, nullable: true }
+            durationMs: { type: integer, nullable: true }
+            keypointFormat: { type: string, nullable: true }
+            keypointUrl: { type: string, nullable: true }
+            keypointFrames: { type: integer, nullable: true }
+            preprocessState: { type: string, enum: [none, running, done, failed] }
+            preprocessError: { type: string, nullable: true }
+            status: { $ref: '#/components/schemas/PublishStatus' }
+            createdAt: { type: string, format: date-time }
+            updatedAt: { type: string, format: date-time }
+
+    MotionUpdate:
+      type: object
+      properties:
+        name: { type: string }
+        songId: { type: integer, format: int64, nullable: true }
+        fps: { type: number }
+        status: { $ref: '#/components/schemas/PublishStatus' }
+        sourceType: { $ref: '#/components/schemas/SourceType' }
+        sourceName: { type: string }
+        sourceUrl: { type: string }
+        license: { type: string }
+        author: { type: string }
+
+    MotionPage:
+      type: object
+      properties:
+        items: { type: array, items: { $ref: '#/components/schemas/Motion' } }
+        total: { type: integer }
+        page: { type: integer }
+        pageSize: { type: integer }
+
+    Model:
+      allOf:
+        - $ref: '#/components/schemas/SourceFields'
+        - type: object
+          properties:
+            id: { type: integer, format: int64 }
+            name: { type: string }
+            format: { $ref: '#/components/schemas/ModelFormat' }
+            vrmVersion: { type: string, nullable: true }
+            isPrimary: { type: boolean }
+            fileUrl: { type: string, nullable: true }
+            fileSize: { type: integer, nullable: true }
+            thumbnailUrl: { type: string, nullable: true }
+            status: { $ref: '#/components/schemas/PublishStatus' }
+            createdAt: { type: string, format: date-time }
+            updatedAt: { type: string, format: date-time }
+
+    ModelUpdate:
+      type: object
+      properties:
+        name: { type: string }
+        status: { $ref: '#/components/schemas/PublishStatus' }
+        sourceType: { $ref: '#/components/schemas/SourceType' }
+        sourceName: { type: string }
+        sourceUrl: { type: string }
+        license: { type: string }
+        author: { type: string }
+
+    ModelPage:
+      type: object
+      properties:
+        items: { type: array, items: { $ref: '#/components/schemas/Model' } }
+        total: { type: integer }
+        page: { type: integer }
+        pageSize: { type: integer }
+
+    ReviewRecord:
+      type: object
+      properties:
+        id: { type: integer, format: int64 }
+        targetType: { type: string, enum: [song, motion, model] }
+        targetId: { type: integer, format: int64 }
+        action: { type: string, enum: [submit, approve, reject, withdraw] }
+        fromStatus: { $ref: '#/components/schemas/PublishStatus' }
+        toStatus: { $ref: '#/components/schemas/PublishStatus' }
+        reviewer: { type: string, nullable: true }
+        comment: { type: string, nullable: true }
+        createdAt: { type: string, format: date-time }
+
+    ReviewPage:
+      type: object
+      properties:
+        items: { type: array, items: { $ref: '#/components/schemas/ReviewRecord' } }
+        total: { type: integer }
+        page: { type: integer }
+        pageSize: { type: integer }
+
+    PendingPage:
+      type: object
+      properties:
+        items:
+          type: array
+          items:
+            type: object
+            properties:
+              targetType: { type: string, enum: [song, motion, model] }
+              targetId: { type: integer, format: int64 }
+              name: { type: string }
+              status: { $ref: '#/components/schemas/PublishStatus' }
+              source: { $ref: '#/components/schemas/SourceFields' }
+              updatedAt: { type: string, format: date-time }
+        total: { type: integer }
+        page: { type: integer }
+        pageSize: { type: integer }
+
+    CatalogBundle:
+      type: object
+      properties:
+        contractVersion: { type: object, additionalProperties: { type: string } }
+        generatedAt: { type: string, format: date-time }
+        songs: { type: array, items: { $ref: '#/components/schemas/Song' } }
+        motions: { type: array, items: { $ref: '#/components/schemas/Motion' } }
+        models: { type: array, items: { $ref: '#/components/schemas/Model' } }
+        defaultModelId: { type: integer, format: int64, nullable: true }
@@ -0,0 +1,125 @@
+# contracts/skeleton-topology.md — 骨骼拓扑契约 v0.1.0
+
+**唯一拓扑：MediaPipe Pose 33 点。禁止引入 SMPL 及其衍生拓扑（许可风险）。**
+
+## 1. 33 点定义与索引
+
+| idx | name | 中文 | 说明 |
+|---|---|---|---|
+| 0 | nose | 鼻 | |
+| 1 | left_eye_inner | 左眼内 | |
+| 2 | left_eye | 左眼 | |
+| 3 | left_eye_outer | 左眼外 | |
+| 4 | right_eye_inner | 右眼内 | |
+| 5 | right_eye | 右眼 | |
+| 6 | right_eye_outer | 右眼外 | |
+| 7 | left_ear | 左耳 | |
+| 8 | right_ear | 右耳 | |
+| 9 | mouth_left | 左嘴角 | |
+| 10 | mouth_right | 右嘴角 | |
+| 11 | left_shoulder | 左肩 | |
+| 12 | right_shoulder | 右肩 | |
+| 13 | left_elbow | 左肘 | |
+| 14 | right_elbow | 右肘 | |
+| 15 | left_wrist | 左腕 | |
+| 16 | right_wrist | 右腕 | |
+| 17 | left_pinky | 左小指 | |
+| 18 | right_pinky | 右小指 | |
+| 19 | left_index | 左食指 | |
+| 20 | right_index | 右食指 | |
+| 21 | left_thumb | 左拇指 | |
+| 22 | right_thumb | 右拇指 | |
+| 23 | left_hip | 左髋 | |
+| 24 | right_hip | 右髋 | |
+| 25 | left_knee | 左膝 | |
+| 26 | right_knee | 右膝 | |
+| 27 | left_ankle | 左踝 | |
+| 28 | right_ankle | 右踝 | |
+| 29 | left_heel | 左足跟 | |
+| 30 | right_heel | 右足跟 | |
+| 31 | left_foot_index | 左足尖 | |
+| 32 | right_foot_index | 右足尖 | |
+
+## 2. 虚拟关节（由 33 点派生，索引 33/34，仅用于层级与角度特征）
+
+| idx | name | 计算 |
+|---|---|---|
+| 33 | neck | `midpoint(left_shoulder(11), right_shoulder(12))` |
+| 34 | pelvis | `midpoint(left_hip(23), right_hip(24))` |
+
+## 3. 父节点表（`parent[i]`，-1 表示世界根）
+
+对称树，便于骨骼重定向与关节角计算：
+
+```
+34 pelvis             -> -1 (world root)
+33 neck               -> 34
+23 left_hip           -> 34
+24 right_hip          -> 34
+11 left_shoulder      -> 33
+12 right_shoulder     -> 33
+0  nose               -> 33
+1  left_eye_inner     -> 0
+2  left_eye           -> 0
+3  left_eye_outer     -> 0
+4  right_eye_inner    -> 0
+5  right_eye          -> 0
+6  right_eye_outer    -> 0
+7  left_ear           -> 3
+8  right_ear          -> 6
+9  mouth_left         -> 0
+10 mouth_right        -> 0
+25 left_knee          -> 23
+26 right_knee         -> 24
+27 left_ankle         -> 25
+28 right_ankle        -> 26
+29 left_heel          -> 27
+30 right_heel         -> 28
+31 left_foot_index    -> 29
+32 right_foot_index   -> 30
+13 left_elbow         -> 11
+14 right_elbow        -> 12
+15 left_wrist         -> 13
+16 right_wrist         -> 14
+17 left_pinky         -> 15
+18 right_pinky         -> 16
+19 left_index         -> 15
+20 right_index        -> 16
+21 left_thumb         -> 15
+22 right_thumb        -> 16
+```
+
+## 4. 坐标系
+
+- **归一化图像坐标**：`x, y ∈ [0, 1]`，原点左上角，`y` 向下；`x` 相对图像宽，`y` 相对图像高。
+- **深度**：`z` 与 `x` 同尺度，原点位于髋中心，**负值朝向相机**。
+- **镜像**：Android 前置摄像头默认输出镜像画面；是否镜像由帧头 `flags.bit0` 声明，
+  接收端据此决定是否翻转 `x`（`x' = 1 - x`）。
+- **置信度**：`visibility ∈ [0, 1]`，落盘/传输为 `uint8`（`round(v * 255)`）。
+  归一化比例统一使用 `32767`（见 `websocket-keypoints.md`）。
+
+## 5. 派生特征（DTW 输入，Windows 端实现，服务端预处理产物同构）
+
+服务端 T-WEB-006 预处理产出的关键点序列与 Android 端输出的帧**结构完全一致**，
+因此 Windows 端 DTW 引擎只有一条输入通路。
+
+关节角特征（弧度，余弦值便于插值）：
+
+```
+shoulder_L = angle(left_elbow,  left_shoulder,  left_hip)
+shoulder_R = angle(right_elbow, right_shoulder, right_hip)
+elbow_L    = angle(left_shoulder,  left_elbow,  left_wrist)
+elbow_R    = angle(right_shoulder, right_elbow, right_wrist)
+hip_L      = angle(left_shoulder,  left_hip,    left_knee)
+hip_R      = angle(right_shoulder, right_hip,   right_knee)
+knee_L     = angle(left_hip,   left_knee,  left_ankle)
+knee_R     = angle(right_hip,  right_knee, right_ankle)
+neck       = angle(nose, neck, pelvis)
+spine      = angle(neck, pelvis, midpoint(left_ankle, right_ankle))
+```
+
+`angle(a, b, c)` = 向量 `ba` 与 `bc` 的夹角余弦，即
+`dot(normalize(a-b), normalize(c-b))`，落在 `[-1, 1]`。
+
+**DTW 序列结构（冻结）**：每帧 = `[33 × (x, y, z), 9 个关节角余弦] = 108 维`。
+低置信度点（`visibility < 0.5`）在插值阶段由相邻帧线性补全，不参与代价计算。
@@ -0,0 +1,131 @@
+# contracts/websocket-keypoints.md — 关键点传输契约 v0.1.0
+
+Android 辅助 App（发送端）→ Windows 客户端（接收端）。
+服务端不参与实时链路，但 T-WEB-006 预处理产出的序列必须与此结构同构。
+
+## 1. 端点
+
+```
+ws://<windows-host>:8765/pose
+```
+
+- Windows 客户端监听，Android App 主动连接。
+- 子协议：`opendance.pose.v1`（`Sec-WebSocket-Protocol`）
+- 二进制帧传输关键点，文本帧传输控制消息（JSON）。
+- 默认 30 FPS；发送端允许丢帧，接收端必须按 `frame_id` 检测丢包并插值补齐。
+
+## 2. 二进制帧：239 字节（冻结）
+
+**小端序（little-endian）**。
+
+```
+偏移  长度  字段          类型      说明
+0     2     magic         u16 LE    固定 0x4F44（ASCII "OD"）
+2     1     version       u8        固定 0x01
+3     1     flags         u8        bit0 = 镜像画面(mirrored)
+                                    bit1 = 本帧含低置信度点(<0.5)
+                                    bit2 = 上半身模式(仅 0..22 有效)
+                                    bit3-7 保留，必须为 0
+4     4     frame_id      u32 LE    单调递增，从 0 开始
+8     231   keypoints     33 × 7B   见下
+--------------------------------------------------------------
+合计  239
+```
+
+### 单个关键点（7 字节，`i` 为 0..32）
+
+```
+偏移  长度  字段   类型     换算
+0    2     x      i16 LE   x_norm = x / 32767.0
+2    2     y      i16 LE   y_norm = y / 32767.0
+4    2     z      i16 LE   z_norm = z / 32767.0
+6    1     conf   u8       visibility = conf / 255.0
+```
+
+- 点索引与坐标语义见 `skeleton-topology.md`。
+- 编码：`x = clamp(round(x_norm * 32767), -32768, 32767)`，`y`、`z` 同理。
+- 低置信度点（`conf < 128`）坐标无意义，接收端必须插值，不得直接使用。
+- `i16` 为有符号数：`0x8000` 表示 `-32768`。
+
+### 参考实现（GDScript 风格伪码）
+
+```gdscript
+func decode(buf: PackedByteArray) -> Dictionary:
+    assert(buf.size() == 239)
+    var magic := buf.decode_u16(0)
+    assert(magic == 0x4F44 and buf.decode_u8(2) == 1)
+    var flags := buf.decode_u8(3)
+    var frame_id := buf.decode_u32(4)
+    var pts := []
+    for i in 33:
+        var o := 8 + i * 7
+        pts.append({
+            "x": float(buf.decode_s16(o)) / 32767.0,
+            "y": float(buf.decode_s16(o + 2)) / 32767.0,
+            "z": float(buf.decode_s16(o + 4)) / 32767.0,
+            "conf": float(buf.decode_u8(o + 6)) / 255.0,
+        })
+    return {"flags": flags, "frame_id": frame_id, "points": pts}
+```
+
+## 3. 文本控制帧（JSON，UTF-8）
+
+### 3.1 `hello` — Android → Windows，连接后立即发送
+
+```json
+{
+  "type": "hello",
+  "protocol": "opendance.pose.v1",
+  "device": "Pixel 8",
+  "appVersion": "0.1.0",
+  "cameraFacing": "front",
+  "targetFps": 30,
+  "resolution": "640x480"
+}
+```
+
+### 3.2 `welcome` — Windows → Android
+
+```json
+{ "type": "welcome", "protocol": "opendance.pose.v1", "sessionId": "uuid", "expectedFps": 30 }
+```
+
+### 3.3 `config` — Windows → Android，运行中调整
+
+```json
+{ "type": "config", "mirror": true, "targetFps": 30, "upperBodyOnly": false, "resolution": "640x480" }
+```
+
+### 3.4 `stats` — Android → Windows，每秒一次
+
+```json
+{ "type": "stats", "fps": 29.6, "dropped": 3, "latencyMs": 42, "confidenceAvg": 0.93 }
+```
+
+### 3.5 `bye` — 双向
+
+```json
+{ "type": "bye", "reason": "user_stop" }
+```
+
+## 4. JSON 调试帧（可选，仅开发期）
+
+```json
+{
+  "type": "pose",
+  "protocol": "opendance.pose.v1",
+  "frameId": 1024,
+  "timestampMs": 1730000000000,
+  "flags": { "mirrored": false, "upperBodyOnly": false },
+  "points": [[0.51, 0.22, -0.03, 0.99], "…共 33 项，顺序固定 [x, y, z, conf]"]
+}
+```
+
+生产链路必须使用二进制帧；JSON 帧仅用于联调，接收端可选择性支持。
+
+## 5. 兼容性规则
+
+- `version` 不同的大版本接收端必须拒绝并在 `bye.reason` 中说明。
+- `flags` 新增位不得改变既有位语义；旧接收端必须忽略未知位。
+- 33 点顺序一旦冻结不得插入或重排；新增点只能追加新 `version`。
+- 服务端 `motions.keypoint_format` 字段取值 `mediapipe33@0.1.0` 对应本契约。