docs: 新增「初次部署（从零跑起来）」；去混淆字符与真实内网信息

- README.md / README.txt 新增初次部署章节：前置条件、获取代码、首次运行、配置服务端地址（API 3000 / 管理端 3001 分离）、与 Android 的 WebSocket 联通、打包导出、自检清单、常见问题 - 三库同源契约：':=' 写法修回、去掉真实 MariaDB 版本串 - 全文去除易被 Gitea 判为「模棱两可 Unicode」的字符（- - ... -> 取代 — – … § →） - 真实内网地址与库名改占位符
2026-09-15 21:33:27 +08:00
parent baec8fce97
commit 9f7b926a9a
21 changed files with 387 additions and 181 deletions
@@ -1,4 +1,4 @@
-# contracts/data-models.md — 数据模型契约 v0.4.0
+# contracts/data-models.md - 数据模型契约 v0.4.0

 Web 服务端是唯一权威定义，本文件是另两端消费的**稳定视图**。
 字段名在 JSON 中统一 `camelCase`；数据库列名 `snake_case`（见 `database.md`）。
@@ -16,13 +16,13 @@ Web 服务端是唯一权威定义，本文件是另两端消费的**稳定视
 - 错误响应统一：

 ```json
-{ "statusCode": 400, "message": "…", "error": "Bad Request", "details": {} }
+{ "statusCode": 400, "message": "...", "error": "Bad Request", "details": {} }
 ```

 - **来源（出处）五元组**是必填项，出现在 `songs` / `motions` / `models` 三处：

 | 字段 | 类型 | 说明 |
-|---|---|---|
+|--|--|--|
 | `sourceType` | enum | 见 1.1 |
 | `sourceName` | string | 来源名称，如「官方曲库」「作者名」 |
 | `sourceUrl` | string | 来源链接，必须为 http(s) |
@@ -52,7 +52,7 @@ rejected   已驳回
 ## 2. `Song`

 | 字段 | 类型 | 必填 | 说明 |
-|---|---|---|---|
+|--|--|--|--|
 | `id` | number | 读 | |
 | `title` | string | ✅ | 曲名，≤200 |
 | `artist` | string | ✅ | 演唱者，≤200 |
@@ -71,7 +71,7 @@ rejected   已驳回
 ## 3. `Motion`（动作数据）

 | 字段 | 类型 | 必填 | 说明 |
-|---|---|---|---|
+|--|--|--|--|
 | `id` | number | 读 | |
 | `songId` | number\|null | | 关联曲目 |
 | `name` | string | ✅ | 动作名称，≤200 |
@@ -82,7 +82,7 @@ rejected   已驳回
 | `frameCount` | number\|null | | 原始帧数 |
 | `durationMs` | number\|null | | |
 | `keypointFormat` | string\|null | 读 | 预处理后固定为 `mediapipe33@0.1.0` |
-| `keypointUrl` | string\|null | 读 | 预处理产物（NDJSON 或 .npz 的 JSON 封装） |
+| `keypointUrl` | string\|null | 读 | 预处理产物（NDJSON 或.npz 的 JSON 封装） |
 | `keypointFrames` | number\|null | 读 | 关键点帧数 |
 | `preprocessState` | enum | 读 | `none` / `running` / `done` / `failed` |
 | `preprocessError` | string\|null | 读 | |
@@ -93,19 +93,19 @@ rejected   已驳回
 ## 4. `Model`（角色模型，VRM 优先）

 | 字段 | 类型 | 必填 | 说明 |
-|---|---|---|---|
+|--|--|--|--|
 | `id` | number | 读 | |
 | `name` | string | ✅ | 模型名称，≤200 |
-| `format` | enum | ✅ | `glb` / `vrm`（主力）/ `gltf` / `fbx`（历史数据）。上传的 PMX/FBX 会被服务端转换成 glb 或 vrm 再入库，见 model-formats.md §1.1 |
+| `format` | enum | ✅ | `glb` / `vrm`（主力）/ `gltf` / `fbx`（历史数据）。上传的 PMX/FBX 会被服务端转换成 glb 或 vrm 再入库，见 model-formats.md 1.1 |
 | `vrmVersion` | string\|null | 读 | `0.x` / `1.0`，非 VRM 为 null |
 | `isPrimary` | boolean | | 全局默认模型；**同一时刻全库至多一个 `true`** |
 | `fileUrl` | string | 读 | |
 | `fileSize` | number | 读 | |
 | `thumbnailUrl` | string\|null | 读 | |
