chore(contracts): 同步契约 0.5.0(模型一律转 VRM,Model 增 usable/unusableReason)

来自 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 同步
This commit is contained in:
opendance
2026-09-17 00:05:02 +08:00
parent 4913760a8b
commit efb2484125
3 changed files with 32 additions and 9 deletions
+4 -2
View File
@@ -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 | 读 | |