# T-WEB-015 场景管理（新增模块）

- **状态**: done
- **依赖**: T-WEB-007（审核流程）
- **文档**: v1.6 §4.12
- **契约**: `rest-api 0.5.0`、`data-models 0.7.0`、`database 0.4.0`

## 目标

新增**场景**这一类资源：客户端跟练时的 3D 环境（GLB）+ 物理参数
（重力 / 风 / 地面 / 碰撞体 / 环境 / 出生点 / 相机）。
服务端**只存参数、不跑物理**，仿真在客户端（Windows 端用 Godot 内置物理）。

## 与模型的区别

| 项 | 模型 | 场景 |
|--|--|--|
| 主力格式 | **VRM**（humanoid 重绑定） | **GLB**（不做重绑定、不转 VRM） |
| 转换 | PMX/FBX/zip → GLB → VRM | `.glb`/`.gltf` 直接导入；`.zip`/`.pmx`/`.fbx` → GLB |
| 附加数据 | 骨骼 / 材质 / 缩略图 | **物理参数** `SceneConfig` |

## 交付物

| 文件 | 说明 |
|--|--|
| `contracts/data-models.md` §7 | `Scene` 与冻结的 `SceneConfig` 结构 |
| `contracts/rest-api.yaml` | `/api/scenes` 增删改查 + 审核复用 `/api/reviews/scene/:id/approve\|reject` + `catalog/export.scenes[]` |
| `migrations/1789650000000-AddScenes.ts` | `scenes` 表；`config` / `stats` 用 **MEDIUMTEXT** |
| `src/scenes/scene-config.ts` | `normalizeSceneConfig()`：缺项默认、越界夹紧、非法枚举回退，**永不抛错** |
| `src/scenes/{scenes.service,scene.serializer,scenes.controller,scenes.module}.ts` | 业务实现（上传一律 `pending`；删除时清理源文件/GLB/缩略图） |
| `src/models/model-inspector.ts` | 场景复用模型检查器做 GLB 分析 |
| `src/models/model-thumbnail.ts` | 场景复用模型光栅化器出缩略图 |
| `admin/src/pages/Scenes.tsx` | 列表 / 上传 / 审核 / 删除 / 物理参数编辑（编辑期即按同一规则夹紧） |
| `admin/src/lib/scene-physics.ts` | 与后端同规则的收敛（保存前就不会产生非法枚举） |

> **MEDIUMTEXT 的原因**：`models.stats` 曾在 TEXT（65,535 字节）上溢出
> （实测 70,980 字节 → MySQL 1406 → 500）。场景的 `stats` 与 `config` 同样可能很大，
> 因此**一开始就用 MEDIUMTEXT**，并保留 `shrinkStatsForStorage()` 兜底。

## 验收

| 验收项 | 结果 |
|--|--|
| 场景可上传（GLB 直传 / zip 自动解包 / PMX 转换） | ✅ 与模型同一套转换管线 |
| 物理参数可在管理端可视化编辑 | ✅ 重力 / 风 / 摩擦 / 弹性 / 碰撞体 / 环境 / 出生点 / 相机 |
| 非法参数不会入库 | ✅ 前后端同规则收敛；`test/scene-config.spec.ts` 9 项边界用例 |
| 客户端能拿到场景 | ✅ `catalog/export.scenes[]`；目录指纹纳入场景变更 |
| 路由与契约一致 | ✅ `check-routes` 共 **35** 条 |

## 缺陷修复记录（v0.7.2）

**缺陷**：`CatalogModule` 的 `imports` 里漏了 `ScenesModule`。

`CatalogService` 因为 `catalog/export` 要下发 `scenes[]` 而注入了 `ScenesService`，
但 Nest 的 DI 是**按模块**解析的 —— 不在同一个模块的 `imports` 里，就解析不到。
后果是 `node dist/main.js` 在 bootstrap 阶段直接抛
`UnknownDependenciesException: Nest can't resolve dependencies of the CatalogService (... ? ...)`，
**服务完全起不来**（v0.7.0 / v0.7.1 的产物都是这样）。

**为什么当时没被发现**：三层检查全都"绿"——

| 检查 | 为什么没抓到 |
|--|--|
| `nest build` / `tsc --noEmit` | 模块 import 缺失是**运行时** DI 问题，类型系统看不出来 |
| 258 项单元测试 | 它们直接 new 服务或测纯函数，**从不编译 `AppModule`** |
| 打包脚本的产物完整性校验 | 只校验文件清单、压缩包结构与 PE/魔数，不启动服务 |

**修复**：在 `CatalogModule.imports` 中补上 `ScenesModule`。

**防线**：新增 `scripts/check-bootstrap.mjs`，以正式部署方式
（`ExecStart=node dist/main.js`、**不带任何 npm 环境变量**、**不需要数据库**）
拉起真实产物，断言①无依赖解析类错误②启动日志里的应用版本等于 `package.json`
③启动确实推进到数据库连接阶段。已挂进 `npm run verify` 与
`scripts/package-release.sh`（构建后、打包前），并做过**反向验证**：
把 `ScenesModule` 删除后该检查立刻失败。