-| `conversionNote` | string\|null | 读 | 由压缩包转换而来时的说明（`Hatsune Miku.pmx → GLB，已内嵌 2 张贴图`）；直传模型为 null |
-| `fileSha256` | string\|null | 读 | 模型文件（转换产物）的 sha256 —— **每次转换都会变**，仅作记录 |
+| `conversionNote` | string\|null | 读 | 由压缩包转换而来时的说明（`Hatsune Miku.pmx -> GLB，已内嵌 2 张贴图`）；直传模型为 null |
+| `fileSha256` | string\|null | 读 | 模型文件（转换产物）的 sha256 -- **每次转换都会变**，仅作记录 |
 | `sourceSha256` | string\|null | 读 | 上传压缩包的 sha256（稳定）；默认模型匹配以它为准，非压缩包上传为 null |
-| `stats` | object\|null | 读 | 模型分析结果：面数 / 顶点数 / 贴图 / **骨骼树** / humanoid 覆盖 / 可驱动性，见 model-formats.md §1.1 |
+| `stats` | object\|null | 读 | 模型分析结果：面数 / 顶点数 / 贴图 / **骨骼树** / humanoid 覆盖 / 可驱动性，见 model-formats.md 1.1 |
 | `source*` | | ✅ | 来源五元组 |
 | `status` | `PublishStatus` | | |
 | `createdAt` / `updatedAt` | string | 读 | |
@@ -124,7 +124,7 @@ rejected   已驳回
 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. 无可用模型 → 客户端使用内置占位模型
+5. 无可用模型 -> 客户端使用内置占位模型
 ```

 第 0/1 步是 v0.3.0 新增：上传 MMD 模型压缩包并转换成功后，服务端会把该模型
@@ -135,7 +135,7 @@ rejected   已驳回
 ## 5. `ReviewRecord`（审核流水）

 | 字段 | 类型 | 说明 |
-|---|---|---|
+|--|--|--|
 | `id` | number | |
 | `targetType` | enum | `song` / `motion` / `model` |
 | `targetId` | number | |
@@ -1,11 +1,11 @@
-# contracts/database.md — 数据库契约 v0.1.0
+# contracts/database.md - 数据库契约 v0.1.0

 ## 环境

- 类型：MySQL 兼容实例（外部提供）。**当前部署实际为 MariaDB 10.11.19**，TypeORM
+- 类型：MySQL 兼容实例（外部提供，含 MariaDB 10.5+），TypeORM
  使用 `mysql` driver（`mysql2`）连接，SQL 语法限制在 MySQL 5.7 / MariaDB 10.5+
  共同子集内，不使用 MySQL 8 专有语法（窗口函数 CTE 递归除外）。
- 数据库名：`dpendance`（由部署方提供，通过 `DB_NAME` 注入；文档默认值 `opendance` 可覆盖）
+- 数据库名：由部署方提供，通过 `DB_NAME` 注入（本文档示例统一用 `opendance`）
 - 字符集：`utf8mb4` / `utf8mb4_general_ci`（沿用现有实例默认排序规则）
 - 迁移工具：TypeORM migration，**不使用 `DB_SYNCHRONIZE`**

@@ -14,11 +14,11 @@
 host / port / user / password 一律通过环境变量注入，**不入库、不入仓**。

 ```bash
-DB_HOST=192.168.150.10
+DB_HOST=<数据库主机>
 DB_PORT=3306
