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 场景选择留待下一轮。
This commit is contained in:
opendance
2026-09-17 00:27:08 +08:00
parent aad60cbd2e
commit 584b7eaca9
25 changed files with 1020 additions and 35 deletions
+65 -1
View File
@@ -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: