+ 不可用：该模型不会进入客户端目录
+ {model.unusableReason ?? '未产出 VRM'}
+
+ 依据契约 model-formats 1.1，所有模型一律转 VRM；humanoid 必需骨齐全后重新导入即可转为可用。
+
+
+ ) : null}
+
{/* 可驱动性结论 */}
diff --git a/web-server/admin/src/lib/version.ts b/web-server/admin/src/lib/version.ts
new file mode 100644
index 0000000..a947507
--- /dev/null
+++ b/web-server/admin/src/lib/version.ts
@@ -0,0 +1,10 @@
+/**
+ * 应用版本号（构建期由 vite.config.ts 从 web-server/package.json 注入）。
+ * 页面左下角必须展示它，且与 `GET /health` 的 version、发布产物文件名一致
+ * （开发文档 v1.5 第十一章）。SSR / 测试环境下回退为 '0.0.0'。
+ */
+export const APP_VERSION: string =
+ typeof __APP_VERSION__ === 'string' && __APP_VERSION__.length > 0 ? __APP_VERSION__ : '0.0.0';
+
+/** 展示用：带 v 前缀 */
+export const APP_VERSION_LABEL = `v${APP_VERSION}`;
diff --git a/web-server/admin/src/pages/Models.tsx b/web-server/admin/src/pages/Models.tsx
index 76a11b8..bed22d0 100644
--- a/web-server/admin/src/pages/Models.tsx
+++ b/web-server/admin/src/pages/Models.tsx
@@ -492,6 +492,14 @@ export function ModelsPage() {
{model.vrmVersion ?? '—'}
diff --git a/web-server/admin/src/styles.css b/web-server/admin/src/styles.css
index ac1ba59..2cac0ef 100644
--- a/web-server/admin/src/styles.css
+++ b/web-server/admin/src/styles.css
@@ -173,6 +173,14 @@ h3 {
color: var(--text-mute);
}
+.app-version {
+ font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+ font-size: 12px;
+ font-weight: 600;
+ color: var(--text-strong, #e8ecf3);
+ letter-spacing: 0.02em;
+}
+
.sidebar-foot code {
color: var(--text-dim);
word-break: break-all;
diff --git a/web-server/admin/src/vite-env.d.ts b/web-server/admin/src/vite-env.d.ts
index 7a7f1cd..cb4be40 100644
--- a/web-server/admin/src/vite-env.d.ts
+++ b/web-server/admin/src/vite-env.d.ts
@@ -7,3 +7,6 @@ interface ImportMetaEnv {
interface ImportMeta {
readonly env: ImportMetaEnv;
}
+
+/** 构建期注入的应用版本号（来自 web-server/package.json） */
+declare const __APP_VERSION__: string;
diff --git a/web-server/admin/vite.config.ts b/web-server/admin/vite.config.ts
index fec90c7..e358288 100644
--- a/web-server/admin/vite.config.ts
+++ b/web-server/admin/vite.config.ts
@@ -1,11 +1,26 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
const API_TARGET = 'http://localhost:3000';
+/**
+ * 版本号唯一来源：`web-server/package.json`（与 `GET /health` 的 version 同源）。
+ * 构建期注入 `__APP_VERSION__`，管理端左下角直接展示，避免代码里再手写一份
+ * （见开发文档 v1.5 第十一章「版本号展示」）。
+ */
+const serverPackage = JSON.parse(
+ readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8'),
+) as { version?: string };
+const APP_VERSION = serverPackage.version ?? '0.0.0';
+
// base './' 让产物可挂在任意子路径；开发期 /api 与 /health 代理到 NestJS 服务。
export default defineConfig({
base: './',
+ define: {
+ __APP_VERSION__: JSON.stringify(APP_VERSION),
+ },
plugins: [react()],
server: {
port: 5173,
diff --git a/web-server/package.json b/web-server/package.json
index 47d7529..bd32bf4 100644
--- a/web-server/package.json
+++ b/web-server/package.json
@@ -1,6 +1,6 @@
{
"name": "opendance-web-server",
- "version": "0.2.5",
+ "version": "0.3.0",
"description": "OpenDance Studio Web 管理服务端（NestJS + TypeORM + 现有 MySQL 实例）",
"license": "MIT",
"private": true,
diff --git a/web-server/src/catalog/catalog.service.ts b/web-server/src/catalog/catalog.service.ts
index daa1238..44f2c07 100644
--- a/web-server/src/catalog/catalog.service.ts
+++ b/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({
diff --git a/web-server/src/config/configuration.ts b/web-server/src/config/configuration.ts
index 9ff18a4..dd8f26e 100644
--- a/web-server/src/config/configuration.ts
+++ b/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('modelConvertFormat') ?? 'glb') === 'vrm' ? 'vrm' : 'glb';
+ // v0.5.0 起默认 **vrm**：所有上传模型一律转 VRM（见 contracts/model-formats.md 1.1）；
+ // humanoid 不达标时管线自动回退交付 GLB 并置 usable=false。
+ return (this.config.get('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),
diff --git a/web-server/src/config/contract-versions.ts b/web-server/src/config/contract-versions.ts
index b9f48a9..b4b3b7c 100644
--- a/web-server/src/config/contract-versions.ts
+++ b/web-server/src/config/contract-versions.ts
@@ -11,9 +11,9 @@ import { join } from 'node:path';
export const CONTRACT_VERSIONS: Readonly> = 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',
});
diff --git a/web-server/src/models/model.serializer.ts b/web-server/src/models/model.serializer.ts
index 163b61c..b94db35 100644
--- a/web-server/src/models/model.serializer.ts
+++ b/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 | 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,
diff --git a/web-server/src/models/models.service.ts b/web-server/src/models/models.service.ts
index a1a9b2d..72baa7a 100644
--- a/web-server/src/models/models.service.ts
+++ b/web-server/src/models/models.service.ts
@@ -451,8 +451,9 @@ export class ModelsService {
* 4. id 最小的已发布模型
*/
async resolveDefaultModelId(): Promise {
+ // 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;
diff --git a/web-server/test/model-usability.spec.ts b/web-server/test/model-usability.spec.ts
new file mode 100644
index 0000000..798a74a
--- /dev/null
+++ b/web-server/test/model-usability.spec.ts
@@ -0,0 +1,110 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { CatalogService } from '../src/catalog/catalog.service';
+import { ModelFormat, PublishStatus, SourceType } from '../src/common/enums';
+import type { CharacterModel } from '../src/entities/model.entity';
+import { isUsableModel, toModelDto, unusableReason } from '../src/models/model.serializer';
+
+/**
+ * v0.5.0「模型一律转 VRM」的可用性门槛。
+ *
+ * 规则（contracts/model-formats.md 1.1）：所有上传模型都转 VRM；
+ * humanoid 不达标时回退交付 GLB —— 这种模型**可入库、可审核，但不可用**，
+ * **不进入 `catalog/export`**（用户明确选择"入库但标记不可用，不进已发布目录"）。
+ */
+
+function model(overrides: Partial = {}): CharacterModel {
+ return {
+ id: 1,
+ name: 'model',
+ format: ModelFormat.Vrm,
+ vrmVersion: '1.0',
+ isPrimary: false,
+ fileAssetId: 1,
+ sourceAssetId: null,
+ thumbnailAssetId: null,
+ conversionNote: null,
+ stats: null,
+ sourceType: SourceType.Other,
+ sourceName: 'x',
+ sourceUrl: 'x',
+ license: 'x',
+ author: 'x',
+ status: PublishStatus.Published,
+ createdAt: new Date('2026-01-01T00:00:00Z'),
+ updatedAt: new Date('2026-01-01T00:00:00Z'),
+ ...overrides,
+ } as CharacterModel;
+}
+
+describe('模型可用性（usable）', () => {
+ it('VRM → 可用，且没有不可用原因', () => {
+ const vrm = model({ format: ModelFormat.Vrm });
+ expect(isUsableModel(vrm)).toBe(true);
+ expect(unusableReason(vrm)).toBeNull();
+ expect(toModelDto(vrm, { fileUrl: '/f', thumbnailUrl: null }).usable).toBe(true);
+ });
+
+ it('GLB（humanoid 不达标）→ 不可用，原因带 humanoid 覆盖度', () => {
+ const glb = model({
+ format: ModelFormat.Glb,
+ vrmVersion: null,
+ stats: { humanoidMapped: 0, humanoidTotal: 22 } as Record,
+ });
+ expect(isUsableModel(glb)).toBe(false);
+ expect(unusableReason(glb)).toBe('humanoid 不达标（0/22），未产出 VRM');
+ const dto = toModelDto(glb, { fileUrl: '/f', thumbnailUrl: null });
+ expect(dto.usable).toBe(false);
+ expect(dto.unusableReason).toContain('0/22');
+ });
+
+ it('GLB 且没有 stats → 给出通用原因（不抛错）', () => {
+ const glb = model({ format: ModelFormat.Glb, vrmVersion: null, stats: null });
+ expect(unusableReason(glb)).toContain('未产出 VRM');
+ });
+});
+
+describe('目录导出只含可用模型', () => {
+ function buildService(captured: { modelsWhere?: unknown }): CatalogService {
+ const songs = { find: vi.fn().mockResolvedValue([]) };
+ const motions = { find: vi.fn().mockResolvedValue([]) };
+ const models = {
+ find: vi.fn().mockImplementation((options: { where: unknown }) => {
+ captured.modelsWhere = options.where;
+ return Promise.resolve([model({ id: 7, format: ModelFormat.Vrm })]);
+ }),
+ };
+ const songsService = { toDtos: vi.fn().mockResolvedValue([]) };
+ const motionsService = { toDtos: vi.fn().mockResolvedValue([]) };
+ const modelsService = {
+ toDtos: vi.fn().mockImplementation((rows: CharacterModel[]) =>
+ rows.map((row) => toModelDto(row, { fileUrl: '/f', thumbnailUrl: null })),
+ ),
+ resolveDefaultModelId: vi.fn().mockResolvedValue(7),
+ };
+ const config = { contractVersions: { 'rest-api': '0.5.0' } };
+ return new CatalogService(
+ songs as never,
+ motions as never,
+ models as never,
+ songsService as never,
+ motionsService as never,
+ modelsService as never,
+ config as never,
+ );
+ }
+
+ it('查询条件限定 status=published 且 format=vrm', async () => {
+ const captured: { modelsWhere?: unknown } = {};
+ const bundle = await buildService(captured).exportBundle();
+ expect(captured.modelsWhere).toEqual({ status: PublishStatus.Published, format: ModelFormat.Vrm });
+ expect(bundle.models.map((m) => m.id)).toEqual([7]);
+ expect(bundle.models.every((m) => m.usable)).toBe(true);
+ });
+
+ it('目录指纹同样只统计可用模型（否则客户端会因"不可见变化"反复刷新）', async () => {
+ const captured: { modelsWhere?: unknown } = {};
+ await buildService(captured).version();
+ expect(captured.modelsWhere).toEqual({ status: PublishStatus.Published, format: ModelFormat.Vrm });
+ });
+});