feat(models): 模型一律转 VRM（契约 0.5.0）+ 可用性门槛 + 管理端版本号展示

按《DSH 开发文档 v1.6》4.9 与第十一章实现，Web 端第一步：

1. 契约先行（先改 contracts/ 再同步三端）：
   * model-formats.md -> 0.5.0：模型主力格式改为 VRM，所有上传模型一律转 VRM
     （.pmx/.fbx: assimp -> GLB -> VRM；glb/gltf: 包装为 VRM）；
     新增 humanoid 硬门槛与"不达标回退 GLB + usable=false"的交付表；
   * data-models.md -> 0.5.0：Model 新增 usable / unusableReason，明确
     usable=false 不进入 catalog/export；format 说明改为主力 vrm；
   * VERSION 与 contract-versions.ts 同步（三端契约文件逐字节一致）。
2. 实现：
   * MODEL_CONVERT_FORMAT 默认改为 vrm（deploy/.env.example 同步）；
   * 新增 isUsableModel()/unusableReason()：usable 等价于"已产出 VRM"，
     原因从 stats 里带出 humanoid 覆盖度；
   * catalog/export 与 catalog/version 指纹都只统计 format=vrm 的已发布模型，
     resolveDefaultModelId 同样只在可用模型中选；
   * 管理端：模型列表与审核面板显示「不可用」及原因；
   * 管理端左下角展示当前版本号（构建期从 web-server/package.json 注入
     __APP_VERSION__，与 GET /health 同源），并去掉写死的"契约 rest-api 0.1.0"。
3. 测试：新增 test/model-usability.spec.ts 5 项；规模 16 文件 / 225 项。
4. 版本 0.3.0。

web-server/src/catalog/catalog.service.ts

@@ -2,7 +2,7 @@ import { Injectable } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
 import { createHash } from 'node:crypto';
 import { Repository } from 'typeorm';
-import { PublishStatus } from '../common/enums';
+import { ModelFormat, PublishStatus } from '../common/enums';
 import { AppConfig } from '../config/configuration';
 import { CharacterModel } from '../entities/model.entity';
 import { Motion } from '../entities/motion.entity';
