zijunchiang
3738bd91b9
契约变更（T-WEB-016，与 Android T-AND-011「两端一起改」配套）
- websocket-keypoints 0.1.0 -> 0.2.0，均为向后兼容（子协议名与二进制帧
version 均不变，只新增可选控制字段与一种新控制类型）：
1.1 保活：接收端必须声明 silentTimeoutMs 与 heartbeatIntervalMs，且心跳必须
小于静默超时的一半。根因是客户端只能用 OkHttp 的协议层 ping，而它由
底层库自动应答、**不暴露给应用层**，接收端根本看不到，无法续命；
3.1 hello.deviceId（该安装实例的稳定标识，不使用任何硬件序列号）；
3.2/3.3 welcome/config 携带保活字段；
3.6 应用层 ping/pong（回显 sentAtMs，pong 另带 serverAtMs 供算 RTT）；
5 设备去重：同一 deviceId 只保留最新连接，旧连接以 1000 关闭
（刻意用 1000：对端据 §7 不会重连，否则形成"挤掉-重连-再挤掉"循环）；
7 关闭码与重连策略：1000/1001/1002 与主动停止不重连，其余重连；
7.1 退避参数冻结：min(500ms*2^(n-1), 15000ms) + ±20% 抖动；
8 连接状态机（两端同名，日志可直接对照）。
- contracts/VERSION 与 src/config/contract-versions.ts 同步到 0.2.0。
补齐 rest-api.yaml 漏写的场景结构（只补规格，不改线格式，版本号不变）
- CatalogBundle 增加 scenes[]（标注 0.5.0 起下发）；
- 新增 Scene / SceneConfig / Vec3 schemas。catalog/export 自 v0.7.0 起就返回
scenes[]，data-models 7 也已冻结，但规格漏写会让两端对字段边界
（如 0~1、±200）的理解不一致。
deploy/proxy/README.md 新增第九节：Gitea 站点的附件上传上限
- 与一~五节的 Web 服务反代是**两个不同站点**；实测 30.5 MB / 40 MB 上传返回
HTTP 413，根因是 IIS 默认 maxAllowedContentLength = 30,000,000 字节；
- 给出放宽到 256 MB 的 IIS / ARR / Gitea app.ini / nginx 四处配置与复验命令；
- 这解释了 Windows 端 v0.1.0 为何被拆成 zip.part0/1/2（交付缺陷）。
文档与脚本
- 补齐 tasks/011~016 与 project.yaml 条目（T-WEB-011~015 此前已在代码中落地
却缺任务说明书）；project.yaml 的 contracts_version 由单个 0.4.0 改为六项字典；
- scripts/package-release.sh 的版本号改为从 web-server/package.json 读取
（与 GET /health 的 version、管理端左下角展示同源），并与 project.yaml 交叉校验；
同时补上 SHA256SUMS 与自校验（此前是手工生成的）。
验证：npm run verify 通过（contracts:check 六项一致 + 35 条路由一致、
typecheck、246 项测试、nest build）；产物 opendance-web-v0.7.1.tar.gz
sha256 27f92cfb125bbcf29077d4ad90c44720cbca46d23ddef12cd7826d73bd8865e2。
49 lines
2.6 KiB
Markdown
49 lines
2.6 KiB
Markdown
# T-WEB-015 场景管理（新增模块）
|
||
|
||
- **状态**: done
|
||
- **依赖**: T-WEB-007（审核流程）
|
||
- **文档**: v1.6 §4.12
|
||
- **契约**: `rest-api 0.5.0`、`data-models 0.7.0`、`database 0.4.0`
|
||
|
||
## 目标
|
||
|
||
新增**场景**这一类资源：客户端跟练时的 3D 环境（GLB）+ 物理参数
|
||
（重力 / 风 / 地面 / 碰撞体 / 环境 / 出生点 / 相机）。
|
||
服务端**只存参数、不跑物理**，仿真在客户端（Windows 端用 Godot 内置物理）。
|
||
|
||
## 与模型的区别
|
||
|
||
| 项 | 模型 | 场景 |
|
||
|--|--|--|
|
||
| 主力格式 | **VRM**（humanoid 重绑定） | **GLB**（不做重绑定、不转 VRM） |
|
||
| 转换 | PMX/FBX/zip → GLB → VRM | `.glb`/`.gltf` 直接导入；`.zip`/`.pmx`/`.fbx` → GLB |
|
||
| 附加数据 | 骨骼 / 材质 / 缩略图 | **物理参数** `SceneConfig` |
|
||
|
||
## 交付物
|
||
|
||
| 文件 | 说明 |
|
||
|--|--|
|
||
| `contracts/data-models.md` §7 | `Scene` 与冻结的 `SceneConfig` 结构 |
|
||
| `contracts/rest-api.yaml` | `/api/scenes` 增删改查 + 审核复用 `/api/reviews/scene/:id/approve\|reject` + `catalog/export.scenes[]` |
|
||
| `migrations/1789650000000-AddScenes.ts` | `scenes` 表；`config` / `stats` 用 **MEDIUMTEXT** |
|
||
| `src/scenes/scene-config.ts` | `normalizeSceneConfig()`：缺项默认、越界夹紧、非法枚举回退，**永不抛错** |
|
||
| `src/scenes/{scenes.service,scene.serializer,scenes.controller,scenes.module}.ts` | 业务实现（上传一律 `pending`；删除时清理源文件/GLB/缩略图） |
|
||
| `src/models/model-inspector.ts` | 场景复用模型检查器做 GLB 分析 |
|
||
| `src/models/model-thumbnail.ts` | 场景复用模型光栅化器出缩略图 |
|
||
| `admin/src/pages/Scenes.tsx` | 列表 / 上传 / 审核 / 删除 / 物理参数编辑（编辑期即按同一规则夹紧） |
|
||
| `admin/src/lib/scene-physics.ts` | 与后端同规则的收敛（保存前就不会产生非法枚举） |
|
||
|
||
> **MEDIUMTEXT 的原因**：`models.stats` 曾在 TEXT（65,535 字节）上溢出
|
||
> （实测 70,980 字节 → MySQL 1406 → 500）。场景的 `stats` 与 `config` 同样可能很大，
|
||
> 因此**一开始就用 MEDIUMTEXT**，并保留 `shrinkStatsForStorage()` 兜底。
|
||
|
||
## 验收
|
||
|
||
| 验收项 | 结果 |
|
||
|--|--|
|
||
| 场景可上传（GLB 直传 / zip 自动解包 / PMX 转换） | ✅ 与模型同一套转换管线 |
|
||
| 物理参数可在管理端可视化编辑 | ✅ 重力 / 风 / 摩擦 / 弹性 / 碰撞体 / 环境 / 出生点 / 相机 |
|
||
| 非法参数不会入库 | ✅ 前后端同规则收敛；`test/scene-config.spec.ts` 9 项边界用例 |
|
||
| 客户端能拿到场景 | ✅ `catalog/export.scenes[]`；目录指纹纳入场景变更 |
|
||
| 路由与契约一致 | ✅ `check-routes` 共 **35** 条 |
|