test(integration): 跨端验收补两类契约边界（不可用模型 / 场景 config 缺字段）

正常路径之外的**字段边界**同样只在跨端跑起来才暴露。配合 Web v0.7.5 增加：

1. 不可用模型：用 Assimp 把真实 PMX 转成 GLB 后入库（等价"管线只产出 GLB"），
   Web 侧断言 usable=false、原因准确（骨架达标时不得说"humanoid 不达标"）、
   不在 catalog/export、defaultModelId 不变；Windows 侧（包内探针）断言
   bundle.models 里没有任何非 VRM 模型、按 id 找不到该模型、defaultModelId 仍指向可用 VRM。
2. 场景 config 只给 {physics:{gravity:{y:-9.8}}}：Web 侧断言服务端补齐默认
   （碰撞体 auto、地面 0.6/45°、静风、相机 follow、环境光 1、出生点 1 条）；
   Windows 侧断言客户端解析出的**同一组默认值**逐项一致。

实测（Web v0.7.5 × Windows v0.2.5 包内 pck，真实 MySQL）：
  ✓ usable=false 且原因为「未产出 VRM（格式为 GLB；humanoid 覆盖 19/22 已达标）…」
  ✓ 目录里的模型全是 VRM／不可用模型 #2 不在目录里／defaultModelId 仍为 1
  ✓ 最简配置：重力 -9.8 保留，碰撞体 auto、地面 0.6/45°、静风、相机 follow、
    环境光 1.0、出生点 1 条，两端逐项一致
跨端集成验收全部通过。

顺带修掉播种脚本自身的顺序错误（把依赖 catalog 的断言插到了 catalog 取回之前），
以及把断言改成「先取目录再断言」。不影响发布产物（build/ 已排除出 pck）。

README.md

@@ -204,7 +204,12 @@ GODOT_BIN=... bash build/accept-ws.sh <zip> --skip-slow
 * `build/accept-ws.sh`：编排两者，并核对**客户端看不到的那一半**（服务端侧
   `frames_dropped` / `malformed_frames` / 控制帧计数 / 去重事件 / 关闭原因）。
 
-实测（已发布的 v0.2.3 资产）：客户端 **30 通过 / 0 失败** + 服务端侧 16 项事实全过，
+**契约边界场景**（配合 Web v0.7.5）：① **不可用模型**（真实 PMX 经 Assimp 转 GLB 后入库）
+必须 `usable=false`、**不进入** `catalog/export`、不影响 `defaultModelId`，且包内客户端
+`bundle.models` 里没有任何非 VRM 模型；② 场景 `config` **只给最少字段**时，服务端补齐的默认值
+与客户端解析出的默认值**逐项一致**（碰撞体 `auto`、地面 `0.6/45°`、静风、相机 `follow`…）。
+
+实测（已发布的 v0.2.5 资产）：客户端 **40 通过 / 0 失败** + 服务端侧 16 项事实全过，
 其中最关键的是**保活对照**——只发应用层 `ping` 持续 19 秒（> 静默超时 15 秒）连接
 **仍保持**，而完全不发数据的连接在 **15011 ms**（阈值 15000 ms）被 `close(1001, "timeout")`。
 反向验证用一个**故意不合规的服务端**（`build/integration/probe-ws-bad.gd`：welcome 不声明

build/integration/probe-integration.gd

@@ -245,6 +245,45 @@ func _run() -> void:
 		else:
 			_fail("动作缩略图下载失败：%s" % thumb["error"])
 