@@ -43,7 +43,11 @@ export class CatalogService {
     const [songs, motions, models] = await Promise.all([
       this.songs.find({ where: { status: PublishStatus.Published }, order: { id: 'ASC' } }),
       this.motions.find({ where: { status: PublishStatus.Published }, order: { id: 'ASC' } }),
-      this.models.find({ where: { status: PublishStatus.Published }, order: { id: 'ASC' } }),
+      // v0.5.0：只交付**已产出 VRM** 的模型（usable），未产出 VRM 的不进入客户端目录
+      this.models.find({
+        where: { status: PublishStatus.Published, format: ModelFormat.Vrm },
+        order: { id: 'ASC' },
+      }),
     ]);
 
     const [songDtos, motionDtos, modelDtos, defaultModelId] = await Promise.all([
@@ -71,7 +75,11 @@ export class CatalogService {
     const [songs, motions, models] = await Promise.all([
       this.songs.find({ where: { status: PublishStatus.Published }, order: { id: 'ASC' } }),
       this.motions.find({ where: { status: PublishStatus.Published }, order: { id: 'ASC' } }),
-      this.models.find({ where: { status: PublishStatus.Published }, order: { id: 'ASC' } }),
+      // v0.5.0：只交付**已产出 VRM** 的模型（usable），未产出 VRM 的不进入客户端目录
+      this.models.find({
+        where: { status: PublishStatus.Published, format: ModelFormat.Vrm },
+        order: { id: 'ASC' },
+      }),
     ]);
 
     const fingerprint = JSON.stringify({

web-server/src/config/configuration.ts

@@ -88,7 +88,9 @@ export class AppConfig {
    * 设为 `vrm` 时会在 GLB 之上补 `VRMC_vrm` 扩展，humanoid 骨骼不全则回退 GLB。
    */
   get modelConvertFormat(): 'glb' | 'vrm' {
-    return (this.config.get<string>('modelConvertFormat') ?? 'glb') === 'vrm' ? 'vrm' : 'glb';
+    // v0.5.0 起默认 **vrm**：所有上传模型一律转 VRM（见 contracts/model-formats.md 1.1）；
+    // humanoid 不达标时管线自动回退交付 GLB 并置 usable=false。
+    return (this.config.get<string>('modelConvertFormat') ?? 'vrm') === 'glb' ? 'glb' : 'vrm';
   }
 
   /**
@@ -207,7 +209,7 @@ export const configuration = () => {
     adminDir: process.env.ADMIN_DIR ?? resolve(process.cwd(), '..', 'admin'),
     uploadMaxBytes: Number(process.env.UPLOAD_MAX_BYTES ?? 512 * 1024 * 1024),
     assimpBin: process.env.ASSIMP_BIN ?? 'assimp',
-    modelConvertFormat: process.env.MODEL_CONVERT_FORMAT ?? 'glb',
+    modelConvertFormat: process.env.MODEL_CONVERT_FORMAT ?? 'vrm',
     modelShading: process.env.MODEL_SHADING ?? 'pbr',
     modelConvertPmx: process.env.MODEL_CONVERT_PMX ?? 'Hatsune Miku.pmx',
     modelConvertTimeoutMs: Number(process.env.MODEL_CONVERT_TIMEOUT_MS ?? 180_000),

web-server/src/config/contract-versions.ts

@@ -11,9 +11,9 @@ import { join } from 'node:path';
 export const CONTRACT_VERSIONS: Readonly<Record<string, string>> = Object.freeze({
   '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',
 });
 

web-server/src/models/model.serializer.ts

@@ -1,4 +1,5 @@
 import { ModelFormat, PublishStatus, SourceType } from '../common/enums';
+import type { ModelStats } from './model-inspector';
 import { CharacterModel } from '../entities/model.entity';
 
 /** 契约 data-models.md §4 的对外表示 */
@@ -7,6 +8,13 @@ export interface ModelDto {
   name: string;
   format: ModelFormat;
   vrmVersion: string | null;
+  /**
+   * 是否可被客户端使用（v0.5.0）：等价于"已产出 VRM"。
+   * `false` 的模型**不进入 `catalog/export`**，但仍可入库与审核。
+   */
+  usable: boolean;
+  /** `usable=false` 时的原因（中文，供审核面板直接展示） */
+  unusableReason: string | null;
   isPrimary: boolean;
   fileUrl: string | null;
   fileSize: number | null;
@@ -37,12 +45,35 @@ export interface ModelUrlLookup {
   sourceSha256?: string | null;
 }
 
+/**
+ * 模型是否可用于客户端（v0.5.0 门槛）：**必须已产出 VRM**。
+ *
+ * 依据 `contracts/model-formats.md` 1.1：所有上传模型一律转 VRM；
+ * humanoid 不达标时管线回退交付 GLB，此时模型可入库、可审核，但**不可用**、
+ * 不进入 `catalog/export` —— 待按 skeleton-topology 标准重绑定骨骼后重新转换即转为可用。
+ */
+export function isUsableModel(model: CharacterModel): boolean {
+  return model.format === ModelFormat.Vrm;
+}
+
+/** 不可用的原因（可用时返回 null）；从 stats 取 humanoid 覆盖度，便于人工定位 */
+export function unusableReason(model: CharacterModel): string | null {
+  if (isUsableModel(model)) return null;
+  const stats = (model.stats ?? null) as Partial<ModelStats> | null;
+  if (stats && typeof stats.humanoidMapped === 'number' && typeof stats.humanoidTotal === 'number') {
+    return `humanoid 不达标（${stats.humanoidMapped}/${stats.humanoidTotal}），未产出 VRM`;
+  }
+  return '未产出 VRM（格式为 GLB），不可用于客户端';
+}
+
 export function toModelDto(model: CharacterModel, urls: ModelUrlLookup): ModelDto {
   return {
     id: model.id,
     name: model.name,
     format: model.format,
     vrmVersion: model.vrmVersion,
+    usable: isUsableModel(model),
+    unusableReason: unusableReason(model),
     isPrimary: model.isPrimary,
     fileUrl: urls.fileUrl,
     fileSize: urls.fileSize ?? null,

web-server/src/models/models.service.ts

@@ -451,8 +451,9 @@ export class ModelsService {
    *   4. id 最小的已发布模型
    */
   async resolveDefaultModelId(): Promise<number | null> {
+    // v0.5.0：默认模型必须来自**可用**模型（已产出 VRM）；未产出 VRM 的不进客户端目录
     const published = await this.models.find({
-      where: { status: PublishStatus.Published },
+      where: { status: PublishStatus.Published, format: ModelFormat.Vrm },
       order: { id: 'ASC' },
     });
     if (published.length === 0) return null;