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:
@@ -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[]` 直接下发该结构。
|
||||
|
||||
Reference in New Issue
Block a user