From efb2484125110027888cf8bd7833908afeb9fb4f Mon Sep 17 00:00:00 2001
From: opendance <dev@opendance.local>
Date: Thu, 17 Sep 2026 00:05:02 +0800
Subject: [PATCH] =?UTF-8?q?chore(contracts):=20=E5=90=8C=E6=AD=A5=E5=A5=91?=
 =?UTF-8?q?=E7=BA=A6=200.5.0=EF=BC=88=E6=A8=A1=E5=9E=8B=E4=B8=80=E5=BE=8B?=
 =?UTF-8?q?=E8=BD=AC=20VRM=EF=BC=8CModel=20=E5=A2=9E=20usable/unusableReas?=
 =?UTF-8?q?on=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

来自 opendance-web 的契约变更，按 DSH 文档 7.2「先改 Web 端 contracts/ 再同步另两端」：
- model-formats.md -> 0.5.0：主力格式 VRM + humanoid 门槛与回退
- data-models.md -> 0.5.0：Model 增 usable / unusableReason
- VERSION 同步
---
 contracts/VERSION          |  4 ++--
 contracts/data-models.md   |  6 ++++--
 contracts/model-formats.md | 31 ++++++++++++++++++++++++++-----
 3 files changed, 32 insertions(+), 9 deletions(-)

diff --git a/contracts/VERSION b/contracts/VERSION
index b559400..c823346 100644
--- a/contracts/VERSION
+++ b/contracts/VERSION
@@ -2,7 +2,7 @@
 # 规则：任何字段级变更必须提升对应条目版本，并回到 opendance-web 修改后再向另两端建迁移任务。
 rest-api: 0.4.0
 websocket-keypoints: 0.1.0
-data-models: 0.4.0
+data-models: 0.5.0
 skeleton-topology: 0.1.0
-model-formats: 0.4.0
+model-formats: 0.5.0
 database: 0.3.0
diff --git a/contracts/data-models.md b/contracts/data-models.md
index be11338..9915be6 100644
--- a/contracts/data-models.md
+++ b/contracts/data-models.md
@@ -1,4 +1,4 @@
-# contracts/data-models.md - 数据模型契约 v0.4.0
+# contracts/data-models.md - 数据模型契约 v0.5.0
 
 Web 服务端是唯一权威定义，本文件是另两端消费的**稳定视图**。
 字段名在 JSON 中统一 `camelCase`；数据库列名 `snake_case`（见 `database.md`）。
@@ -96,8 +96,10 @@ rejected   已驳回
 |--|--|--|--|
 | `id` | number | 读 | |
 | `name` | string | ✅ | 模型名称，<=200 |
-| `format` | enum | ✅ | `glb` / `vrm`（主力）/ `gltf` / `fbx`（历史数据）。上传的 PMX/FBX 会被服务端转换成 glb 或 vrm 再入库，见 model-formats.md 1.1 |
+| `format` | enum | ✅ | `vrm`（主力）/ `glb`（回退或历史数据）/ `gltf` / `fbx`。**所有上传模型一律转换为 VRM**，只有 humanoid 不达标时回退为 `glb` 并置 `usable=false`，见 model-formats.md 1.1 |
 | `vrmVersion` | string\|null | 读 | `0.x` / `1.0`，非 VRM 为 null |
+| `usable` | boolean | 读 | **是否可被客户端使用**：等价于"已产出 VRM"（`format=vrm`）。`false` 的模型**不出现在 `catalog/export`**（v0.5.0） |
+| `unusableReason` | string\|null | 读 | `usable=false` 时的原因，例如 `humanoid 不达标（0/22），未产出 VRM` |
 | `isPrimary` | boolean | | 全局默认模型；**同一时刻全库至多一个 `true`** |
 | `fileUrl` | string | 读 | |
 | `fileSize` | number | 读 | |
diff --git a/contracts/model-formats.md b/contracts/model-formats.md
index b6a50c2..ce91cbf 100644
--- a/contracts/model-formats.md
+++ b/contracts/model-formats.md
@@ -1,20 +1,41 @@
-# contracts/model-formats.md - 模型与动作格式契约 v0.4.0
+# contracts/model-formats.md - 模型与动作格式契约 v0.5.0
 
 ## 1. 角色模型(models)
 
-**系统以 GLB / VRM 为主力格式**（两个客户端都原生加载），其余格式一律在服务端转换。
+**v0.5.0 起模型主力格式为 VRM**：**所有上传的模型都转换为 VRM**（`MODEL_CONVERT_FORMAT`
+默认 `vrm`）；GLB 退为**转换中间产物**与 **humanoid 不达标时的回退交付**。
+两个客户端（Godot `godot-vrm` / 管理端 `@pixiv/three-vrm`）都原生加载 VRM。
 
 | 格式 | 扩展名 | 支持级别 | 服务端行为 |
 |--|--|--|--|
-| glTF Binary | `.glb` | **主力(P0)** | **直接导入**，不重编码 |
 | VRM | `.vrm` | **主力(P0)** | **直接导入**; = GLB + VRM 扩展(humanoid / 表情 / springBone / meta) |
+| glTF Binary | `.glb` | 输入(P0) | 导入后**包装为 VRM**（含 `VRMC_vrm`）；humanoid 不齐时保留 GLB 并标记 `usable=false` |
 | 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) |
+| MMD 模型 | `.pmx` | P2（输入） | 服务端转换：`assimp -> GLB -> VRM`；单文件上传无贴图 |
+| FBX | `.fbx` | P2（输入） | 服务端转换：`assimp -> GLB -> VRM` |
 
 ### 1.1 上传与转换策略
 
+**v0.5.0 起的一律转换链路**：
+
+```
+.vrm            -> 直接导入（已是 VRM）
+.glb / .gltf    -> 包装为 VRM 1.0（写 VRMC_vrm）
+.pmx / .fbx     -> assimp -> GLB -> 包装为 VRM 1.0
+.zip            -> 自动搜索包内模型，按上面三种处理
+```
+
+**humanoid 门槛（硬性）**：VRM 1.0 要求 humanoid 必需骨骼齐全。服务端判定规则：
+
+| 情况 | 交付 | `models.usable` | 是否进入客户端目录 |
+|--|--|--|--|
+| humanoid 必需骨齐全 | **VRM**（`format=vrm`，`vrmVersion=1.0`） | `true` | ✅ 可发布、可选用 |
+| humanoid 不齐（如 MMD 日文骨名未重绑定） | 回退交付 **GLB**，`vrmVersion=null`，`conversionNote` 注明原因 | `false` | ❌ 不进入 `catalog/export` |
+
+即：**不达标模型仍可入库与审核，但标记为不可用、不进入已发布目录**；
+待骨骼按 `skeleton-topology.md` 的标准重绑定成功后重新转换即变为可用。
+
 **`.glb` / `.vrm` / `.gltf` 直接导入**（不重编码，零损失）；**`.pmx` / `.fbx` 由服务端转换**:
 **优先 GLB，其次 VRM**。