-DB_USER=dpendance
-DB_PASS=<部署方提供>
-DB_NAME=dpendance
+DB_USER=opendance_app
+DB_PASS=<数据库口令>
+DB_NAME=opendance
 DB_SYNCHRONIZE=false
 DB_LOGGING=false
 ```
@@ -39,17 +39,17 @@ DB_LOGGING=false
 ## 增量迁移（v0.2.0 / v0.3.0）

 | 迁移 | 变更 |
-|---|---|
-| `AddModelConversionFields` | `models` 增加 `source_asset_id BIGINT NULL`（上传的压缩包，用于溯源）与 `conversion_note VARCHAR(500) NULL`（转换说明，见 model-formats.md §1.1） |
+|--|--|
+| `AddModelConversionFields` | `models` 增加 `source_asset_id BIGINT NULL`（上传的压缩包，用于溯源）与 `conversion_note VARCHAR(500) NULL`（转换说明，见 model-formats.md 1.1） |
 | `AddModelStats` | `models` 增加 `stats TEXT NULL`（模型分析结果：面数、骨骼树、humanoid 覆盖、可驱动性），供审核界面展示 |

 ## 表清单（v0.1.0）

 | 表 | 用途 | 任务 |
-|---|---|---|
+|--|--|--|
 | `songs` | 曲目元数据 | T-WEB-003 |
 | `assets` | 上传文件元数据（去重、sha256、物理路径） | T-WEB-004 |
-| `motions` | 动作数据（BVH/FBX…）+ 来源 + 预处理产物 | T-WEB-004 / 006 |
+| `motions` | 动作数据（BVH/FBX...）+ 来源 + 预处理产物 | T-WEB-004 / 006 |
 | `models` | 角色模型（VRM 优先）+ 来源 + 压缩包转换溯源 | T-WEB-005 |
 | `review_records` | 上传审核流水 | T-WEB-007 |

@@ -1,15 +1,15 @@
-# contracts/model-formats.md — 模型与动作格式契约 v0.4.0
+# contracts/model-formats.md - 模型与动作格式契约 v0.4.0

 ## 1. 角色模型（models）

 **系统以 GLB / VRM 为主力格式**（两个客户端都原生加载），其余格式一律在服务端转换。

 | 格式 | 扩展名 | 支持级别 | 服务端行为 |
-|---|---|---|---|
+|--|--|--|--|
 | glTF Binary | `.glb` | **主力（P0）** | **直接导入**，不重编码 |
 | VRM | `.vrm` | **主力（P0）** | **直接导入**；= GLB + VRM 扩展（humanoid / 表情 / springBone / meta） |
-| glTF | `.gltf` (+ `.bin`, 贴图) | P1 | 直接导入（分离文件在 zip 内可用；单文件上传会缺 .bin） |
-| MMD 压缩包 | `.zip` | P1 | **自动搜索包内可用模型**：优先直接导入 `.vrm`/`.glb`/`.gltf`，否则转换 `.pmx`/`.fbx`，见 §1.1 |
+| glTF | `.gltf` (+ `.bin`, 贴图) | P1 | 直接导入（分离文件在 zip 内可用；单文件上传会缺.bin） |
+| MMD 压缩包 | `.zip` | P1 | **自动搜索包内可用模型**：优先直接导入 `.vrm`/`.glb`/`.gltf`，否则转换 `.pmx`/`.fbx`，见 1.1 |
 | MMD 模型 | `.pmx` | P2（输入） | 服务端转换（优先 GLB、其次 VRM）；单文件上传无贴图 |
 | FBX | `.fbx` | P2（输入） | 服务端转换（优先 GLB、其次 VRM） |

@@ -21,18 +21,18 @@
 #### 单文件上传

 | 输入 | 行为 |
-|---|---|
+|--|--|
 | `.glb` / `.vrm` | 直接导入；`.glb` 若含 `VRMC_vrm`/`VRM` 扩展会被识别为 VRM |
 | `.gltf` | 直接导入（外部 `.bin` / 贴图不在同一文件里，会缺资源） |
-| `.pmx` / `.fbx` | 转换：`ASSIMP_BIN` 导出 → 回读校验（见下） |
+| `.pmx` / `.fbx` | 转换：`ASSIMP_BIN` 导出 -> 回读校验（见下） |

 #### 压缩包上传（自动搜索）

 不再"只找 `.pmx`"，而是**按格式优先级自动搜索包内可用模型**：

 ```
