feat(scenes): 场景管理后端 + 契约 0.5.0/0.7.0/0.4.0（T-WEB-015）

契约先行（三端逐字节一致，已同步 windows/android）： - rest-api -> 0.5.0：新增 GET/POST /api/scenes、GET/PATCH/DELETE /api/scenes/{id} - data-models -> 0.7.0：新增 §7 Scene 与 7.1 SceneConfig（物理/环境/出生点/相机） - database -> 0.4.0：新增 scenes 表（config/stats 用 MEDIUMTEXT，迁移可逆）后端： - entities/scene.entity.ts + 迁移 AddScenes1789650000000（scenes 表） - scenes/scene-config.ts：SceneConfig 定义 + 默认值 + **边界收敛**（越界夹紧、非法枚举回退），保证客户端拿到的参数一定可解释；服务端只存参数不跑物理 - scenes/scenes.service.ts：上传（.glb/.gltf 直接导入；.zip/.pmx/.fbx 转 GLB，场景不做 humanoid 重绑定、不转 VRM）、列表/详情/更新/软删除、缩略图复用模型光栅化器、分析复用模型检查器、config 同时接受 JSON 字符串与平铺字段 - scenes/scenes.controller.ts + scenes.module.ts（app.module 注册） - 审核复用 /api/reviews/:type/:id：TargetType.Scene 接入待审列表与状态流转 - catalog/export 增 scenes[]，目录指纹纳入场景变更 - 枚举：TargetType.Scene、AssetKind.Scene / SceneThumbnail 测试：新增 test/scene-config.spec.ts 6 项（默认值/夹紧/枚举回退/出生点上限/颜色/ 序列化）；规模 19 文件 / 243 项；check-routes 35 条一致。版本 0.6.0。注：管理端场景页（GLB 预览 + 物理参数可视化）与 Windows 场景选择留待下一轮。
2026-09-17 00:27:08 +08:00
25 changed files with 1020 additions and 35 deletions
@@ -10,7 +10,15 @@ OpenDance Studio **阶段一**: Web 管理服务端(NestJS + TypeORM + 现有 My

 ## 状态

-**阶段一已完成**: T-WEB-001 -> T-WEB-010 全部落地,当前版本 **v0.5.0**(契约 `rest-api 0.4.0`、`data-models 0.6.0`、`model-formats 0.5.0`、`skeleton-topology 0.2.0`、`database 0.3.0`)。
+**阶段一已完成**: T-WEB-001 -> T-WEB-010 全部落地,当前版本 **v0.6.0**(契约 `rest-api 0.5.0`、`data-models 0.7.0`、`model-formats 0.5.0`、`skeleton-topology 0.2.0`、`database 0.4.0`)。
+
+v0.6.0 修订(**场景管理**,契约 rest-api -> 0.5.0、data-models -> 0.7.0、database -> 0.4.0):
+
+1. **新增场景管理**(T-WEB-015):场景**以 GLB 为主**(不做 humanoid 重绑定、不转 VRM);上传 `.glb/.gltf` 直接导入,`.zip/.pmx/.fbx` 由服务端转 GLB;
+2. **场景物理参数**(`SceneConfig` 冻结在契约 data-models 7.1):重力向量、**风向动态**(基础风 + 阵风幅度/频率/方向/坐标系)、地面摩擦/弹性/坡度、碰撞体来源(auto/mesh/none)、环境光/雾、出生点(≤16)、相机;**服务端只存参数、不跑物理**(仿真在客户端 Godot);
+3. **入库即收敛**:越界夹紧、非法枚举回退默认值,保证客户端拿到的参数一定可解释;`scenes.config`/`stats` 用 MEDIUMTEXT;
+4. **端点**:`GET/POST /api/scenes`、`GET/PATCH/DELETE /api/scenes/{id}`(共 35 条路由,`check-routes` 通过);审核复用 `/api/reviews/scene/:id/approve|reject`(上传一律 `pending`);`catalog/export` 增 `scenes[]` 且指纹纳入场景变更;
+5. 缩略图复用模型光栅化器 + 分析复用模型检查器;新增 6 项测试;规模 **19 文件 / 243 项**。

 v0.5.0 修订(**动作预览**,契约 data-models -> 0.6.0):

@@ -101,15 +109,15 @@ v0.2.0 主要变更:
 3. 取得发布包并校验(地址用你们自己的制品库替换; 下面是本仓库的发布地址)

   ```bash
-   curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.5.0/opendance-web-v0.5.0.tar.gz
-   curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.5.0/SHA256SUMS
+   curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.6.0/opendance-web-v0.6.0.tar.gz
+   curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.6.0/SHA256SUMS
   sha256sum -c SHA256SUMS      # 期望输出 "OK"
   ```

 4. 解压并生成配置(交互式引导,逐项问答,口令不回显)

   ```bash
-   tar -xzf opendance-web-v0.5.0.tar.gz && cd opendance-web-v0.5.0
+   tar -xzf opendance-web-v0.6.0.tar.gz && cd opendance-web-v0.6.0
   bash deploy/init-env.sh
   ```

@@ -179,8 +187,8 @@ FLUSH PRIVILEGES;
 ### 5. 部署步骤

 ```bash
-tar -xzf opendance-web-v0.5.0.tar.gz
-cd opendance-web-v0.5.0
+tar -xzf opendance-web-v0.6.0.tar.gz
+cd opendance-web-v0.6.0
 bash deploy/init-env.sh         # 首次启动引导: 逐项问答生成 deploy/.env(见下)
 bash deploy/install.sh          # 已以 root 登录, 不需要 sudo
 ```
@@ -353,12 +361,12 @@ npm run dev             # http://localhost:5173(/api 与 /health 代理到 3000)
 cd web-server
 npm run contracts:check   # 契约版本一致性
 npm run typecheck         # TypeScript 严格检查
-npm run test              # 237 项单元测试 / 18 个文件(VMD 31、模型压缩包 27、
+npm run test              # 243 项单元测试 / 19 个文件(VMD 31、模型压缩包 27、
                          #   模型检查器 25、缩略图 8、骨骼过滤 8、
                          #   预处理 25、init-env 16、admin-port 16、
                          #   access-log 9、VRM 检查器 6、.env 预检 12、
                          #   Assimp 定位与安装 13、stats 容量与编码 12、
-                          #   缩略图贴图采样 6、MMD 材质对齐 9、模型可用性 5、MMD 骨名重绑定 4、动作预览 8)
+                          #   缩略图贴图采样 6、MMD 材质对齐 9、模型可用性 5、MMD 骨名重绑定 4、动作预览 8、场景管理 6)
 npm run build             # 生产构建
 npm run start:prod &      # 启动
 npm run test:smoke        # 57 项端到端冒烟(需要数据库可连通)
@@ -1,5 +1,5 @@
 ================================================================
-OpenDance Studio -- Web 管理服务端 v0.5.0  使用说明
+OpenDance Studio -- Web 管理服务端 v0.6.0  使用说明
 ================================================================

 本服务端是 OpenDance Studio 三端中的第一端, 负责管理歌曲、VRM 模型与
@@ -8,6 +8,17 @@ OpenDance Studio -- Web 管理服务端 v0.5.0  使用说明
 重要: 本服务端 不部署、不管理 MySQL。数据库为部署方提供的现有实例,
 连接信息通过 .env 注入。

+v0.6.0 修订 - 场景管理(契约 rest-api 0.5.0 / data-models 0.7.0 / database 0.4.0)
+  1. 场景以 GLB 为主(不做 humanoid 重绑定、不转 VRM): .glb/.gltf 直接导入,
+     .zip/.pmx/.fbx 由服务端转 GLB。
+  2. 场景物理参数(SceneConfig, 契约 data-models 7.1): 重力向量、风向动态
+     (基础风 + 阵风幅度/频率/方向/坐标系)、地面摩擦/弹性/坡度、碰撞体来源、
+     环境光/雾、出生点(<=16)、相机; 服务端只存参数不跑物理(仿真在客户端)。
+  3. 入库即收敛: 越界夹紧、非法枚举回退默认; scenes.config/stats 用 MEDIUMTEXT。
+  4. 端点: GET/POST /api/scenes、GET/PATCH/DELETE /api/scenes/{id}(共 35 条路由);
+     审核复用 /api/reviews/scene/:id/approve|reject; catalog/export 增 scenes[]。
+  5. 新增 6 项测试; 规模 19 文件 / 243 项。
+
 v0.5.0 修订 - 动作预览(契约 data-models -> 0.6.0)
  1. 动作骨架缩略图(服务端): motion-thumbnail.ts 把关键点序列画成正视图骨架 PNG,
     随 /preprocess 生成并落库(motions.thumbnail_asset_id, 迁移 AddMotionThumbnail),
@@ -125,11 +136,11 @@ v0.2.1 修订
   2. 准备一个现有的 MySQL / MariaDB 实例, 并建好库与账号(见下方"前置要求")
        本项目不会创建数据库本身
   3. 取得发布包并校验(地址用你们自己的制品库替换)
-        curl -LO https://<制品库地址>/opendance-web-v0.5.0.tar.gz
+        curl -LO https://<制品库地址>/opendance-web-v0.6.0.tar.gz
        curl -LO https://<制品库地址>/SHA256SUMS
        sha256sum -c SHA256SUMS      # 期望输出 "OK"
   4. 解压并生成配置(交互式引导, 逐项问答, 口令不回显)
-        tar -xzf opendance-web-v0.5.0.tar.gz && cd opendance-web-v0.5.0
+        tar -xzf opendance-web-v0.6.0.tar.gz && cd opendance-web-v0.6.0
        bash deploy/init-env.sh
   5. 安装(建用户与目录 -> 装依赖 -> 迁移 -> 注册系统服务 -> 等健康检查)
        bash deploy/install.sh
@@ -187,8 +198,8 @@ v0.2.1 修订
  (本项目不会创建数据库本身, 也不需要 GRANT OPTION / FILE / SUPER 等管理权限)

 部署步骤
-  tar -xzf opendance-web-v0.5.0.tar.gz
-  cd opendance-web-v0.5.0
+  tar -xzf opendance-web-v0.6.0.tar.gz
+  cd opendance-web-v0.6.0
  bash deploy/init-env.sh         # 首次启动引导: 逐项问答生成 deploy/.env(见下)
  bash deploy/install.sh          # 已以 root 登录, 不需要 sudo

@@ -363,12 +374,12 @@ deploy/.env 初始化引导(deploy/init-env.sh)
  cd web-server
  npm run contracts:check   # 契约版本一致性
  npm run typecheck         # TypeScript 严格检查
-  npm run test              # 237 项单元测试 / 18 个文件(VMD 31、模型压缩包 24、
+  npm run test              # 243 项单元测试 / 19 个文件(VMD 31、模型压缩包 24、
                            #   模型检查器 25、缩略图 8、骨骼过滤 8、
                            #   预处理 25、init-env 16、admin-port 16、
                            #   access-log 9、VRM 检查器 6、.env 预检 12、
                            #   Assimp 定位与安装 13、stats 容量与编码 12、缩略图贴图 6、
-                            #   MMD 材质对齐 9、模型可用性 5、MMD 骨名重绑定 4、动作预览 8)
+                            #   MMD 材质对齐 9、模型可用性 5、MMD 骨名重绑定 4、动作预览 8、场景管理 6)
  npm run build             # 生产构建
  npm run start:prod &      # 启动
  npm run test:smoke        # 57 项端到端冒烟(需要数据库可连通)
@@ -1,8 +1,8 @@
 # OpenDance Studio 契约版本
 # 规则：任何字段级变更必须提升对应条目版本，并回到 opendance-web 修改后再向另两端建迁移任务。
-rest-api: 0.4.0
+rest-api: 0.5.0
 websocket-keypoints: 0.1.0
-data-models: 0.6.0
+data-models: 0.7.0
 skeleton-topology: 0.2.0
 model-formats: 0.5.0
-database: 0.3.0
+database: 0.4.0
@@ -83,7 +83,7 @@ rejected   已驳回
 | `durationMs` | number\|null | | |
 | `keypointFormat` | string\|null | 读 | 预处理后固定为 `mediapipe33@0.1.0` |
 | `keypointUrl` | string\|null | 读 | 预处理产物（NDJSON 或.npz 的 JSON 封装） |
-| `thumbnailUrl` | string\|null | 读 | 骨架缩略图（`/preprocess` 时生成，动作管理列表展示；未生成时为 null）(v0.6.0) |
+| `thumbnailUrl` | string\|null | 读 | 骨架缩略图（`/preprocess` 时生成，动作管理列表展示；未生成时为 null）(v0.7.0) |
 | `keypointFrames` | number\|null | 读 | 关键点帧数 |
 | `preprocessState` | enum | 读 | `none` / `running` / `done` / `failed` |
 | `preprocessError` | string\|null | 读 | |
@@ -163,3 +163,48 @@ rejected   已驳回

 - 仅包含 `status = 'published'` 的记录。
 - `defaultModelId` 由 4.1 的规则解析得出，客户端无需自行实现优先级。
+
+---
+
+## 7. `Scene`（场景，GLB 为主）（v0.7.0）
+
+场景与模型的区别：**以 GLB 为主**（不做 humanoid 重绑定、不转 VRM），
+并携带**物理参数**（服务端只存参数、不跑物理；仿真在客户端）。
+
+| 字段 | 类型 | 必填 | 说明 |
+|--|--|--|--|
+| `id` | number | 读 | |
+| `name` | string | ✅ | 场景名称，<=200 |
+| `glbUrl` | string\|null | 读 | 场景 GLB 下载地址 |
+| `thumbnailUrl` | string\|null | 读 | 缩略图（服务端离线渲染） |
+| `fileSize` | number\|null | 读 | |
+| `fileSha256` | string\|null | 读 | |
+| `conversionNote` | string\|null | 读 | 由 `.zip`/`.pmx`/`.fbx` 转换而来时的说明 |
+| `config` | `SceneConfig` | ✅ | 物理 / 环境 / 出生点 / 相机，见 7.1 |
+| `stats` | object\|null | 读 | 场景 GLB 分析（面数 / 网格 / 材质 / warnings） |
+| `sourceType` `sourceName` `sourceUrl` `license` `author` | string | ✅ | 来源五元组 |
+| `status` | enum | 读 | 上传一律 `pending`，经审核后 `published` |
+
+### 7.1 `SceneConfig`（冻结）
+
+```yaml
+physics:
+  gravity: { x: 0, y: -9.8, z: 0 }        # 米/秒^2，各分量 ±200
+  wind:
+    base: { x: 0, y: 0, z: 0 }            # 基础风向量（米/秒，±100）
+    gustAmplitude: 0                       # 阵风幅度 0~100
+    gustFrequency: 0.2                     # 阵风频率 Hz，0.01~5
+    gustDirection: { x: 1, y: 0, z: 0 }    # 阵风方向（±1）
+    space: world | local                   # 风的作用坐标系
+  ground: { friction: 0.6, restitution: 0, slopeLimit: 45 }   # 0~1 / 0~1 / 0~89 度
+  colliders: auto | mesh | none            # auto=按 GLB 命名约定，mesh=三角网
+environment:
+  ambientColor: "#8fb4ff"                  # #RRGGBB
+  ambientIntensity: 1                      # 0~4
+  fogDensity: 0                            # 0~1（0=关闭）
+spawnPoints: [{ x: 0, y: 0, z: 0, yaw: 0 }]   # 最多 16 个
+camera: { mode: follow | fixed | orbit, distance: 4.5, height: 1.6 }
+```
+
+服务端入库时对每项做**边界收敛**（越界夹紧、非法枚举回退默认值），
+保证客户端拿到的参数一定可解释；`catalog/export` 的 `scenes[]` 直接下发该结构。
@@ -36,7 +36,7 @@ DB_LOGGING=false
 - 每个 migration 必须可逆（提供 `down` 方法）
 - 迁移文件名格式：`<timestamp>-<kebab-name>.ts`

-## 增量迁移(v0.2.0 / v0.3.0)
+## 增量迁移(v0.2.0 / v0.4.0)

 | 迁移 | 变更 |
 |--|--|
@@ -63,3 +63,24 @@ draft ──submit──▶ pending ──approve──▶ published

 - `published` 才可被 Windows 客户端 / Android App 消费
 - `/api/catalog/export` 只导出 `published` 记录
+
+---
+
+## 场景表 `scenes`（v0.4.0 / T-WEB-015）
+
+| 列 | 类型 | 说明 |
+|--|--|--|
+| `id` | bigint PK | |
+| `name` | varchar(200) | 场景名称 |
+| `glb_asset_id` | bigint NULL | 场景 GLB（以 GLB 为主，不转 VRM） |
+| `thumbnail_asset_id` | bigint NULL | 缩略图 |
+| `config` | **mediumtext** NULL | `SceneConfig` JSON（物理 / 环境 / 出生点 / 相机） |
+| `stats` | **mediumtext** NULL | 场景 GLB 分析结果（复用模型检查器） |
+| `file_size` / `file_sha256` / `conversion_note` | - | 与 models 同义 |
+| `source_type` `source_name` `source_url` `license` `author` | - | 来源五元组（必填） |
+| `status` | varchar(16) | 上传一律 `pending`，审核后 `published`/`rejected` |
+| `created_at` `updated_at` `deleted_at` | datetime | 软删除 |
+
+* `config` / `stats` 用 **MEDIUMTEXT**（TEXT 的 64KB 上限在 `models.stats` 上踩过坑）；
+* 迁移：`AddScenes1789650000000`（可逆，`down` 为 `DROP TABLE scenes`）；
+* 状态机与审核复用既有约定（审核走 `/api/reviews/scene/:id/approve|reject`）。
@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
  title: OpenDance Studio Web 管理服务端 API
-  version: 0.4.0
+  version: 0.5.0
  description: |
    OpenDance Studio 的唯一数据源与契约权威。
    契约版本见 contracts/VERSION。字段语义见 contracts/data-models.md。
@@ -594,6 +594,70 @@ paths:
                  contractVersion: { type: object, additionalProperties: { type: string } }
                  revision: { type: string, description: 目录内容 sha256，变化即需重新拉取 }

+  /api/scenes:
+    get:
+      tags: [scenes]
+      summary: 场景列表（v0.5.0）
+      parameters:
+        - $ref: '#/components/parameters/Page'
+        - $ref: '#/components/parameters/PageSize'
+        - name: q
+          in: query
+          schema: { type: string }
+          description: 按 name/author 模糊匹配
+        - name: status
+          in: query
+          schema: { type: string, enum: [draft, pending, published, rejected] }
+      responses:
+        '200':
+          description: 分页结果 { items, total, page, pageSize }
+    post:
+      tags: [scenes]
+      summary: 上传场景（multipart：file + name + 来源五元组 + 可选 config）
+      description: |
+        `file` 以 **.glb 为主**（直接导入，不重编码）；`.gltf` 直接导入；
+        `.zip` / `.pmx` / `.fbx` 由服务端转换为 GLB（场景不做 humanoid 重绑定、不转 VRM）。
+        `config` 为 JSON 字符串（或平铺字段 gravity / wind / environment / spawnPoints / camera），
+        含物理参数：重力向量、风向动态（基础风 + 阵风）、地面摩擦/弹性/坡度、碰撞体来源。
+        服务端**只存参数、不跑物理**（仿真在客户端）。上传一律 status=pending。
+      requestBody:
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required: [file, name, sourceType, sourceName, sourceUrl, license, author]
+              properties:
+                file: { type: string, format: binary }
+                name: { type: string }
+                config: { type: string, description: SceneConfig 的 JSON 字符串 }
+                sourceType: { type: string }
+                sourceName: { type: string }
+                sourceUrl: { type: string }
+                license: { type: string }
+                author: { type: string }
+      responses:
+        '201':
+          description: 已入库（pending）
+  /api/scenes/{id}:
+    parameters: [{ $ref: '#/components/parameters/Id' }]
+    get:
+      tags: [scenes]
+      summary: 场景详情
+      responses:
+        '200': { description: Scene }
+        '404': { description: 不存在 }
+    patch:
+      tags: [scenes]
+      summary: 更新场景名称 / 物理参数（状态变更走 /api/reviews）
+      responses:
+        '200': { description: Scene }
+        '400': { description: 参数非法或试图直接改状态 }
+    delete:
+      tags: [scenes]
+      summary: 删除场景（软删除）
+      responses:
+        '204': { description: 已删除 }
+
 components:
  parameters:
    Id:
@@ -1,5 +1,5 @@
 project: opendance-web-server
-version: 0.5.0
+version: 0.6.0
 repository: opendance-web
 default_branch: main
 contracts_version: 0.4.0
@@ -60,13 +60,13 @@ tasks:
    status: done

 deliverable:
-  artifact: opendance-web-v0.5.0.tar.gz
+  artifact: opendance-web-v0.6.0.tar.gz
  packaging: Linux 业务服务（系统服务托管，双端口：软件 API + 管理端，不含 MySQL、不含反向代理、不使用 Docker）
  includes:
    - web-server/          # NestJS 源码 + 构建产物（含 BVH / VMD 内置解析、ZIP 读取与模型压缩包转换）
    - admin/               # React 管理端构建产物
    - deploy/              # install.sh / init-env.sh / systemd / openrc / initd / ctl.sh / .env.example（PORT、ADMIN_PORT、HOST）
    - deploy/proxy/        # 反向代理说明（nginx / IIS，仅供参考不部署）
-    - contracts/           # 当前版本契约快照（data-models 0.6.0）
+    - contracts/           # 当前版本契约快照（rest-api 0.5.0 / data-models 0.7.0 / database 0.4.0）
    - THIRD_PARTY.md       # 开源声明
    - README.txt           # 使用说明
@@ -1,6 +1,6 @@
 #!/bin/bash
 # ============================================================
-# 打包发布产物：opendance-web-v0.5.0.tar.gz
+# 打包发布产物：opendance-web-v0.6.0.tar.gz
 #
 # 产物结构（Linux 业务服务部署，不使用 Docker、不部署反向代理）：
 #   web-server/      NestJS 源码 + 构建产物
@@ -21,7 +21,7 @@ set -euo pipefail
 REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 cd "$REPO_ROOT"

-VERSION="${1:-0.5.0}"
+VERSION="${1:-0.6.0}"
 NAME="opendance-web-v${VERSION}"
 OUT_DIR="$REPO_ROOT/dist-release"
 STAGE="$OUT_DIR/$NAME"
@@ -1,7 +1,7 @@
 {
  "name": "opendance-admin",
  "private": true,
-  "version": "0.5.0",
+  "version": "0.6.0",
  "type": "module",
  "description": "OpenDance Studio 管理端（React + TypeScript + Vite）",
  "scripts": {
@@ -1,6 +1,6 @@
 {
  "name": "opendance-web-server",
-  "version": "0.5.0",
+  "version": "0.6.0",
  "description": "OpenDance Studio Web 管理服务端（NestJS + TypeORM + 现有 MySQL 实例）",
  "license": "MIT",
  "private": true,
@@ -9,6 +9,7 @@ import { ModelsModule } from './models/models.module';
 import { MotionsModule } from './motions/motions.module';
 import { PreprocessModule } from './preprocess/preprocess.module';
 import { ReviewsModule } from './reviews/reviews.module';
+import { ScenesModule } from './scenes/scenes.module';
 import { SongsModule } from './songs/songs.module';
 import { StorageModule } from './storage/storage.module';

@@ -39,6 +40,7 @@ import { StorageModule } from './storage/storage.module';

    StorageModule,
    HealthModule,
+    ScenesModule,
    SongsModule,
    MotionsModule,
    ModelsModule,
@@ -12,6 +12,8 @@ import { ModelsService } from '../models/models.service';
 import { MotionDto } from '../motions/motion.serializer';
 import { MotionsService } from '../motions/motions.service';
 import { SongDto } from '../songs/song.serializer';
+import { ScenesService } from '../scenes/scenes.service';
+import type { SceneDto } from '../scenes/scene.serializer';
 import { SongsService } from '../songs/songs.service';

 export interface CatalogBundle {
@@ -20,6 +22,8 @@ export interface CatalogBundle {
  songs: SongDto[];
  motions: MotionDto[];
  models: ModelDto[];
+  /** 已发布场景（含物理参数）；契约 data-models 0.7.0 */
+  scenes: SceneDto[];
  defaultModelId: number | null;
 }

@@ -36,6 +40,7 @@ export class CatalogService {
    private readonly songsService: SongsService,
    private readonly motionsService: MotionsService,
    private readonly modelsService: ModelsService,
+    private readonly scenesService: ScenesService,
    private readonly config: AppConfig,
  ) {}

@@ -50,10 +55,11 @@ export class CatalogService {
      }),
    ]);

-    const [songDtos, motionDtos, modelDtos, defaultModelId] = await Promise.all([
+    const [songDtos, motionDtos, modelDtos, sceneDtos, defaultModelId] = await Promise.all([
      this.songsService.toDtos(songs),
      this.motionsService.toDtos(motions),
      this.modelsService.toDtos(models),
+      this.scenesService.published(),
      this.modelsService.resolveDefaultModelId(),
    ]);

@@ -63,6 +69,7 @@ export class CatalogService {
      songs: songDtos,
      motions: motionDtos,
      models: modelDtos,
+      scenes: sceneDtos,
      defaultModelId,
    };
  }
@@ -72,7 +79,7 @@ export class CatalogService {
   * 指纹只覆盖影响客户端行为的字段。
   */
  async version(): Promise<{ contractVersion: Record<string, string>; revision: string; generatedAt: string }> {
-    const [songs, motions, models] = await Promise.all([
+    const [songs, motions, models, scenes] = await Promise.all([
      this.songs.find({ where: { status: PublishStatus.Published }, order: { id: 'ASC' } }),
      this.motions.find({ where: { status: PublishStatus.Published }, order: { id: 'ASC' } }),
      // v0.5.0：只交付**已产出 VRM** 的模型（usable），未产出 VRM 的不进入客户端目录
@@ -80,6 +87,7 @@ export class CatalogService {
        where: { status: PublishStatus.Published, format: ModelFormat.Vrm },
        order: { id: 'ASC' },
      }),
+      this.scenesService.published(),
    ]);

    const fingerprint = JSON.stringify({
@@ -94,6 +102,7 @@ export class CatalogService {
        m.preprocessState,
      ]),
      models: models.map((m) => [m.id, m.name, m.format, m.isPrimary, m.updatedAt.toISOString(), m.fileAssetId]),
+      scenes: scenes.map((s) => [s.id, s.name, s.updatedAt, s.glbUrl, s.status]),
    });

    return {
@@ -60,6 +60,8 @@ export enum TargetType {
  Song = 'song',
  Motion = 'motion',
  Model = 'model',
+  /** 场景（T-WEB-015） */
+  Scene = 'scene',
 }

 export enum AssetKind {
@@ -72,6 +74,10 @@ export enum AssetKind {
  Thumbnail = 'thumbnail',
  /** 动作关键点序列的骨架缩略图（T-WEB-014） */
  MotionThumbnail = 'motion-thumbnail',
+  /** 场景 GLB（T-WEB-015） */
+  Scene = 'scene',
+  /** 场景缩略图 */
+  SceneThumbnail = 'scene-thumbnail',
  Keypoints = 'keypoints',
 }

@@ -9,12 +9,12 @@ import { join } from 'node:path';
 *  未设置该变量时回落到这里的常量）。
 */
 export const CONTRACT_VERSIONS: Readonly<Record<string, string>> = Object.freeze({
-  'rest-api': '0.4.0',
+  'rest-api': '0.5.0',
  'websocket-keypoints': '0.1.0',
-  'data-models': '0.6.0',
+  'data-models': '0.7.0',
  'skeleton-topology': '0.2.0',
  'model-formats': '0.5.0',
-  database: '0.3.0',
+  database: '0.4.0',
 });

 /** 解析 `contracts/VERSION`（`key: value` 每行一条，`#` 起注释） */
@@ -0,0 +1,95 @@
+import {
+  Column,
+  CreateDateColumn,
+  DeleteDateColumn,
+  Entity,
+  Index,
+  PrimaryGeneratedColumn,
+  UpdateDateColumn,
+} from 'typeorm';
+import { bigintNumber } from '../common/transformers';
+import { PublishStatus, SourceType } from '../common/enums';
+import type { SceneConfig } from '../scenes/scene-config';
+
+/** JSON 文本列（MEDIUMTEXT）：TEXT 的 64KB 上限在模型 stats 上已经踩过坑 */
+const jsonText = {
+  to: (value: unknown): string | null => (value === null || value === undefined ? null : JSON.stringify(value)),
+  from: (value: string | null): unknown => {
+    if (value === null || value === undefined || value === '') return null;
+    try {
+      return JSON.parse(value);
+    } catch {
+      return null;
+    }
+  },
+};
+
+/**
+ * 场景 —— 契约 data-models.md §7（T-WEB-015）。
+ *
+ * **以 GLB 为主**（与模型区分：场景不做 humanoid 重绑定、不转 VRM）；
+ * `config` 存物理/环境/出生点/相机参数（重力、风向动态等），
+ * **服务端只存参数不跑物理**，仿真在客户端（Godot 内置物理）。
+ */
+@Entity('scenes')
+@Index('idx_scenes_status', ['status'])
+export class Scene {
+  @PrimaryGeneratedColumn({ type: 'bigint' })
+  id!: number;
+
+  @Column({ type: 'varchar', length: 200 })
+  name!: string;
+
+  /** 场景 GLB 资产 */
+  @Column({ name: 'glb_asset_id', type: 'bigint', nullable: true, transformer: bigintNumber })
+  glbAssetId!: number | null;
+
+  @Column({ name: 'thumbnail_asset_id', type: 'bigint', nullable: true, transformer: bigintNumber })
+  thumbnailAssetId!: number | null;
+
+  /** 物理 / 环境 / 出生点 / 相机（见 scenes/scene-config.ts） */
+  @Column({ name: 'config', type: 'mediumtext', nullable: true, transformer: jsonText })
+  config!: SceneConfig | null;
+
+  /** 场景 GLB 的分析结果（面数 / 网格 / 材质 / warnings，复用模型检查器） */
+  @Column({ name: 'stats', type: 'mediumtext', nullable: true, transformer: jsonText })
+  stats!: Record<string, unknown> | null;
+
+  @Column({ name: 'file_size', type: 'bigint', nullable: true, transformer: bigintNumber })
+  fileSize!: number | null;
+
+  @Column({ name: 'file_sha256', type: 'varchar', length: 64, nullable: true })
+  fileSha256!: string | null;
+
+  /** 由 `.zip` / `.pmx` / `.fbx` 转换而来时的说明 */
+  @Column({ name: 'conversion_note', type: 'varchar', length: 500, nullable: true })
+  conversionNote!: string | null;
+
+  // ---- 来源五元组（必填）----
+  @Column({ name: 'source_type', type: 'varchar', length: 32 })
+  sourceType!: SourceType;
+
+  @Column({ name: 'source_name', type: 'varchar', length: 200 })
+  sourceName!: string;
+
+  @Column({ name: 'source_url', type: 'varchar', length: 500 })
+  sourceUrl!: string;
+
+  @Column({ type: 'varchar', length: 100 })
+  license!: string;
+
+  @Column({ type: 'varchar', length: 200 })
+  author!: string;
+
+  @Column({ type: 'varchar', length: 16, default: PublishStatus.Pending })
+  status!: PublishStatus;
+
+  @CreateDateColumn({ name: 'created_at', type: 'datetime' })
+  createdAt!: Date;
+
+  @UpdateDateColumn({ name: 'updated_at', type: 'datetime' })
+  updatedAt!: Date;
+
+  @DeleteDateColumn({ name: 'deleted_at', type: 'datetime', nullable: true })
+  deletedAt!: Date | null;
+}
@@ -0,0 +1,43 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * 场景管理（T-WEB-015，契约 database 0.4.0 / data-models 0.7.0）。
+ *
+ * 场景以 **GLB 为主**：`glb_asset_id` 指向存储里的场景文件；
+ * `config` 存物理参数（重力 / 风向动态 / 地面 / 碰撞体）与环境、出生点、相机；
+ * `stats` 复用模型检查器的分析结果。服务端**只存参数、不跑物理**。
+ */
+export class AddScenes1789650000000 implements MigrationInterface {
+    name = 'AddScenes1789650000000'
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`
+            CREATE TABLE \`scenes\` (
+                \`id\` bigint NOT NULL AUTO_INCREMENT,
+                \`name\` varchar(200) NOT NULL,
+                \`glb_asset_id\` bigint NULL,
+                \`thumbnail_asset_id\` bigint NULL,
+                \`config\` mediumtext NULL,
+                \`stats\` mediumtext NULL,
+                \`file_size\` bigint NULL,
+                \`file_sha256\` varchar(64) NULL,
+                \`conversion_note\` varchar(500) NULL,
+                \`source_type\` varchar(32) NOT NULL,
+                \`source_name\` varchar(200) NOT NULL,
+                \`source_url\` varchar(500) NOT NULL,
+                \`license\` varchar(100) NOT NULL,
+                \`author\` varchar(200) NOT NULL,
+                \`status\` varchar(16) NOT NULL DEFAULT 'pending',
+                \`created_at\` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
+                \`updated_at\` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+                \`deleted_at\` datetime NULL,
+                INDEX \`idx_scenes_status\` (\`status\`),
+                PRIMARY KEY (\`id\`)
+            ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+        `);
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`DROP TABLE \`scenes\``);
+    }
+}
@@ -1,3 +1,4 @@
+import { Scene } from '../entities/scene.entity';
 import { Module } from '@nestjs/common';
 import { TypeOrmModule } from '@nestjs/typeorm';
 import { ModelsModule } from '../models/models.module';
@@ -9,7 +10,7 @@ import { ReviewsController } from './reviews.controller';
 import { ReviewsService } from './reviews.service';

@Module({
-  imports: [TypeOrmModule.forFeature([ReviewRecord, Song, Motion, CharacterModel]), ModelsModule],
+  imports: [TypeOrmModule.forFeature([Scene, ReviewRecord, Song, Motion, CharacterModel]), ModelsModule],
  controllers: [ReviewsController],
  providers: [ReviewsService],
  exports: [ReviewsService],
@@ -19,6 +19,7 @@ import { Paged, toPaged } from '../common/pagination';
 import { CharacterModel } from '../entities/model.entity';
 import { Motion } from '../entities/motion.entity';
 import { ReviewRecord } from '../entities/review-record.entity';
+import { Scene } from '../entities/scene.entity';
 import { Song } from '../entities/song.entity';
 import { QueryReviewDto, ReviewActionDto } from './review.dto';

@@ -68,6 +69,7 @@ export class ReviewsService {
    @InjectRepository(Song) private readonly songs: Repository<Song>,
    @InjectRepository(Motion) private readonly motions: Repository<Motion>,
    @InjectRepository(CharacterModel) private readonly models: Repository<CharacterModel>,
+    @InjectRepository(Scene) private readonly scenes: Repository<Scene>,
    private readonly modelsService: ModelsService,
  ) {}

@@ -84,15 +86,17 @@ export class ReviewsService {
  async listByStatus(status: PublishStatus, query: QueryReviewDto): Promise<Paged<PendingItemDto>> {
    const rows: PendingItemDto[] = [];

-    const [songs, motions, models] = await Promise.all([
+    const [songs, motions, models, scenes] = await Promise.all([
      this.songs.find({ where: { status } }),
      this.motions.find({ where: { status } }),
      this.models.find({ where: { status } }),
+      this.scenes.find({ where: { status } }),
    ]);

    rows.push(...songs.map((s) => toPending(TargetType.Song, s, s.title)));
    rows.push(...motions.map((m) => toPending(TargetType.Motion, m, m.name)));
    rows.push(...models.map((m) => toPending(TargetType.Model, m, m.name)));
+    rows.push(...scenes.map((s) => toPending(TargetType.Scene, s, s.name)));

    rows.sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : -1));
    const total = rows.length;
@@ -133,6 +137,14 @@ export class ReviewsService {
        save = () => this.motions.save(motion);
        break;
      }
+      case TargetType.Scene: {
+        const scene = await this.scenes.findOne({ where: { id } });
+        if (!scene) throw new NotFoundException(`场景 #${id} 不存在`);
+        entity = scene;
+        name = scene.name;
+        save = () => this.scenes.save(scene);
+        break;
+      }
      case TargetType.Model: {
        const model = await this.models.findOne({ where: { id } });
        if (!model) throw new NotFoundException(`模型 #${id} 不存在`);
@@ -0,0 +1,163 @@
+/**
+ * 场景物理与环境的配置定义（T-WEB-015）。
+ *
+ * 职责划分：**服务端只存参数、不跑物理**；仿真在客户端（Windows 端用 Godot 内置物理：
+ * RigidBody3D / Area3D 风场 / PhysicsServer3D）。因此这里只做
+ * "结构校验 + 默认值 + 边界收敛"，保证下发给客户端的参数一定可解释。
+ */
+
+export interface Vec3 {
+  x: number;
+  y: number;
+  z: number;
+}
+
+/** 风：基础风 + 阵风（正弦叠加） */
+export interface WindConfig {
+  base: Vec3;
+  /** 阵风幅度（米/秒，0 表示无阵风；上限 100） */
+  gustAmplitude: number;
+  /** 阵风频率（Hz，0.01~5） */
+  gustFrequency: number;
+  /** 阵风方向（上限 ±1） */
+  gustDirection: Vec3;
+  /** 世界坐标 or 场景局部坐标 */
+  space: 'world' | 'local';
+}
+
+export interface GroundConfig {
+  /** 摩擦系数 0~1 */
+  friction: number;
+  /** 弹性 0~1 */
+  restitution: number;
+  /** 可行走坡度上限（度）0~89 */
+  slopeLimit: number;
+}
+
+export interface EnvironmentConfig {
+  /** 环境光颜色（#RRGGBB） */
+  ambientColor: string;
+  /** 环境光强度 0~4 */
+  ambientIntensity: number;
+  /** 雾浓度 0~1（0 = 关闭） */
+  fogDensity: number;
+}
+
+export interface SpawnPoint {
+  x: number;
+  y: number;
+  z: number;
+  /** 朝向（度，绕 Y 轴） */
+  yaw: number;
+}
+
+export interface CameraConfig {
+  mode: 'follow' | 'fixed' | 'orbit';
+  distance: number;
+  height: number;
+}
+
+export interface SceneConfig {
+  physics: {
+    /** 重力向量（米/秒^2），默认 (0,-9.8,0) */
+    gravity: Vec3;
+    wind: WindConfig;
+    ground: GroundConfig;
+    /** 碰撞体来源：auto（按 GLB 命名约定）| mesh（三角网）| none */
+    colliders: 'auto' | 'mesh' | 'none';
+  };
+  environment: EnvironmentConfig;
+  spawnPoints: SpawnPoint[];
+  camera: CameraConfig;
+}
+
+export const SCENE_CONFIG_DEFAULTS: SceneConfig = {
+  physics: {
+    gravity: { x: 0, y: -9.8, z: 0 },
+    wind: {
+      base: { x: 0, y: 0, z: 0 },
+      gustAmplitude: 0,
+      gustFrequency: 0.2,
+      gustDirection: { x: 1, y: 0, z: 0 },
+      space: 'world',
+    },
+    ground: { friction: 0.6, restitution: 0, slopeLimit: 45 },
+    colliders: 'auto',
+  },
+  environment: { ambientColor: '#8fb4ff', ambientIntensity: 1, fogDensity: 0 },
+  spawnPoints: [{ x: 0, y: 0, z: 0, yaw: 0 }],
+  camera: { mode: 'follow', distance: 4.5, height: 1.6 },
+};
+
+function num(value: unknown, fallback: number, min: number, max: number): number {
+  const parsed = typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+  return Math.min(max, Math.max(min, parsed));
+}
+
+function vec3(value: unknown, fallback: Vec3, limit = 1000): Vec3 {
+  const raw = (value ?? {}) as Partial<Vec3>;
+  return {
+    x: num(raw.x, fallback.x, -limit, limit),
+    y: num(raw.y, fallback.y, -limit, limit),
+    z: num(raw.z, fallback.z, -limit, limit),
+  };
+}
+
+function hexColor(value: unknown, fallback: string): string {
+  return typeof value === 'string' && /^#[0-9a-fA-F]{6}$/.test(value) ? value.toLowerCase() : fallback;
+}
+
+/**
+ * 把任意输入收敛成合法 `SceneConfig`：缺项用默认值、越界夹紧、非法枚举回退。
+ * **永不抛错** —— 保证客户端拿到的参数一定可解释。
+ */
+export function normalizeSceneConfig(input: unknown): SceneConfig {
+  const raw = (input ?? {}) as Partial<SceneConfig>;
+  const physics = (raw.physics ?? {}) as Partial<SceneConfig['physics']>;
+  const wind = (physics.wind ?? {}) as Partial<WindConfig>;
+  const ground = (physics.ground ?? {}) as Partial<GroundConfig>;
+  const environment = (raw.environment ?? {}) as Partial<EnvironmentConfig>;
+  const camera = (raw.camera ?? {}) as Partial<CameraConfig>;
+  const defaults = SCENE_CONFIG_DEFAULTS;
+  const spawnPoints = Array.isArray(raw.spawnPoints) && raw.spawnPoints.length > 0
+    ? raw.spawnPoints
+    : defaults.spawnPoints;
+
+  return {
+    physics: {
+      gravity: vec3(physics.gravity, defaults.physics.gravity, 200),
+      wind: {
+        base: vec3(wind.base, defaults.physics.wind.base, 100),
+        gustAmplitude: num(wind.gustAmplitude, defaults.physics.wind.gustAmplitude, 0, 100),
+        gustFrequency: num(wind.gustFrequency, defaults.physics.wind.gustFrequency, 0.01, 5),
+        gustDirection: vec3(wind.gustDirection, defaults.physics.wind.gustDirection, 1),
+        space: wind.space === 'local' ? 'local' : 'world',
+      },
+      ground: {
+        friction: num(ground.friction, defaults.physics.ground.friction, 0, 1),
+        restitution: num(ground.restitution, defaults.physics.ground.restitution, 0, 1),
+        slopeLimit: num(ground.slopeLimit, defaults.physics.ground.slopeLimit, 0, 89),
+      },
+      colliders: physics.colliders === 'mesh' || physics.colliders === 'none' ? physics.colliders : 'auto',
+    },
+    environment: {
+      ambientColor: hexColor(environment.ambientColor, defaults.environment.ambientColor),
+      ambientIntensity: num(environment.ambientIntensity, defaults.environment.ambientIntensity, 0, 4),
+      fogDensity: num(environment.fogDensity, defaults.environment.fogDensity, 0, 1),
+    },
+    spawnPoints: spawnPoints.slice(0, 16).map((point) => {
+      const item = (point ?? {}) as Partial<SpawnPoint>;
+      return {
+        x: num(item.x, 0, -1000, 1000),
+        y: num(item.y, 0, -1000, 1000),
+        z: num(item.z, 0, -1000, 1000),
+        yaw: num(item.yaw, 0, -360, 360),
+      };
+    }),
+    camera: {
+      mode: camera.mode === 'fixed' || camera.mode === 'orbit' ? camera.mode : defaults.camera.mode,
+      distance: num(camera.distance, defaults.camera.distance, 0.5, 50),
+      height: num(camera.height, defaults.camera.height, 0, 20),
+    },
+  };
+}
@@ -0,0 +1,52 @@
+import { PublishStatus, SourceType } from '../common/enums';
+import { Scene } from '../entities/scene.entity';
+import type { SceneConfig } from './scene-config';
+
+/** 契约 data-models.md §7 的对外表示 */
+export interface SceneDto {
+  id: number;
+  name: string;
+  glbUrl: string | null;
+  thumbnailUrl: string | null;
+  fileSize: number | null;
+  fileSha256: string | null;
+  conversionNote: string | null;
+  /** 物理 / 环境 / 出生点 / 相机（服务端只存参数，仿真在客户端） */
+  config: SceneConfig | null;
+  stats: Record<string, unknown> | null;
+  sourceType: SourceType;
+  sourceName: string;
+  sourceUrl: string;
+  license: string;
+  author: string;
+  status: PublishStatus;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface SceneUrlLookup {
+  glbUrl: string | null;
+  thumbnailUrl: string | null;
+}
+
+export function toSceneDto(scene: Scene, urls: SceneUrlLookup): SceneDto {
+  return {
+    id: scene.id,
+    name: scene.name,
+    glbUrl: urls.glbUrl,
+    thumbnailUrl: urls.thumbnailUrl,
+    fileSize: scene.fileSize ?? null,
+    fileSha256: scene.fileSha256 ?? null,
+    conversionNote: scene.conversionNote ?? null,
+    config: scene.config ?? null,
+    stats: scene.stats ?? null,
+    sourceType: scene.sourceType,
+    sourceName: scene.sourceName,
+    sourceUrl: scene.sourceUrl,
+    license: scene.license,
+    author: scene.author,
+    status: scene.status,
+    createdAt: scene.createdAt.toISOString(),
+    updatedAt: scene.updatedAt.toISOString(),
+  };
+}
@@ -0,0 +1,68 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  HttpCode,
+  HttpStatus,
+  Param,
+  ParseIntPipe,
+  Patch,
+  Post,
+  Query,
+  UploadedFile,
+  UseInterceptors,
+} from '@nestjs/common';
+import { FileInterceptor } from '@nestjs/platform-express';
+import { ScenesService, type UploadedSceneFile } from './scenes.service';
+import type { SceneDto } from './scene.serializer';
+
+/** 场景管理（T-WEB-015）：契约 rest-api.yaml /api/scenes */
+@Controller('api/scenes')
+export class ScenesController {
+  constructor(private readonly scenes: ScenesService) {}
+
+  @Get()
+  list(
+    @Query('q') q?: string,
+    @Query('status') status?: string,
+    @Query('page') page?: string,
+    @Query('pageSize') pageSize?: string,
+  ): Promise<{ items: SceneDto[]; total: number; page: number; pageSize: number }> {
+    return this.scenes.list({
+      q,
+      status,
+      page: page ? Number(page) : undefined,
+      pageSize: pageSize ? Number(pageSize) : undefined,
+    });
+  }
+
+  /** 上传场景：multipart，`file`（.glb 为主）+ 名称 + 来源五元组 + 可选 config(JSON) */
+  @Post()
+  @UseInterceptors(FileInterceptor('file'))
+  create(
+    @Body() body: Record<string, unknown>,
+    @UploadedFile() file: UploadedSceneFile | undefined,
+  ): Promise<SceneDto> {
+    return this.scenes.create(body, file);
+  }
+
+  @Get(':id')
+  detail(@Param('id', ParseIntPipe) id: number): Promise<SceneDto> {
+    return this.scenes.findOne(id);
+  }
+
+  @Patch(':id')
+  update(
+    @Param('id', ParseIntPipe) id: number,
+    @Body() body: Record<string, unknown>,
+  ): Promise<SceneDto> {
+    return this.scenes.update(id, body);
+  }
+
+  @Delete(':id')
+  @HttpCode(HttpStatus.NO_CONTENT)
+  async remove(@Param('id', ParseIntPipe) id: number): Promise<void> {
+    await this.scenes.remove(id);
+  }
+}
@@ -0,0 +1,14 @@
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { Scene } from '../entities/scene.entity';
+import { StorageModule } from '../storage/storage.module';
+import { ScenesController } from './scenes.controller';
+import { ScenesService } from './scenes.service';
+
+@Module({
+  imports: [TypeOrmModule.forFeature([Scene]), StorageModule],
+  controllers: [ScenesController],
+  providers: [ScenesService],
+  exports: [ScenesService],
+})
+export class ScenesModule {}
@@ -0,0 +1,262 @@
+import { BadRequestException, Injectable, Logger, NotFoundException } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { existsSync } from 'node:fs';
+import { Repository } from 'typeorm';
+import { AssetKind, ModelFormat, PublishStatus } from '../common/enums';
+import { assertSourceTupleComplete, type SourceTuple } from '../common/source.dto';
+import { AppConfig } from '../config/configuration';
+import { Scene } from '../entities/scene.entity';
+import { convertModelArchive, convertModelFile } from '../models/model-convert';
+import { inspectModelFile } from '../models/model-inspector';
+import { renderModelThumbnail } from '../models/model-thumbnail';
+import { StorageService } from '../storage/storage.service';
+import { normalizeSceneConfig, SCENE_CONFIG_DEFAULTS, type SceneConfig } from './scene-config';
+import { type SceneDto, toSceneDto } from './scene.serializer';
+
+export interface UploadedSceneFile {
+  buffer: Buffer;
+  originalname: string;
+  size: number;
+  mimetype?: string;
+}
+
+const SUPPORTED_DIRECT = new Set(['.glb', '.gltf']);
+
+function extOf(name: string): string {
+  const index = name.lastIndexOf('.');
+  return index >= 0 ? name.slice(index).toLowerCase() : '';
+}
+
+/**
+ * 场景管理（T-WEB-015）。
+ *
+ * 与模型管理的差异（契约 model-formats 1.1 / data-models §7）：
+ *   * 场景**以 GLB 为主**，不做 humanoid 重绑定、不转 VRM；
+ *   * 场景携带**物理参数**（重力 / 风向动态 / 地面 / 碰撞体）与环境、出生点、相机；
+ *   * 服务端**只存参数、不跑物理**：仿真在客户端（Godot 内置物理）。
+ */
+@Injectable()
+export class ScenesService {
+  private readonly logger = new Logger(ScenesService.name);
+
+  constructor(
+    @InjectRepository(Scene) private readonly scenes: Repository<Scene>,
+    private readonly storage: StorageService,
+    private readonly config: AppConfig,
+  ) {}
+
+  async create(body: Record<string, unknown>, file: UploadedSceneFile | undefined): Promise<SceneDto> {
+    if (!file || !file.buffer || file.buffer.length === 0) {
+      throw new BadRequestException('上传场景必须带 file 字段（.glb 为主，也接受 .gltf/.zip/.fbx/.pmx）');
+    }
+    const name = typeof body.name === 'string' && body.name.trim().length > 0 ? body.name.trim() : '';
+    if (name.length === 0) throw new BadRequestException('场景名称 name 必填');
+    const tuple = assertSourceTupleComplete({
+      sourceType: body.sourceType as SourceTuple['sourceType'],
+      sourceName: body.sourceName as string,
+      sourceUrl: body.sourceUrl as string,
+      license: body.license as string,
+      author: body.author as string,
+    });
+    if (!tuple) {
+      throw new BadRequestException('上传场景必须填写完整的来源信息（sourceType/sourceName/sourceUrl/license/author）');
+    }
+
+    const parsed = this.parseConfigInput(body);
+    const ext = extOf(file.originalname || '');
+    let buffer: Buffer;
+    let conversionNote: string;
+
+    if (SUPPORTED_DIRECT.has(ext)) {
+      // 场景主力格式：GLB 直接导入（不重编码）
+      buffer = file.buffer;
+      conversionNote = `直接导入（${ext.slice(1).toUpperCase()}，未做重编码）`;
+    } else {
+      // 其余格式统一转 GLB（场景不做 VRM）
+      try {
+        const converted =
+          ext === '.zip'
+            ? await convertModelArchive(file.buffer, {
+                assimpBin: this.config.assimpBin,
+                timeoutMs: this.config.modelConvertTimeoutMs,
+                preferFormat: 'glb',
+              })
+            : await convertModelFile(file.buffer, file.originalname, {
+                assimpBin: this.config.assimpBin,
+                timeoutMs: this.config.modelConvertTimeoutMs,
+                preferFormat: 'glb',
+              });
+        buffer = converted.buffer;
+        conversionNote = converted.note.slice(0, 500);
+      } catch (error) {
+        throw new BadRequestException(
+          `场景转换失败（${ext || '未知扩展名'}）：${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    }
+
+    const stored = await this.storage.persistBuffer(
+      AssetKind.Scene,
+      buffer,
+      file.originalname || `scene-${Date.now()}.glb`,
+      'model/gltf-binary',
+    );
+
+    const absolutePath = this.storage.absolutePath(stored.asset);
+    const stats = await this.inspectSafely(absolutePath, buffer.length, name);
+    const thumbnailAssetId = await this.thumbnailSafely(absolutePath);
+
+    const scene = this.scenes.create({
+      name,
+      glbAssetId: stored.asset.id,
+      thumbnailAssetId,
+      config: parsed,
+      stats: stats as unknown as Record<string, unknown>,
+      fileSize: stored.asset.size,
+      fileSha256: stored.asset.sha256,
+      conversionNote,
+      sourceType: tuple.sourceType as Scene['sourceType'],
+      sourceName: tuple.sourceName,
+      sourceUrl: tuple.sourceUrl,
+      license: tuple.license,
+      author: tuple.author,
+      // 与模型/动作一致：上传一律待审核
+      status: PublishStatus.Pending,
+    });
+    const saved = await this.scenes.save(scene);
+    this.logger.log(
+      `场景已入库待审：#${saved.id} ${name}（${file.originalname}，${conversionNote}）` +
+        ` 重力=(${parsed.physics.gravity.x},${parsed.physics.gravity.y},${parsed.physics.gravity.z})`,
+    );
+    const [dto] = await this.toDtos([saved]);
+    return dto;
+  }
+
+  /** 场景配置：既接受 `config` JSON 字符串（multipart 常用），也接受平铺字段 */
+  private parseConfigInput(body: Record<string, unknown>): SceneConfig {
+    const raw = body.config;
+    if (typeof raw === 'string' && raw.trim().length > 0) {
+      try {
+        return normalizeSceneConfig(JSON.parse(raw));
+      } catch {
+        throw new BadRequestException('config 不是合法的 JSON');
+      }
+    }
+    if (raw && typeof raw === 'object') return normalizeSceneConfig(raw);
+    if (body.gravity || body.wind || body.environment || body.spawnPoints || body.camera) {
+      return normalizeSceneConfig({
+        physics: { gravity: body.gravity, wind: body.wind },
+        environment: body.environment,
+        spawnPoints: body.spawnPoints,
+        camera: body.camera,
+      });
+    }
+    return SCENE_CONFIG_DEFAULTS;
+  }
+
+  private async inspectSafely(
+    absolutePath: string,
+    fileSize: number,
+    name: string,
+  ): Promise<Record<string, unknown> | null> {
+    try {
+      return (await inspectModelFile(absolutePath, fileSize)) as unknown as Record<string, unknown>;
+    } catch (error) {
+      this.logger.warn(`场景「${name}」分析失败：${error instanceof Error ? error.message : String(error)}`);
+      return null;
+    }
+  }
+
+  private async thumbnailSafely(absolutePath: string): Promise<number | null> {
+    try {
+      const rendered = await renderModelThumbnail(absolutePath, { size: 512 });
+      if (!rendered) return null;
+      const stored = await this.storage.persistBuffer(
+        AssetKind.SceneThumbnail,
+        rendered.png,
+        `scene-thumb-${Date.now()}.png`,
+        'image/png',
+      );
+      return stored.asset.id;
+    } catch (error) {
+      this.logger.warn(`场景缩略图生成失败：${error instanceof Error ? error.message : String(error)}`);
+      return null;
+    }
+  }
+
+  async list(query: {
+    q?: string;
+    status?: string;
+    page?: number;
+    pageSize?: number;
+  }): Promise<{ items: SceneDto[]; total: number; page: number; pageSize: number }> {
+    const page = Math.max(1, Math.floor(query.page ?? 1));
+    const pageSize = Math.min(100, Math.max(1, Math.floor(query.pageSize ?? 20)));
+    const qb = this.scenes.createQueryBuilder('s');
+    if (query.q) {
+      qb.andWhere('(s.name LIKE :q OR s.author LIKE :q)', { q: `%${query.q}%` });
+    }
+    if (query.status) qb.andWhere('s.status = :status', { status: query.status });
+    qb.orderBy('s.id', 'DESC').skip((page - 1) * pageSize).take(pageSize);
+    const [rows, total] = await qb.getManyAndCount();
+    return { items: await this.toDtos(rows), total, page, pageSize };
+  }
+
+  async findOne(id: number): Promise<SceneDto> {
+    const scene = await this.getEntity(id);
+    const [dto] = await this.toDtos([scene]);
+    return dto;
+  }
+
+  async update(id: number, body: Record<string, unknown>): Promise<SceneDto> {
+    const scene = await this.getEntity(id);
+    if (typeof body.name === 'string' && body.name.trim().length > 0) scene.name = body.name.trim();
+    if (body.config !== undefined || body.gravity || body.wind || body.environment) {
+      scene.config = this.parseConfigInput(body);
+    }
+    if (typeof body.status === 'string' && body.status !== scene.status) {
+      throw new BadRequestException('状态变更请走 /api/reviews 接口（上传一律待审核）');
+    }
+    const saved = await this.scenes.save(scene);
+    const [dto] = await this.toDtos([saved]);
+    return dto;
+  }
+
+  /** 软删除（与歌曲一致：保留数据，客户端目录按 status 过滤） */
+  async remove(id: number): Promise<void> {
+    const scene = await this.getEntity(id);
+    await this.scenes.softRemove(scene);
+  }
+
+  async getEntity(id: number): Promise<Scene> {
+    const scene = await this.scenes.findOne({ where: { id } });
+    if (!scene) throw new NotFoundException(`场景 #${id} 不存在`);
+    return scene;
+  }
+
+  async toDtos(rows: Scene[]): Promise<SceneDto[]> {
+    const assets = await this.storage.findMany(
+      rows.flatMap((row) => [row.glbAssetId, row.thumbnailAssetId]),
+    );
+    return rows.map((row) => {
+      const glb = row.glbAssetId ? assets.get(row.glbAssetId) : undefined;
+      const thumbnail = row.thumbnailAssetId ? assets.get(row.thumbnailAssetId) : undefined;
+      if (glb && !existsSync(this.storage.absolutePath(glb))) {
+        this.logger.warn(`场景 #${row.id} 的 GLB 在存储中不存在：${this.storage.absolutePath(glb)}`);
+      }
+      return toSceneDto(row, {
+        glbUrl: glb ? this.storage.url(glb) : null,
+        thumbnailUrl: thumbnail ? this.storage.url(thumbnail) : null,
+      });
+    });
+  }
+
+  /** 供 catalog 使用：已发布场景（含物理参数） */
+  async published(): Promise<SceneDto[]> {
+    const rows = await this.scenes.find({
+      where: { status: PublishStatus.Published },
+      order: { id: 'ASC' },
+    });
+    return this.toDtos(rows);
+  }
+}
@@ -76,6 +76,7 @@ describe('目录导出只含可用模型', () => {
    };
    const songsService = { toDtos: vi.fn().mockResolvedValue([]) };
    const motionsService = { toDtos: vi.fn().mockResolvedValue([]) };
+    const scenesService = { published: vi.fn().mockResolvedValue([]) };
    const modelsService = {
      toDtos: vi.fn().mockImplementation((rows: CharacterModel[]) =>
        rows.map((row) => toModelDto(row, { fileUrl: '/f', thumbnailUrl: null })),
@@ -90,6 +91,7 @@ describe('目录导出只含可用模型', () => {
      songsService as never,
      motionsService as never,
      modelsService as never,
+      scenesService as never,
      config as never,
    );
  }
@@ -0,0 +1,107 @@
+import { describe, expect, it } from 'vitest';
+
+import { normalizeSceneConfig, SCENE_CONFIG_DEFAULTS } from '../src/scenes/scene-config';
+import { toSceneDto } from '../src/scenes/scene.serializer';
+import { PublishStatus, SourceType } from '../src/common/enums';
+import type { Scene } from '../src/entities/scene.entity';
+
+/**
+ * 场景物理参数（T-WEB-015）。
+ *
+ * 服务端**只存参数、不跑物理**，所以这里锁两件事：
+ *   1. 越界/非法输入一律被收敛成可解释的值（客户端拿到就一定能用）；
+ *   2. 缺省即 `SCENE_CONFIG_DEFAULTS`（重力 -9.8 等），且序列化结构稳定。
+ */
+describe('SceneConfig 归一化', () => {
+  it('空输入 -> 默认值（重力 -9.8、无风、跟随相机）', () => {
+    const config = normalizeSceneConfig(undefined);
+    expect(config).toEqual(SCENE_CONFIG_DEFAULTS);
+    expect(config.physics.gravity).toEqual({ x: 0, y: -9.8, z: 0 });
+    expect(config.physics.wind.gustAmplitude).toBe(0);
+    expect(config.camera.mode).toBe('follow');
+  });
+
+  it('越界数值被夹紧（重力 ±200、摩擦 0~1、频率 0.01~5、雾 0~1）', () => {
+    const config = normalizeSceneConfig({
+      physics: {
+        gravity: { x: 9999, y: -9999, z: 0 },
+        wind: { base: { x: 500, y: 0, z: 0 }, gustAmplitude: 999, gustFrequency: 99 },
+        ground: { friction: 5, restitution: -1, slopeLimit: 120 },
+      },
+      environment: { ambientIntensity: 99, fogDensity: 9 },
+      camera: { distance: 999, height: -5 },
+    });
+    expect(config.physics.gravity.x).toBe(200);
+    expect(config.physics.gravity.y).toBe(-200);
+    expect(config.physics.wind.base.x).toBe(100);
+    expect(config.physics.wind.gustAmplitude).toBe(100);
+    expect(config.physics.wind.gustFrequency).toBe(5);
+    expect(config.physics.ground.friction).toBe(1);
+    expect(config.physics.ground.restitution).toBe(0);
+    expect(config.physics.ground.slopeLimit).toBe(89);
+    expect(config.environment.ambientIntensity).toBe(4);
+    expect(config.environment.fogDensity).toBe(1);
+    expect(config.camera.distance).toBe(50);
+    expect(config.camera.height).toBe(0);
+  });
+
+  it('非法枚举回退默认；风坐标系只认 local/world', () => {
+    const config = normalizeSceneConfig({
+      physics: { colliders: 'banana', wind: { space: 'space' } },
+      camera: { mode: 'fly' },
+      environment: { ambientColor: 'red' },
+    });
+    expect(config.physics.colliders).toBe('auto');
+    expect(config.physics.wind.space).toBe('world');
+    expect(config.camera.mode).toBe('follow');
+    expect(config.environment.ambientColor).toBe(SCENE_CONFIG_DEFAULTS.environment.ambientColor);
+
+    const local = normalizeSceneConfig({ physics: { colliders: 'mesh', wind: { space: 'local' } } });
+    expect(local.physics.colliders).toBe('mesh');
+    expect(local.physics.wind.space).toBe('local');
+  });
+
+  it('出生点最多 16 个，坐标与朝向被夹紧', () => {
+    const many = Array.from({ length: 40 }, () => ({ x: 1e9, y: 0, z: 0, yaw: 1e9 }));
+    const config = normalizeSceneConfig({ spawnPoints: many });
+    expect(config.spawnPoints.length).toBe(16);
+    expect(config.spawnPoints[0].x).toBe(1000);
+    expect(config.spawnPoints[0].yaw).toBe(360);
+  });
+
+  it('合法 #RRGGBB 颜色被接受并小写化', () => {
+    const config = normalizeSceneConfig({ environment: { ambientColor: '#AABBCC' } });
+    expect(config.environment.ambientColor).toBe('#aabbcc');
+  });
+});
+
+describe('SceneDto 序列化', () => {
+  it('带出 config 与来源五元组；URL 由调用方注入', () => {
+    const scene = {
+      id: 3,
+      name: '黄昏广场',
+      glbAssetId: 11,
+      thumbnailAssetId: 12,
+      config: normalizeSceneConfig({ physics: { gravity: { x: 0, y: -3.5, z: 0 } } }),
+      stats: { triangles: 1234 },
+      fileSize: 456,
+      fileSha256: 'abc',
+      conversionNote: '直接导入（GLB，未做重编码）',
+      sourceType: SourceType.Other,
+      sourceName: 'x',
+      sourceUrl: 'y',
+      license: 'z',
+      author: 'a',
+      status: PublishStatus.Pending,
+      createdAt: new Date('2026-01-01T00:00:00Z'),
+      updatedAt: new Date('2026-01-02T00:00:00Z'),
+    } as unknown as Scene;
+    const dto = toSceneDto(scene, { glbUrl: '/static/scene/x.glb', thumbnailUrl: '/static/scene/x.png' });
+    expect(dto.id).toBe(3);
+    expect(dto.glbUrl).toBe('/static/scene/x.glb');
+    expect(dto.config?.physics.gravity.y).toBe(-3.5);
+    expect(dto.stats).toEqual({ triangles: 1234 });
+    expect(dto.status).toBe(PublishStatus.Pending);
+    expect(dto.createdAt).toBe('2026-01-01T00:00:00.000Z');
+  });
+});