+	# ---------- 5b. ② 目录边界：不可用模型不得出现在客户端目录里（①）----------
+	var nonVrm: Array = []
+	for m in models:
+		if str(m.format) != "vrm":
+			nonVrm.append("%s(%s)" % [m.name, m.format])
+	_check(nonVrm.is_empty(),
+		"目录里的模型全是 VRM（不可用模型不进目录）：%s" % ("OK" if nonVrm.is_empty() else str(nonVrm)))
+	if _expect.has("unusableModelId") and _expect["unusableModelId"] != null:
+		var unusable_id := int(_expect["unusableModelId"])
+		_check(bundle.find_model(unusable_id) == null,
+			"不可用模型 #%d 不在客户端目录里" % unusable_id)
+	_check(bundle.default_model_id == _expect["modelId"],
+		"defaultModelId 仍指向可用的 VRM 模型（实际 %d）" % bundle.default_model_id)
+
+	# ---------- 5c. ④ 场景 config 缺字段时的默认值（契约 0.5.0 边界）----------
+	if _expect.has("minimalSceneId") and _expect.has("minimalSceneExpect"):
+		var minimal: CatalogTypes.Scene = bundle.find_scene(int(_expect["minimalSceneId"]))
+		if minimal == null:
+			_fail("目录里找不到最简配置场景 #%d" % int(_expect["minimalSceneId"]))
+		else:
+			var want_min: Dictionary = _expect["minimalSceneExpect"]
+			var cfg2: CatalogTypes.SceneConfig = minimal.config
+			_check(_near(cfg2.physics.gravity.y, float(want_min["gravityY"])),
+				"最简配置：重力保留 %.1f" % cfg2.physics.gravity.y)
+			_check(cfg2.physics.colliders == str(want_min["colliders"]),
+				"最简配置：碰撞体补默认 %s" % cfg2.physics.colliders)
+			_check(_near(cfg2.physics.ground.friction, float(want_min["groundFriction"]))
+				and _near(cfg2.physics.ground.slope_limit, float(want_min["groundSlopeLimit"])),
+				"最简配置：地面默认 摩擦 %.2f / 坡度 %.0f°" % [
+					cfg2.physics.ground.friction, cfg2.physics.ground.slope_limit])
+			_check(cfg2.physics.wind.is_calm() == bool(want_min["windCalm"]),
+				"最简配置：风默认静风（is_calm=%s）" % str(cfg2.physics.wind.is_calm()))
+			_check(cfg2.camera.mode == str(want_min["cameraMode"]),
+				"最简配置：相机默认 %s" % cfg2.camera.mode)
+			_check(_near(cfg2.environment.ambient_intensity, float(want_min["ambientIntensity"])),
+				"最简配置：环境光默认 %.1f" % cfg2.environment.ambient_intensity)
+			_check(cfg2.spawn_points.size() <= 1,
+				"最简配置：出生点默认最多一条（实际 %d）" % cfg2.spawn_points.size())
+
 	# ---------- 6. ① 模型资源可下载 ----------
 	var model: CatalogTypes.Model = bundle.find_model(_expect["modelId"])
 	if model == null:

build/integration/seed-catalog.mjs

@@ -3,14 +3,17 @@
  *   真实 VMD 动作 → 预处理成内部标准 33 点；真实 PMX 模型 → 转 VRM；
  *   场景 GLB（复用真实转换产物的几何）+ 契约 0.5.0 的物理参数。
  */
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
 
 const API = process.env.API_BASE ?? 'http://127.0.0.1:3100';
 // 样例目录与期望值输出路径都可通过环境变量覆盖（默认取仓库根的 示例文件/）
 const SAMPLES = process.env.OPENDANCE_SAMPLES_DIR
   ?? new URL('../../../示例文件', import.meta.url).pathname;
 const EXPECT_PATH = process.env.EXPECT_PATH ?? '/tmp/opendance-catalog-expect.json';