-.vrm  →  .glb  →  .gltf        （直接导入，优先）
-.pmx  →  .fbx                  （需要转换）
+.vrm  ->.glb  ->.gltf        （直接导入，优先）
+.pmx  ->.fbx                  （需要转换）
 ```

 同一优先级内：`MODEL_CONVERT_PMX` 指定的文件名优先，其次目录最浅，最后文件最大。
@@ -41,31 +41,31 @@
 #### 转换与校验（PMX / FBX）

 | 步骤 | 规则 |
-|---|---|
-| 1. GLB 直出 | `assimp export → .glb`，成功后把 Assimp 写成外部 URI 的贴图**内嵌**进 BIN chunk |
-| 2. glTF 打包 | 上一步失败时 `assimp export → .gltf`，由 `gltf-packer.ts` 把 `.gltf` + `.bin` + 贴图自行合成 GLB |
+|--|--|
+| 1. GLB 直出 | `assimp export ->.glb`，成功后把 Assimp 写成外部 URI 的贴图**内嵌**进 BIN chunk |
+| 2. glTF 打包 | 上一步失败时 `assimp export ->.gltf`，由 `gltf-packer.ts` 把 `.gltf` + `.bin` + 贴图自行合成 GLB |
 | 3. VRM 封装 | `MODEL_CONVERT_FORMAT=vrm` 时，在 GLB 之上补 `VRMC_vrm` 扩展（humanoid 骨骼来自骨骼名映射，见 `model-inspector.ts` 的候选表，与 Godot 客户端一致）；**humanoid 不全则回退交付 GLB**，缺失骨骼写进 `conversion_note` |
 | 回读校验 | 每一步产物都要 `assimp info` 回读。Assimp 会"写出损坏文件"（实测 FBX 导出退出码 11、产物回读报 `FBX-DOM no Objects dictionary found`），只看退出码会把坏文件入库 |
-| 说明 | 每次尝试都写进 `models.conversion_note`（例如 `Hatsune Miku.pmx → GLB，已内嵌 2 张贴图`） |
-| 失败 | 包内没有可用模型、Assimp 不可用、两条路径都失败 → **HTTP 422**，不产生模型记录 |
+| 说明 | 每次尝试都写进 `models.conversion_note`（例如 `Hatsune Miku.pmx -> GLB，已内嵌 2 张贴图`） |
+| 失败 | 包内没有可用模型、Assimp 不可用、两条路径都失败 -> **HTTP 422**，不产生模型记录 |

 #### 入库后（自动）

 | 项 | 说明 |
-|---|---|
+|--|--|
 | 状态 | **一律 `pending`（待审核）**：模型必须审核通过后才可能被客户端消费，见 `database.md` 状态机 |
 | 分析 | `model-inspector.ts` 计算面数 / 顶点数 / 贴图 / **骨骼树** / humanoid 覆盖 / 可驱动性，写入 `models.stats`，供审核界面展示 |
 | 缩略图 | `model-thumbnail.ts` 纯 TS 光栅化生成 PNG，写入 `models.thumbnail_asset_id`（失败不影响入库） |
-| 默认模型 | 只在**审核通过并勾选"同时设为默认"**（或 `POST /api/models/:id/primary`）时设置，并把身份写进源码 `src/config/default-model.ts`，见 `data-models.md` §4.1 |
+| 默认模型 | 只在**审核通过并勾选"同时设为默认"**（或 `POST /api/models/:id/primary`）时设置，并把身份写进源码 `src/config/default-model.ts`，见 `data-models.md` 4.1 |

 #### 其它约定

 | 项 | 规则 |
-|---|---|
+|--|--|
 | 确定性 | **转换产物不是字节级确定的**：同一份 zip 连续转换 3 次得到 3 个不同 sha256（大小相同，BIN chunk 有十几字节浮动）。因此默认模型种子以**上传压缩包的 sha256** 为匹配键，产物 sha256 只作记录 |
 | 安全 | 解压前逐条校验路径，拒绝绝对路径与 `..`（zip-slip）；拒绝加密条目；只支持 STORE / DEFLATE |

-**VRM 优先**的选取顺序见 `data-models.md` §4.1。
+**VRM 优先**的选取顺序见 `data-models.md` 4.1。

 VRM 版本识别：读取 GLB 的 JSON chunk，检查 `extensions.VRM`（0.x）或
 `extensions.VRMC_vrm`（1.0），写入 `models.vrm_version`。
@@ -73,9 +73,9 @@ VRM 版本识别：读取 GLB 的 JSON chunk，检查 `extensions.VRM`（0.x）
 ## 2. 动作数据（motions）

 | 格式 | 扩展名 | 预处理支持 | 说明 |
-|---|---|---|---|
-| BVH | `.bvh` | ✅ 内置纯 TS 解析器 | 文本格式，服务端直接解析 → FK → MediaPipe33 |
-| VMD | `.vmd` | ✅ 内置纯 TS 解析器 | MikuMikuDance 动作数据（二进制，Shift-JIS 骨骼名 + 四元数关键帧）；服务端按标准 MMD 骨架做 FK + 腿部 IK 求解 → MediaPipe33，见 §2.3 |
+|--|--|--|--|
+| BVH | `.bvh` | ✅ 内置纯 TS 解析器 | 文本格式，服务端直接解析 -> FK -> MediaPipe33 |
+| VMD | `.vmd` | ✅ 内置纯 TS 解析器 | MikuMikuDance 动作数据（二进制，Shift-JIS 骨骼名 + 四元数关键帧）；服务端按标准 MMD 骨架做 FK + 腿部 IK 求解 -> MediaPipe33，见 2.3 |
 | FBX | `.fbx` | ⚠️ 需 Assimp | 服务端调用 `assimp` 可执行文件导出为 BVH/glTF 后再解析；未安装则 `preprocessState=failed` |
 | glTF/GLB | `.gltf` / `.glb` | ⚠️ 需 Assimp | 同上 |
 | 关键点 JSON | `.json` | ✅ 直通校验 | 已是 `mediapipe33@0.1.0` 结构，仅做校验与归一化 |
@@ -86,11 +86,11 @@ VRM 版本识别：读取 GLB 的 JSON chunk，检查 `extensions.VRM`（0.x）
 - 一行结构：

 ```json
