Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 opendance
|
584b7eaca9 |
@@ -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):
|
v0.5.0 修订(**动作预览**,契约 data-models -> 0.6.0):
|
||||||
|
|
||||||
@@ -101,15 +109,15 @@ v0.2.0 主要变更:
|
|||||||
3. 取得发布包并校验(地址用你们自己的制品库替换; 下面是本仓库的发布地址)
|
3. 取得发布包并校验(地址用你们自己的制品库替换; 下面是本仓库的发布地址)
|
||||||
|
|
||||||
```bash
|
```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.6.0/opendance-web-v0.6.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/SHA256SUMS
|
||||||
sha256sum -c SHA256SUMS # 期望输出 "OK"
|
sha256sum -c SHA256SUMS # 期望输出 "OK"
|
||||||
```
|
```
|
||||||
|
|
||||||
4. 解压并生成配置(交互式引导,逐项问答,口令不回显)
|
4. 解压并生成配置(交互式引导,逐项问答,口令不回显)
|
||||||
|
|
||||||
```bash
|
```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
|
bash deploy/init-env.sh
|
||||||
```
|
```
|
||||||
|
|
||||||
@@ -179,8 +187,8 @@ FLUSH PRIVILEGES;
|
|||||||
### 5. 部署步骤
|
### 5. 部署步骤
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
tar -xzf opendance-web-v0.5.0.tar.gz
|
tar -xzf opendance-web-v0.6.0.tar.gz
|
||||||
cd opendance-web-v0.5.0
|
cd opendance-web-v0.6.0
|
||||||
bash deploy/init-env.sh # 首次启动引导: 逐项问答生成 deploy/.env(见下)
|
bash deploy/init-env.sh # 首次启动引导: 逐项问答生成 deploy/.env(见下)
|
||||||
bash deploy/install.sh # 已以 root 登录, 不需要 sudo
|
bash deploy/install.sh # 已以 root 登录, 不需要 sudo
|
||||||
```
|
```
|
||||||
@@ -353,12 +361,12 @@ npm run dev # http://localhost:5173(/api 与 /health 代理到 3000)
|
|||||||
cd web-server
|
cd web-server
|
||||||
npm run contracts:check # 契约版本一致性
|
npm run contracts:check # 契约版本一致性
|
||||||
npm run typecheck # TypeScript 严格检查
|
npm run typecheck # TypeScript 严格检查
|
||||||
npm run test # 237 项单元测试 / 18 个文件(VMD 31、模型压缩包 27、
|
npm run test # 243 项单元测试 / 19 个文件(VMD 31、模型压缩包 27、
|
||||||
# 模型检查器 25、缩略图 8、骨骼过滤 8、
|
# 模型检查器 25、缩略图 8、骨骼过滤 8、
|
||||||
# 预处理 25、init-env 16、admin-port 16、
|
# 预处理 25、init-env 16、admin-port 16、
|
||||||
# access-log 9、VRM 检查器 6、.env 预检 12、
|
# access-log 9、VRM 检查器 6、.env 预检 12、
|
||||||
# Assimp 定位与安装 13、stats 容量与编码 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 build # 生产构建
|
||||||
npm run start:prod & # 启动
|
npm run start:prod & # 启动
|
||||||
npm run test:smoke # 57 项端到端冒烟(需要数据库可连通)
|
npm run test:smoke # 57 项端到端冒烟(需要数据库可连通)
|
||||||
|
|||||||
+18
-7
@@ -1,5 +1,5 @@
|
|||||||
================================================================
|
================================================================
|
||||||
OpenDance Studio -- Web 管理服务端 v0.5.0 使用说明
|
OpenDance Studio -- Web 管理服务端 v0.6.0 使用说明
|
||||||
================================================================
|
================================================================
|
||||||
|
|
||||||
本服务端是 OpenDance Studio 三端中的第一端, 负责管理歌曲、VRM 模型与
|
本服务端是 OpenDance Studio 三端中的第一端, 负责管理歌曲、VRM 模型与
|
||||||
@@ -8,6 +8,17 @@ OpenDance Studio -- Web 管理服务端 v0.5.0 使用说明
|
|||||||
重要: 本服务端 不部署、不管理 MySQL。数据库为部署方提供的现有实例,
|
重要: 本服务端 不部署、不管理 MySQL。数据库为部署方提供的现有实例,
|
||||||
连接信息通过 .env 注入。
|
连接信息通过 .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)
|
v0.5.0 修订 - 动作预览(契约 data-models -> 0.6.0)
|
||||||
1. 动作骨架缩略图(服务端): motion-thumbnail.ts 把关键点序列画成正视图骨架 PNG,
|
1. 动作骨架缩略图(服务端): motion-thumbnail.ts 把关键点序列画成正视图骨架 PNG,
|
||||||
随 /preprocess 生成并落库(motions.thumbnail_asset_id, 迁移 AddMotionThumbnail),
|
随 /preprocess 生成并落库(motions.thumbnail_asset_id, 迁移 AddMotionThumbnail),
|
||||||
@@ -125,11 +136,11 @@ v0.2.1 修订
|
|||||||
2. 准备一个现有的 MySQL / MariaDB 实例, 并建好库与账号(见下方"前置要求")
|
2. 准备一个现有的 MySQL / MariaDB 实例, 并建好库与账号(见下方"前置要求")
|
||||||
本项目不会创建数据库本身
|
本项目不会创建数据库本身
|
||||||
3. 取得发布包并校验(地址用你们自己的制品库替换)
|
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
|
curl -LO https://<制品库地址>/SHA256SUMS
|
||||||
sha256sum -c SHA256SUMS # 期望输出 "OK"
|
sha256sum -c SHA256SUMS # 期望输出 "OK"
|
||||||
4. 解压并生成配置(交互式引导, 逐项问答, 口令不回显)
|
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
|
bash deploy/init-env.sh
|
||||||
5. 安装(建用户与目录 -> 装依赖 -> 迁移 -> 注册系统服务 -> 等健康检查)
|
5. 安装(建用户与目录 -> 装依赖 -> 迁移 -> 注册系统服务 -> 等健康检查)
|
||||||
bash deploy/install.sh
|
bash deploy/install.sh
|
||||||
@@ -187,8 +198,8 @@ v0.2.1 修订
|
|||||||
(本项目不会创建数据库本身, 也不需要 GRANT OPTION / FILE / SUPER 等管理权限)
|
(本项目不会创建数据库本身, 也不需要 GRANT OPTION / FILE / SUPER 等管理权限)
|
||||||
|
|
||||||
部署步骤
|
部署步骤
|
||||||
tar -xzf opendance-web-v0.5.0.tar.gz
|
tar -xzf opendance-web-v0.6.0.tar.gz
|
||||||
cd opendance-web-v0.5.0
|
cd opendance-web-v0.6.0
|
||||||
bash deploy/init-env.sh # 首次启动引导: 逐项问答生成 deploy/.env(见下)
|
bash deploy/init-env.sh # 首次启动引导: 逐项问答生成 deploy/.env(见下)
|
||||||
bash deploy/install.sh # 已以 root 登录, 不需要 sudo
|
bash deploy/install.sh # 已以 root 登录, 不需要 sudo
|
||||||
|
|
||||||
@@ -363,12 +374,12 @@ deploy/.env 初始化引导(deploy/init-env.sh)
|
|||||||
cd web-server
|
cd web-server
|
||||||
npm run contracts:check # 契约版本一致性
|
npm run contracts:check # 契约版本一致性
|
||||||
npm run typecheck # TypeScript 严格检查
|
npm run typecheck # TypeScript 严格检查
|
||||||
npm run test # 237 项单元测试 / 18 个文件(VMD 31、模型压缩包 24、
|
npm run test # 243 项单元测试 / 19 个文件(VMD 31、模型压缩包 24、
|
||||||
# 模型检查器 25、缩略图 8、骨骼过滤 8、
|
# 模型检查器 25、缩略图 8、骨骼过滤 8、
|
||||||
# 预处理 25、init-env 16、admin-port 16、
|
# 预处理 25、init-env 16、admin-port 16、
|
||||||
# access-log 9、VRM 检查器 6、.env 预检 12、
|
# access-log 9、VRM 检查器 6、.env 预检 12、
|
||||||
# Assimp 定位与安装 13、stats 容量与编码 12、缩略图贴图 6、
|
# Assimp 定位与安装 13、stats 容量与编码 12、缩略图贴图 6、
|
||||||
# MMD 材质对齐 9、模型可用性 5、MMD 骨名重绑定 4、动作预览 8)
|
# MMD 材质对齐 9、模型可用性 5、MMD 骨名重绑定 4、动作预览 8、场景管理 6)
|
||||||
npm run build # 生产构建
|
npm run build # 生产构建
|
||||||
npm run start:prod & # 启动
|
npm run start:prod & # 启动
|
||||||
npm run test:smoke # 57 项端到端冒烟(需要数据库可连通)
|
npm run test:smoke # 57 项端到端冒烟(需要数据库可连通)
|
||||||
|
|||||||
+3
-3
@@ -1,8 +1,8 @@
|
|||||||
# OpenDance Studio 契约版本
|
# OpenDance Studio 契约版本
|
||||||
# 规则：任何字段级变更必须提升对应条目版本，并回到 opendance-web 修改后再向另两端建迁移任务。
|
# 规则：任何字段级变更必须提升对应条目版本，并回到 opendance-web 修改后再向另两端建迁移任务。
|
||||||
rest-api: 0.4.0
|
rest-api: 0.5.0
|
||||||
websocket-keypoints: 0.1.0
|
websocket-keypoints: 0.1.0
|
||||||
data-models: 0.6.0
|
data-models: 0.7.0
|
||||||
skeleton-topology: 0.2.0
|
skeleton-topology: 0.2.0
|
||||||
model-formats: 0.5.0
|
model-formats: 0.5.0
|
||||||
database: 0.3.0
|
database: 0.4.0
|
||||||
|
|||||||
@@ -83,7 +83,7 @@ rejected 已驳回
|
|||||||
| `durationMs` | number\|null | | |
|
| `durationMs` | number\|null | | |
|
||||||
| `keypointFormat` | string\|null | 读 | 预处理后固定为 `mediapipe33@0.1.0` |
|
| `keypointFormat` | string\|null | 读 | 预处理后固定为 `mediapipe33@0.1.0` |
|
||||||
| `keypointUrl` | string\|null | 读 | 预处理产物（NDJSON 或.npz 的 JSON 封装） |
|
| `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 | 读 | 关键点帧数 |
|
| `keypointFrames` | number\|null | 读 | 关键点帧数 |
|
||||||
| `preprocessState` | enum | 读 | `none` / `running` / `done` / `failed` |
|
| `preprocessState` | enum | 读 | `none` / `running` / `done` / `failed` |
|
||||||
| `preprocessError` | string\|null | 读 | |
|
| `preprocessError` | string\|null | 读 | |
|
||||||
@@ -163,3 +163,48 @@ rejected 已驳回
|
|||||||
|
|
||||||
- 仅包含 `status = 'published'` 的记录。
|
- 仅包含 `status = 'published'` 的记录。
|
||||||
- `defaultModelId` 由 4.1 的规则解析得出，客户端无需自行实现优先级。
|
- `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[]` 直接下发该结构。
|
||||||
|
|||||||
+22
-1
@@ -36,7 +36,7 @@ DB_LOGGING=false
|
|||||||
- 每个 migration 必须可逆（提供 `down` 方法）
|
- 每个 migration 必须可逆（提供 `down` 方法）
|
||||||
- 迁移文件名格式：`<timestamp>-<kebab-name>.ts`
|
- 迁移文件名格式：`<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 消费
|
- `published` 才可被 Windows 客户端 / Android App 消费
|
||||||
- `/api/catalog/export` 只导出 `published` 记录
|
- `/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`）。
|
||||||
|
|||||||
+65
-1
@@ -1,7 +1,7 @@
|
|||||||
openapi: 3.0.3
|
openapi: 3.0.3
|
||||||
info:
|
info:
|
||||||
title: OpenDance Studio Web 管理服务端 API
|
title: OpenDance Studio Web 管理服务端 API
|
||||||
version: 0.4.0
|
version: 0.5.0
|
||||||
description: |
|
description: |
|
||||||
OpenDance Studio 的唯一数据源与契约权威。
|
OpenDance Studio 的唯一数据源与契约权威。
|
||||||
契约版本见 contracts/VERSION。字段语义见 contracts/data-models.md。
|
契约版本见 contracts/VERSION。字段语义见 contracts/data-models.md。
|
||||||
@@ -594,6 +594,70 @@ paths:
|
|||||||
contractVersion: { type: object, additionalProperties: { type: string } }
|
contractVersion: { type: object, additionalProperties: { type: string } }
|
||||||
revision: { type: string, description: 目录内容 sha256，变化即需重新拉取 }
|
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:
|
components:
|
||||||
parameters:
|
parameters:
|
||||||
Id:
|
Id:
|
||||||
|
|||||||
+3
-3
@@ -1,5 +1,5 @@
|
|||||||
project: opendance-web-server
|
project: opendance-web-server
|
||||||
version: 0.5.0
|
version: 0.6.0
|
||||||
repository: opendance-web
|
repository: opendance-web
|
||||||
default_branch: main
|
default_branch: main
|
||||||
contracts_version: 0.4.0
|
contracts_version: 0.4.0
|
||||||
@@ -60,13 +60,13 @@ tasks:
|
|||||||
status: done
|
status: done
|
||||||
|
|
||||||
deliverable:
|
deliverable:
|
||||||
artifact: opendance-web-v0.5.0.tar.gz
|
artifact: opendance-web-v0.6.0.tar.gz
|
||||||
packaging: Linux 业务服务（系统服务托管，双端口：软件 API + 管理端，不含 MySQL、不含反向代理、不使用 Docker）
|
packaging: Linux 业务服务（系统服务托管，双端口：软件 API + 管理端，不含 MySQL、不含反向代理、不使用 Docker）
|
||||||
includes:
|
includes:
|
||||||
- web-server/ # NestJS 源码 + 构建产物（含 BVH / VMD 内置解析、ZIP 读取与模型压缩包转换）
|
- web-server/ # NestJS 源码 + 构建产物（含 BVH / VMD 内置解析、ZIP 读取与模型压缩包转换）
|
||||||
- admin/ # React 管理端构建产物
|
- admin/ # React 管理端构建产物
|
||||||
- deploy/ # install.sh / init-env.sh / systemd / openrc / initd / ctl.sh / .env.example（PORT、ADMIN_PORT、HOST）
|
- deploy/ # install.sh / init-env.sh / systemd / openrc / initd / ctl.sh / .env.example（PORT、ADMIN_PORT、HOST）
|
||||||
- deploy/proxy/ # 反向代理说明（nginx / IIS，仅供参考不部署）
|
- 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 # 开源声明
|
- THIRD_PARTY.md # 开源声明
|
||||||
- README.txt # 使用说明
|
- README.txt # 使用说明
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
#!/bin/bash
|
#!/bin/bash
|
||||||
# ============================================================
|
# ============================================================
|
||||||
# 打包发布产物：opendance-web-v0.5.0.tar.gz
|
# 打包发布产物：opendance-web-v0.6.0.tar.gz
|
||||||
#
|
#
|
||||||
# 产物结构（Linux 业务服务部署，不使用 Docker、不部署反向代理）：
|
# 产物结构（Linux 业务服务部署，不使用 Docker、不部署反向代理）：
|
||||||
# web-server/ NestJS 源码 + 构建产物
|
# web-server/ NestJS 源码 + 构建产物
|
||||||
@@ -21,7 +21,7 @@ set -euo pipefail
|
|||||||
REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
|
REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
|
||||||
cd "$REPO_ROOT"
|
cd "$REPO_ROOT"
|
||||||
|
|
||||||
VERSION="${1:-0.5.0}"
|
VERSION="${1:-0.6.0}"
|
||||||
NAME="opendance-web-v${VERSION}"
|
NAME="opendance-web-v${VERSION}"
|
||||||
OUT_DIR="$REPO_ROOT/dist-release"
|
OUT_DIR="$REPO_ROOT/dist-release"
|
||||||
STAGE="$OUT_DIR/$NAME"
|
STAGE="$OUT_DIR/$NAME"
|
||||||
|
|||||||
@@ -1,7 +1,7 @@
|
|||||||
{
|
{
|
||||||
"name": "opendance-admin",
|
"name": "opendance-admin",
|
||||||
"private": true,
|
"private": true,
|
||||||
"version": "0.5.0",
|
"version": "0.6.0",
|
||||||
"type": "module",
|
"type": "module",
|
||||||
"description": "OpenDance Studio 管理端（React + TypeScript + Vite）",
|
"description": "OpenDance Studio 管理端（React + TypeScript + Vite）",
|
||||||
"scripts": {
|
"scripts": {
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
{
|
{
|
||||||
"name": "opendance-web-server",
|
"name": "opendance-web-server",
|
||||||
"version": "0.5.0",
|
"version": "0.6.0",
|
||||||
"description": "OpenDance Studio Web 管理服务端（NestJS + TypeORM + 现有 MySQL 实例）",
|
"description": "OpenDance Studio Web 管理服务端（NestJS + TypeORM + 现有 MySQL 实例）",
|
||||||
"license": "MIT",
|
"license": "MIT",
|
||||||
"private": true,
|
"private": true,
|
||||||
|
|||||||
@@ -9,6 +9,7 @@ import { ModelsModule } from './models/models.module';
|
|||||||
import { MotionsModule } from './motions/motions.module';
|
import { MotionsModule } from './motions/motions.module';
|
||||||
import { PreprocessModule } from './preprocess/preprocess.module';
|
import { PreprocessModule } from './preprocess/preprocess.module';
|
||||||
import { ReviewsModule } from './reviews/reviews.module';
|
import { ReviewsModule } from './reviews/reviews.module';
|
||||||
|
import { ScenesModule } from './scenes/scenes.module';
|
||||||
import { SongsModule } from './songs/songs.module';
|
import { SongsModule } from './songs/songs.module';
|
||||||
import { StorageModule } from './storage/storage.module';
|
import { StorageModule } from './storage/storage.module';
|
||||||
|
|
||||||
@@ -39,6 +40,7 @@ import { StorageModule } from './storage/storage.module';
|
|||||||
|
|
||||||
StorageModule,
|
StorageModule,
|
||||||
HealthModule,
|
HealthModule,
|
||||||
|
ScenesModule,
|
||||||
SongsModule,
|
SongsModule,
|
||||||
MotionsModule,
|
MotionsModule,
|
||||||
ModelsModule,
|
ModelsModule,
|
||||||
|
|||||||
@@ -12,6 +12,8 @@ import { ModelsService } from '../models/models.service';
|
|||||||
import { MotionDto } from '../motions/motion.serializer';
|
import { MotionDto } from '../motions/motion.serializer';
|
||||||
import { MotionsService } from '../motions/motions.service';
|
import { MotionsService } from '../motions/motions.service';
|
||||||
import { SongDto } from '../songs/song.serializer';
|
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';
|
import { SongsService } from '../songs/songs.service';
|
||||||
|
|
||||||
export interface CatalogBundle {
|
export interface CatalogBundle {
|
||||||
@@ -20,6 +22,8 @@ export interface CatalogBundle {
|
|||||||
songs: SongDto[];
|
songs: SongDto[];
|
||||||
motions: MotionDto[];
|
motions: MotionDto[];
|
||||||
models: ModelDto[];
|
models: ModelDto[];
|
||||||
|
/** 已发布场景（含物理参数）；契约 data-models 0.7.0 */
|
||||||
|
scenes: SceneDto[];
|
||||||
defaultModelId: number | null;
|
defaultModelId: number | null;
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -36,6 +40,7 @@ export class CatalogService {
|
|||||||
private readonly songsService: SongsService,
|
private readonly songsService: SongsService,
|
||||||
private readonly motionsService: MotionsService,
|
private readonly motionsService: MotionsService,
|
||||||
private readonly modelsService: ModelsService,
|
private readonly modelsService: ModelsService,
|
||||||
|
private readonly scenesService: ScenesService,
|
||||||
private readonly config: AppConfig,
|
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.songsService.toDtos(songs),
|
||||||
this.motionsService.toDtos(motions),
|
this.motionsService.toDtos(motions),
|
||||||
this.modelsService.toDtos(models),
|
this.modelsService.toDtos(models),
|
||||||
|
this.scenesService.published(),
|
||||||
this.modelsService.resolveDefaultModelId(),
|
this.modelsService.resolveDefaultModelId(),
|
||||||
]);
|
]);
|
||||||
|
|
||||||
@@ -63,6 +69,7 @@ export class CatalogService {
|
|||||||
songs: songDtos,
|
songs: songDtos,
|
||||||
motions: motionDtos,
|
motions: motionDtos,
|
||||||
models: modelDtos,
|
models: modelDtos,
|
||||||
|
scenes: sceneDtos,
|
||||||
defaultModelId,
|
defaultModelId,
|
||||||
};
|
};
|
||||||
}
|
}
|
||||||
@@ -72,7 +79,7 @@ export class CatalogService {
|
|||||||
* 指纹只覆盖影响客户端行为的字段。
|
* 指纹只覆盖影响客户端行为的字段。
|
||||||
*/
|
*/
|
||||||
async version(): Promise<{ contractVersion: Record<string, string>; revision: string; generatedAt: string }> {
|
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.songs.find({ where: { status: PublishStatus.Published }, order: { id: 'ASC' } }),
|
||||||
this.motions.find({ where: { status: PublishStatus.Published }, order: { id: 'ASC' } }),
|
this.motions.find({ where: { status: PublishStatus.Published }, order: { id: 'ASC' } }),
|
||||||
// v0.5.0：只交付**已产出 VRM** 的模型（usable），未产出 VRM 的不进入客户端目录
|
// v0.5.0：只交付**已产出 VRM** 的模型（usable），未产出 VRM 的不进入客户端目录
|
||||||
@@ -80,6 +87,7 @@ export class CatalogService {
|
|||||||
where: { status: PublishStatus.Published, format: ModelFormat.Vrm },
|
where: { status: PublishStatus.Published, format: ModelFormat.Vrm },
|
||||||
order: { id: 'ASC' },
|
order: { id: 'ASC' },
|
||||||
}),
|
}),
|
||||||
|
this.scenesService.published(),
|
||||||
]);
|
]);
|
||||||
|
|
||||||
const fingerprint = JSON.stringify({
|
const fingerprint = JSON.stringify({
|
||||||
@@ -94,6 +102,7 @@ export class CatalogService {
|
|||||||
m.preprocessState,
|
m.preprocessState,
|
||||||
]),
|
]),
|
||||||
models: models.map((m) => [m.id, m.name, m.format, m.isPrimary, m.updatedAt.toISOString(), m.fileAssetId]),
|
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 {
|
return {
|
||||||
|
|||||||
@@ -60,6 +60,8 @@ export enum TargetType {
|
|||||||
Song = 'song',
|
Song = 'song',
|
||||||
Motion = 'motion',
|
Motion = 'motion',
|
||||||
Model = 'model',
|
Model = 'model',
|
||||||
|
/** 场景（T-WEB-015） */
|
||||||
|
Scene = 'scene',
|
||||||
}
|
}
|
||||||
|
|
||||||
export enum AssetKind {
|
export enum AssetKind {
|
||||||
@@ -72,6 +74,10 @@ export enum AssetKind {
|
|||||||
Thumbnail = 'thumbnail',
|
Thumbnail = 'thumbnail',
|
||||||
/** 动作关键点序列的骨架缩略图（T-WEB-014） */
|
/** 动作关键点序列的骨架缩略图（T-WEB-014） */
|
||||||
MotionThumbnail = 'motion-thumbnail',
|
MotionThumbnail = 'motion-thumbnail',
|
||||||
|
/** 场景 GLB（T-WEB-015） */
|
||||||
|
Scene = 'scene',
|
||||||
|
/** 场景缩略图 */
|
||||||
|
SceneThumbnail = 'scene-thumbnail',
|
||||||
Keypoints = 'keypoints',
|
Keypoints = 'keypoints',
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
@@ -9,12 +9,12 @@ import { join } from 'node:path';
|
|||||||
* 未设置该变量时回落到这里的常量）。
|
* 未设置该变量时回落到这里的常量）。
|
||||||
*/
|
*/
|
||||||
export const CONTRACT_VERSIONS: Readonly<Record<string, string>> = Object.freeze({
|
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',
|
'websocket-keypoints': '0.1.0',
|
||||||
'data-models': '0.6.0',
|
'data-models': '0.7.0',
|
||||||
'skeleton-topology': '0.2.0',
|
'skeleton-topology': '0.2.0',
|
||||||
'model-formats': '0.5.0',
|
'model-formats': '0.5.0',
|
||||||
database: '0.3.0',
|
database: '0.4.0',
|
||||||
});
|
});
|
||||||
|
|
||||||
/** 解析 `contracts/VERSION`（`key: value` 每行一条，`#` 起注释） */
|
/** 解析 `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 { Module } from '@nestjs/common';
|
||||||
import { TypeOrmModule } from '@nestjs/typeorm';
|
import { TypeOrmModule } from '@nestjs/typeorm';
|
||||||
import { ModelsModule } from '../models/models.module';
|
import { ModelsModule } from '../models/models.module';
|
||||||
@@ -9,7 +10,7 @@ import { ReviewsController } from './reviews.controller';
|
|||||||
import { ReviewsService } from './reviews.service';
|
import { ReviewsService } from './reviews.service';
|
||||||
|
|
||||||
@Module({
|
@Module({
|
||||||
imports: [TypeOrmModule.forFeature([ReviewRecord, Song, Motion, CharacterModel]), ModelsModule],
|
imports: [TypeOrmModule.forFeature([Scene, ReviewRecord, Song, Motion, CharacterModel]), ModelsModule],
|
||||||
controllers: [ReviewsController],
|
controllers: [ReviewsController],
|
||||||
providers: [ReviewsService],
|
providers: [ReviewsService],
|
||||||
exports: [ReviewsService],
|
exports: [ReviewsService],
|
||||||
|
|||||||
@@ -19,6 +19,7 @@ import { Paged, toPaged } from '../common/pagination';
|
|||||||
import { CharacterModel } from '../entities/model.entity';
|
import { CharacterModel } from '../entities/model.entity';
|
||||||
import { Motion } from '../entities/motion.entity';
|
import { Motion } from '../entities/motion.entity';
|
||||||
import { ReviewRecord } from '../entities/review-record.entity';
|
import { ReviewRecord } from '../entities/review-record.entity';
|
||||||
|
import { Scene } from '../entities/scene.entity';
|
||||||
import { Song } from '../entities/song.entity';
|
import { Song } from '../entities/song.entity';
|
||||||
import { QueryReviewDto, ReviewActionDto } from './review.dto';
|
import { QueryReviewDto, ReviewActionDto } from './review.dto';
|
||||||
|
|
||||||
@@ -68,6 +69,7 @@ export class ReviewsService {
|
|||||||
@InjectRepository(Song) private readonly songs: Repository<Song>,
|
@InjectRepository(Song) private readonly songs: Repository<Song>,
|
||||||
@InjectRepository(Motion) private readonly motions: Repository<Motion>,
|
@InjectRepository(Motion) private readonly motions: Repository<Motion>,
|
||||||
@InjectRepository(CharacterModel) private readonly models: Repository<CharacterModel>,
|
@InjectRepository(CharacterModel) private readonly models: Repository<CharacterModel>,
|
||||||
|
@InjectRepository(Scene) private readonly scenes: Repository<Scene>,
|
||||||
private readonly modelsService: ModelsService,
|
private readonly modelsService: ModelsService,
|
||||||
) {}
|
) {}
|
||||||
|
|
||||||
@@ -84,15 +86,17 @@ export class ReviewsService {
|
|||||||
async listByStatus(status: PublishStatus, query: QueryReviewDto): Promise<Paged<PendingItemDto>> {
|
async listByStatus(status: PublishStatus, query: QueryReviewDto): Promise<Paged<PendingItemDto>> {
|
||||||
const rows: 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.songs.find({ where: { status } }),
|
||||||
this.motions.find({ where: { status } }),
|
this.motions.find({ where: { status } }),
|
||||||
this.models.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(...songs.map((s) => toPending(TargetType.Song, s, s.title)));
|
||||||
rows.push(...motions.map((m) => toPending(TargetType.Motion, m, m.name)));
|
rows.push(...motions.map((m) => toPending(TargetType.Motion, m, m.name)));
|
||||||
rows.push(...models.map((m) => toPending(TargetType.Model, 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));
|
rows.sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : -1));
|
||||||
const total = rows.length;
|
const total = rows.length;
|
||||||
@@ -133,6 +137,14 @@ export class ReviewsService {
|
|||||||
save = () => this.motions.save(motion);
|
save = () => this.motions.save(motion);
|
||||||
break;
|
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: {
|
case TargetType.Model: {
|
||||||
const model = await this.models.findOne({ where: { id } });
|
const model = await this.models.findOne({ where: { id } });
|
||||||
if (!model) throw new NotFoundException(`模型 #${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 songsService = { toDtos: vi.fn().mockResolvedValue([]) };
|
||||||
const motionsService = { toDtos: vi.fn().mockResolvedValue([]) };
|
const motionsService = { toDtos: vi.fn().mockResolvedValue([]) };
|
||||||
|
const scenesService = { published: vi.fn().mockResolvedValue([]) };
|
||||||
const modelsService = {
|
const modelsService = {
|
||||||
toDtos: vi.fn().mockImplementation((rows: CharacterModel[]) =>
|
toDtos: vi.fn().mockImplementation((rows: CharacterModel[]) =>
|
||||||
rows.map((row) => toModelDto(row, { fileUrl: '/f', thumbnailUrl: null })),
|
rows.map((row) => toModelDto(row, { fileUrl: '/f', thumbnailUrl: null })),
|
||||||
@@ -90,6 +91,7 @@ describe('目录导出只含可用模型', () => {
|
|||||||
songsService as never,
|
songsService as never,
|
||||||
motionsService as never,
|
motionsService as never,
|
||||||
modelsService as never,
|
modelsService as never,
|
||||||
|
scenesService as never,
|
||||||
config 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');
|
||||||
|
});
|
||||||
|
});
|
||||||
Reference in New Issue
Block a user