+/** 用于把真实 PMX 转成 GLB（模拟"转换只产出 GLB"的入库形态） */
+const ASSIMP_BIN = process.env.ASSIMP_BIN ?? '/usr/bin/assimp';
 const SOURCE = {
   sourceType: 'original',
   sourceName: '跨端集成验收素材',
@@ -102,8 +105,67 @@ const run = async () => {
   must(scene.status === 201, '上传场景 GLB', `${scene.status} ${JSON.stringify(scene.body)}`);
   const sceneId = scene.body.id;
 
+  // ---------- 边界 A：不可用模型（只有 GLB、没有 VRM 容器）----------
+  // 形态等价于"管线只产出了 GLB"：契约 model-formats §1.1 要求这类模型
+  // **可入库、可审核，但 usable=false，且不进入 catalog/export**（① 的硬性要求）。
+  let unusable = null;
+  try {
+    const pmxZip = `${SAMPLES}/模型_初音未来Hatsune Miku_by_Boku_Wa_Luka.zip`;
+    const entries = execFileSync('unzip', ['-Z1', pmxZip], { encoding: 'utf8' })
+      .split('\n').map((line) => line.trim())
+      .filter((line) => line.toLowerCase().endsWith('.pmx'));
+    if (entries.length === 0) throw new Error('压缩包里没有 .pmx');
+    const pmxPath = join('/tmp', 'opendance-seed-model.pmx');
+    const glbPath = join('/tmp', 'opendance-seed-model.glb');
+    execFileSync('unzip', ['-p', pmxZip, entries[0]], { stdio: ['ignore', openSync(pmxPath, 'w'), 'ignore'] });
+    execFileSync(ASSIMP_BIN, ['export', pmxPath, glbPath], { stdio: 'ignore' });
+    const glb = readFileSync(glbPath);
+    must(glb.subarray(0, 4).toString('ascii') === 'glTF', `Assimp 转出 GLB（${glb.length} 字节）`);
+    const created = await request('POST', '/api/models', {
+      form: fileForm({ name: '不可用模型（仅 GLB，未产出 VRM）', ...SOURCE }, 'unusable.glb', glb, 'model/gltf-binary'),
+    });
+    must(created.status === 201, '上传仅 GLB 的模型', `${created.status} ${JSON.stringify(created.body)}`);
+    const id = created.body.id;
+    must(created.body.format === 'glb', `入库格式为 glb（实际 ${created.body.format}）`);
+    must(created.body.usable === false, '该模型标记为不可用（usable=false）',
+      JSON.stringify(created.body.unusableReason));
+    const approve = await request('POST', `/api/reviews/model/${id}/approve`, {
+      json: { reviewer: 'qa', comment: '通过但不设为默认' },
+    });
+    must(approve.status === 200 || approve.status === 201, '审核通过（不设为默认模型）', String(approve.status));
+    const detail = await request('GET', `/api/models/${id}`);
+    const reason = String(detail.body?.unusableReason ?? '');
+    const drivable = detail.body?.stats?.drivable === true;
+    must(reason.includes('未产出 VRM'), `不可用原因说明"未产出 VRM"：${reason}`);
+    // 归因准确性（T-WEB-017）：骨架已达标时**不得**说"humanoid 不达标"
+    if (drivable) {
+      must(!reason.includes('humanoid 不达标'),
+        `骨架达标（drivable=true，humanoid ${detail.body?.stats?.humanoidMapped}/${detail.body?.stats?.humanoidTotal}）`
+        + `时不得归因于 humanoid：${reason}`);
+    } else {
+      console.log(`    · 该 GLB 的 drivable=false（humanoid ${detail.body?.stats?.humanoidMapped}/`
+        + `${detail.body?.stats?.humanoidTotal}），原因归因于 humanoid 属正确`);
+    }
+    unusable = { id, reason, drivable };
+    rmSync(pmxPath, { force: true });
+    rmSync(glbPath, { force: true });
+  } catch (error) {
+    console.log(`    · 跳过不可用模型场景（${error.message}）—— 需要 unzip 与 ASSIMP_BIN`);
+  }
+
+  // ---------- 边界 B：场景 config 只给最少字段，服务端必须补齐默认 ----------
+  const minimalConfig = { physics: { gravity: { y: -9.8 } } };
+  const minimalScene = await request('POST', '/api/scenes', {
+    form: fileForm(
+      { name: '最简配置场景（只有 gravity）', config: JSON.stringify(minimalConfig), ...SOURCE },
+      'minimal.glb', glbBytes, 'model/gltf-binary',
+    ),
+  });
+  must(minimalScene.status === 201, '上传最简配置场景', `${minimalScene.status} ${JSON.stringify(minimalScene.body)}`);
+  const minimalSceneId = minimalScene.body.id;
+
   // ---------- 审核发布 ----------
-  for (const [kind, id] of [['song', songId], ['motion', motionId], ['model', modelId], ['scene', sceneId]]) {
+  for (const [kind, id] of [['song', songId], ['motion', motionId], ['model', modelId], ['scene', sceneId], ['scene', minimalSceneId]]) {
     // 契约：**上传即 pending**（draft 才需要显式 submit），所以 409「已处于 pending」是正常的
     const submit = await request('POST', `/api/reviews/${kind}/${id}/submit`, { json: { reviewer: 'qa' } });
     must([200, 201, 409].includes(submit.status), `提交审核 ${kind}#${id}`, String(submit.status));
@@ -122,6 +184,31 @@ const run = async () => {
   const data = catalog.body;
   console.log(`  目录：songs=${data.songs?.length} motions=${data.motions?.length} models=${data.models?.length} scenes=${data.scenes?.length}`);
   must(data.scenes?.length >= 1, '目录含场景（④ 的 scenes[]）');
+  // 不可用模型不得进入客户端目录（①），且默认模型不受影响
+  const modelsInCatalog = (catalog.body?.models ?? []);
+  const nonVrm = modelsInCatalog.filter((m) => m.format !== 'vrm');
+  must(nonVrm.length === 0, '目录里的模型全是 VRM（不可用模型不进目录）', JSON.stringify(nonVrm));
+  if (unusable) {
+    must(!modelsInCatalog.some((m) => m.id === unusable.id), `不可用模型 #${unusable.id} 不在目录里`);
+    must(catalog.body?.defaultModelId === modelId,
+      `defaultModelId 仍是可用的 VRM 模型（实际 ${catalog.body?.defaultModelId}，期望 ${modelId}）`);
+  }
+
+  // 最简配置场景：服务端必须补齐默认值（契约 0.5.0 的字段边界）
+  const minimalEntry = (catalog.body?.scenes ?? []).find((s) => s.id === minimalSceneId);
+  must(minimalEntry !== undefined, `最简配置场景 #${minimalSceneId} 在目录里`);
+  const mc = minimalEntry?.config ?? {};
+  must(mc.physics?.gravity?.y === -9.8, `重力保留（${JSON.stringify(mc.physics?.gravity)}）`);
+  must(mc.physics?.colliders === 'auto', `碰撞体补默认 auto（实际 ${mc.physics?.colliders}）`);
+  must(mc.physics?.ground?.friction === 0.6 && mc.physics?.ground?.slopeLimit === 45,
+    `地面补默认 0.6/45°（实际 ${JSON.stringify(mc.physics?.ground)}）`);
+  must(mc.physics?.wind?.gustAmplitude === 0 && mc.physics?.wind?.base?.x === 0,
+    `风补默认（静风）：${JSON.stringify(mc.physics?.wind)}`);
+  must(mc.camera?.mode === 'follow', `相机补默认 follow（实际 ${mc.camera?.mode}）`);
+  must(mc.environment?.ambientIntensity === 1, `环境光补默认 1（实际 ${mc.environment?.ambientIntensity}）`);
+  must(mc.spawnPoints === undefined || mc.spawnPoints.length <= 1,
+    `出生点补默认（最多一条）：${JSON.stringify(mc.spawnPoints)}`);
+
   const version = await request('GET', '/api/catalog/version');
   console.log(`  目录指纹：${JSON.stringify(version.body)}`);
 
@@ -135,6 +222,18 @@ const run = async () => {
     keypointFormat: pre.body?.keypointFormat ?? null,
     catalogRevision: version.body?.revision ?? null,
     contractVersions: health.body?.contractVersion ?? {},
+    unusableModelId: unusable?.id ?? null,
+    unusableDrivable: unusable?.drivable ?? null,
+    minimalSceneId,
+    minimalSceneExpect: {
+      gravityY: -9.8,
+      colliders: 'auto',
+      groundFriction: 0.6,
+      groundSlopeLimit: 45,
+      windCalm: true,
+      cameraMode: 'follow',
+      ambientIntensity: 1,
+    },
   }, null, 2));
   console.log(`\n期望值已写入 ${EXPECT_PATH}`);
 };

tasks/019-cross-end-integration.md

@@ -52,6 +52,32 @@ Web 端的测试只验自己那一侧。**两端各自绿灯 ≠ 契约字段真
 | ③ 动作预览（资产链路） | 动作缩略图 **可下载**且为 PNG |
 | ① 模型交付 | 模型格式 `vrm`、`isPrimary`、模型文件可下载且为 `glTF` 容器、大小与 `fileSize` 一致 |
 
+## 契约边界场景（续，配合 Web v0.7.5）
+
+正常路径之外的**字段边界**同样只在跨端跑起来才会暴露。`seed-catalog.mjs` 与
+`probe-integration.gd` 因此增加两类场景，**两端都断言**：
+
+| 场景 | Web 侧（播种脚本断言） | Windows 侧（包内探针断言） |
+|--|--|--|
+| **不可用模型**：真实 PMX 用 Assimp 转 GLB 后入库（等价"管线只产出 GLB"） | `usable=false`；原因准确（骨架达标时**不得**说"humanoid 不达标"）；**不在** `catalog/export`；`defaultModelId` 不变 | `bundle.models` 里没有任何非 VRM 模型；按 id 找不到该模型；`defaultModelId` 仍指向可用的 VRM |
+| **场景 config 只给最少字段**（`{physics:{gravity:{y:-9.8}}}`） | 服务端补齐默认（碰撞体 `auto`、地面 `0.6/45°`、静风、相机 `follow`、环境光 `1`、出生点 1 条） | 客户端解析出的**同一组默认值**逐项一致 |
+
+实测（Web v0.7.5 × Windows v0.2.5 包内 pck）：
+
+```
+✓ 该模型标记为不可用（usable=false）
+✓ 不可用原因说明"未产出 VRM"：未产出 VRM（格式为 GLB；humanoid 覆盖 19/22 已达标），需重新以 VRM 交付才能进入客户端目录
+✓ 骨架达标（drivable=true，humanoid 19/22）时不得归因于 humanoid
+✓ 目录里的模型全是 VRM（不可用模型不进目录）／✓ 不可用模型 #2 不在客户端目录里
+✓ defaultModelId 仍是可用的 VRM 模型（实际 1，期望 1）
+✓ 最简配置：重力保留 -9.8 ／ 碰撞体补默认 auto ／ 地面默认 0.60 / 45°
+✓ 最简配置：风默认静风（is_calm=true）／ 相机默认 follow ／ 环境光默认 1.0 ／ 出生点 1 条
+```
+
+> 这两类场景的价值在**同一份契约的两侧解释**：Web 认为"不可用"的模型长什么样、
+> 客户端是否真的看不到它；以及"缺字段"时两端的默认值是否逐项一致
+> （服务端补齐 vs 客户端收敛，任一侧不一致都会表现为"配置看起来生效了但行为不对"）。
+
 ## 实测（v0.2.3 包内 pck × 真实 Web v0.7.4 + 真实 MySQL）
 
 ```