-{"frame":0,"timeMs":0.0,"points":[[0.5,0.5,0.0,1.0],"…33 项"],"angles":[1.0,"…9 项"]}
+{"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 个关节角余弦，顺序固定：
+- `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 轴向上、右手系、骨盆为原点**，
@@ -102,7 +102,7 @@ VRM 版本识别：读取 GLB 的 JSON chunk，检查 `extensions.VRM`（0.x）
 ### 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` |
@@ -119,7 +119,7 @@ VRM 版本识别：读取 GLB 的 JSON chunk，检查 `extensions.VRM`（0.x）
 | 31 left_foot_index | `LeftToeBase`, `LeftToe`, `LToe` |
 | 32 right_foot_index | `RightToeBase`, `RightToe`, `RToe` |

-未映射到的点按 `skeleton-topology.md` §5 的层级由父节点推算，
+未映射到的点按 `skeleton-topology.md` 5 的层级由父节点推算，
 并置 `confidence` 降低（`0.5`），表示估算而非实测。

 ### 2.3 VMD（MikuMikuDance）解析约定
@@ -130,13 +130,13 @@ float32×3 位移、float32×4 旋转四元数、64 字节贝塞尔插值参数
 灯光 / 自阴影 / IK / 可见性段落。**VMD 不含骨骼长度**，只有旋转（少数骨骼带位移），
 因此服务端必须自带一套标准 MMD 骨架才能做 FK。

-处理链路：`vmd-parser.ts`（二进制 + Shift-JIS + 贝塞尔插值）→ `mmd-skeleton.ts`
-（标准骨架）→ `mmd-pose.ts`（FK + 腿部 IK）→ `retarget.ts` 的
+处理链路：`vmd-parser.ts`（二进制 + Shift-JIS + 贝塞尔插值）-> `mmd-skeleton.ts`
+（标准骨架）-> `mmd-pose.ts`（FK + 腿部 IK）-> `retarget.ts` 的
 `worldFramesToKeypointFrames()`（与 BVH 完全共用骨盆归零 / 自适应缩放 / 图像空间投影 /
 9 个关节角）。固定 **30 fps**（MMD 帧率恒定，上传时填写的 `fps` 被忽略）。

 | MediaPipe 点 | MMD 标准骨骼 | 说明 |
-|---|---|---|
+|--|--|--|
 | 0 nose | `頭` | 取头骨根部再上移，近似面部中心 |
 | 11 / 12 left/right_shoulder | `左腕` / `右腕` | 肩关节（不是 `左肩` 骨骼） |
 | 13 / 14 left/right_elbow | `左ひじ` / `右ひじ` | |
@@ -149,12 +149,12 @@ float32×3 位移、float32×4 旋转四元数、64 字节贝塞尔插值参数
 骨骼名按 `mmd-skeleton.ts` 的别名表归一（含全角 `ＩＫ` / 半角 `IK` 两种写法）；
 未纳入标准骨架的骨骼（裙摆、物理、表情等）被忽略但会计数并写入预处理日志。

-**腿部驱动判定**：`足ＩＫ` 轨道存在非零位移 → 走 IK（用两骨骼解析 IK 把踝拉到 IK
+**腿部驱动判定**：`足ＩＫ` 轨道存在非零位移 -> 走 IK（用两骨骼解析 IK 把踝拉到 IK
 目标点，膝盖朝角色正面弯，不可达时收敛为伸直）；否则走 FK（部分动作数据把腿烘焙成
 FK 旋转）。两份示例文件分别命中两种路径。

 **坐标系**：MMD 原生是左手系（正面为 -Z），本项目通路是右手系（正面为 +Z、+X 为角色
-左侧）。VMD 的四元数与位移统一做 Z 镜像（`(x,y,z,w) → (-x,-y,z,w)`、位移 z 取反）后
+左侧）。VMD 的四元数与位移统一做 Z 镜像（`(x,y,z,w) -> (-x,-y,z,w)`、位移 z 取反）后
 送入标准骨架。该选择由真实数据对照实验确定：腿部烘焙为 FK 的样本中，`zMirrored` 下
 膝盖朝前占比 94.1%，不转换时仅 5.9%（见 `test/mmd-vmd.spec.ts`）。

@@ -166,7 +166,7 @@ FK 旋转）。两份示例文件分别命中两种路径。
 ## 3. 上传限制

 | 项 | 值 |
-|---|---|
+|--|--|
 | 单文件上限 | 512 MiB（`UPLOAD_MAX_BYTES` 可覆盖） |
 | 允许扩展名 | 上表全部；其他一律 422 |
 | 存储路径 | `${STORAGE_DIR}/{kind}/{yyyy}/{mm}/{sha256前2位}/{sha256}.{ext}` |
@@ -175,7 +175,7 @@ FK 旋转）。两份示例文件分别命中两种路径。

 ## 4. 开源依赖与许可证（引用 `open-source-credits.md`）

- `bvh`（MIT）— BVH 解析参考实现
- `Assimp`（BSD-3-Clause）— FBX/glTF 转换，**可选外部依赖**
- `@pixiv/three-vrm`（MIT）— 管理端 VRM 预览
- `three`（MIT）— 管理端 3D 预览
+- `bvh`（MIT）- BVH 解析参考实现
+- `Assimp`（BSD-3-Clause）- FBX/glTF 转换，**可选外部依赖**
+- `@pixiv/three-vrm`（MIT）- 管理端 VRM 预览
+- `three`（MIT）- 管理端 3D 预览
@@ -1,10 +1,10 @@
-# contracts/open-source-credits.md — 开源声明锚点 v0.1.0
+# 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 管理端 |
@@ -21,7 +21,7 @@
 | 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 项为实际引入的构建期/运行时依赖，
+> 注意：文档模板中列出的 10 项为**最低要求**；第 11-15 项为实际引入的构建期/运行时依赖，
 > 一并声明更完整。发布时必须保留各许可证副本（见 `web-server/LICENSE-THIRD-PARTY/`）。

 ## 版权声明补充
@@ -262,7 +262,7 @@ paths:
    parameters: [{ $ref: '#/components/parameters/Id' }]
    post:
      tags: [motions]
-      summary: 触发 BVH/FBX → MediaPipe33 关键点序列预处理（同步执行）
+      summary: 触发 BVH/FBX -> MediaPipe33 关键点序列预处理（同步执行）
      description: |
        同步执行并返回最终状态：成功时 preprocessState=done；
        失败时返回 422，且 Motion.preprocessError 记录可读原因。
@@ -285,7 +285,7 @@ paths:
        '200':
          description: |
            application/x-ndjson，每行一个帧对象：
-            {"frame":0,"timeMs":0,"points":[[x,y,z,conf], …33],"angles":[9 个余弦]}
+            {"frame":0,"timeMs":0,"points":[[x,y,z,conf], ...33],"angles":[9 个余弦]}
          content:
            application/x-ndjson:
              schema: { type: string }
@@ -323,11 +323,11 @@ paths:

        - `.glb` / `.vrm` / `.gltf`：**直接导入**，不重编码
        - `.pmx` / `.fbx`：服务端转换，**优先 GLB、其次 VRM**
-        - `.zip`：**自动搜索包内可用模型** —— `.vrm` → `.glb` → `.gltf`（直接导入）
-          优先，其次 `.pmx` → `.fbx`（转换）。压缩包原件作为 `model-archive` 资产留存。
+        - `.zip`：**自动搜索包内可用模型** -- `.vrm` -> `.glb` -> `.gltf`（直接导入）
+          优先，其次 `.pmx` -> `.fbx`（转换）。压缩包原件作为 `model-archive` 资产留存。

-        转换链路（`model-convert.ts`）：`assimp export → .glb` →（失败）`→ .gltf` 后
-        由服务端自行打包成 GLB →（`MODEL_CONVERT_FORMAT=vrm` 时）在 GLB 之上补
+        转换链路（`model-convert.ts`）：`assimp export -> .glb` ->（失败）`-> .gltf` 后
+        由服务端自行打包成 GLB ->（`MODEL_CONVERT_FORMAT=vrm` 时）在 GLB 之上补
        `VRMC_vrm` 扩展产出 VRM 1.0。每一步都 `assimp info` **回读校验**，
        并把过程写进 `conversionNote`；贴图会内嵌进 GLB，保证单文件可用。

@@ -488,7 +488,7 @@ paths:
      - $ref: '#/components/parameters/Id'
    post:
      tags: [reviews]
-      summary: 审核通过 → published
+      summary: 审核通过 -> published
      requestBody:
        content:
          application/json:
@@ -510,7 +510,7 @@ paths:
      - $ref: '#/components/parameters/Id'
    post:
      tags: [reviews]
-      summary: 撤回审核 → draft
+      summary: 撤回审核 -> draft
      requestBody:
        content:
          application/json:
@@ -552,7 +552,7 @@ paths:
      - $ref: '#/components/parameters/Id'
    post:
      tags: [reviews]
-      summary: 审核驳回 → rejected
+      summary: 审核驳回 -> rejected
      requestBody:
        required: true
        content:
@@ -664,7 +664,7 @@ components:
          type: object
          properties:
            connected: { type: boolean }
-            server: { type: string, description: '如 MariaDB 10.11.19' }
+            server: { type: string, description: '如 MariaDB 10.5+' }
            database: { type: string }
            migrationsPending: { type: integer }

@@ -795,13 +795,13 @@ components:
            fileSha256:
              type: string
              nullable: true
-              description: 模型文件（转换产物）的 sha256 —— 每次转换都会变（Assimp 导出非字节级确定），仅作记录
+              description: 模型文件（转换产物）的 sha256 -- 每次转换都会变（Assimp 导出非字节级确定），仅作记录
            stats:
              type: object
              nullable: true
              description: >-
                模型分析结果（面数 / 顶点数 / 贴图 / 骨骼树 / humanoid 覆盖 / 可驱动性），
-                审核界面据此判断"能不能驱动与评分"。结构见 contracts/model-formats.md §1.1
+                审核界面据此判断"能不能驱动与评分"。结构见 contracts/model-formats.md 1.1
            sourceSha256:
              type: string
              nullable: true
@@ -1,11 +1,11 @@
-# contracts/skeleton-topology.md — 骨骼拓扑契约 v0.1.0
+# contracts/skeleton-topology.md - 骨骼拓扑契约 v0.1.0

 **唯一拓扑：MediaPipe Pose 33 点。禁止引入 SMPL 及其衍生拓扑（许可风险）。**

 ## 1. 33 点定义与索引

 | idx | name | 中文 | 说明 |
-|---|---|---|---|
+|--|--|--|--|
 | 0 | nose | 鼻 | |
 | 1 | left_eye_inner | 左眼内 | |
 | 2 | left_eye | 左眼 | |
@@ -43,7 +43,7 @@
 ## 2. 虚拟关节（由 33 点派生，索引 33/34，仅用于层级与角度特征）

 | idx | name | 计算 |
-|---|---|---|
+|--|--|--|
 | 33 | neck | `midpoint(left_shoulder(11), right_shoulder(12))` |
 | 34 | pelvis | `midpoint(left_hip(23), right_hip(24))` |

@@ -1,6 +1,6 @@
-# contracts/websocket-keypoints.md — 关键点传输契约 v0.1.0
+# contracts/websocket-keypoints.md - 关键点传输契约 v0.1.0

-Android 辅助 App（发送端）→ Windows 客户端（接收端）。
+Android 辅助 App（发送端）-> Windows 客户端（接收端）。
 服务端不参与实时链路，但 T-WEB-006 预处理产出的序列必须与此结构同构。

 ## 1. 端点
@@ -28,7 +28,7 @@ ws://<windows-host>:8765/pose
                                    bit3-7 保留，必须为 0
 4     4     frame_id      u32 LE    单调递增，从 0 开始
 8     231   keypoints     33 × 7B   见下
--------------------------------------------------------------
+--
 合计  239
 ```

@@ -70,7 +70,7 @@ func decode(buf: PackedByteArray) -> Dictionary:

 ## 3. 文本控制帧（JSON，UTF-8）

-### 3.1 `hello` — Android → Windows，连接后立即发送
+### 3.1 `hello` - Android -> Windows，连接后立即发送

 ```json
 {
@@ -84,25 +84,25 @@ func decode(buf: PackedByteArray) -> Dictionary:
 }
 ```

-### 3.2 `welcome` — Windows → Android
+### 3.2 `welcome` - Windows -> Android

 ```json
 { "type": "welcome", "protocol": "opendance.pose.v1", "sessionId": "uuid", "expectedFps": 30 }
 ```

-### 3.3 `config` — Windows → Android，运行中调整
+### 3.3 `config` - Windows -> Android，运行中调整

 ```json
 { "type": "config", "mirror": true, "targetFps": 30, "upperBodyOnly": false, "resolution": "640x480" }
 ```

-### 3.4 `stats` — Android → Windows，每秒一次
+### 3.4 `stats` - Android -> Windows，每秒一次

 ```json
 { "type": "stats", "fps": 29.6, "dropped": 3, "latencyMs": 42, "confidenceAvg": 0.93 }
 ```

-### 3.5 `bye` — 双向
+### 3.5 `bye` - 双向

 ```json
 { "type": "bye", "reason": "user_stop" }
@@ -117,7 +117,7 @@ func decode(buf: PackedByteArray) -> Dictionary:
  "frameId": 1024,
  "timestampMs": 1730000000000,
  "flags": { "mirrored": false, "upperBodyOnly": false },
-  "points": [[0.51, 0.22, -0.03, 0.99], "…共 33 项，顺序固定 [x, y, z, conf]"]
+  "points": [[0.51, 0.22, -0.03, 0.99], "...共 33 项，顺序固定 [x, y, z, conf]"]
 }
 ```