feat(web): 端口分离 + VMD 动作支持；契约升至 0.2.0
需求 1：管理端端口与软件 API 端口分离 - 软件 API 端口 PORT（默认 3000）只提供 /api、/health、/static、/contracts， 不提供管理页面（未命中路径 404）；管理端端口 ADMIN_PORT（默认 3001） 提供管理页面与全部接口；ADMIN_HOST 可单独限制管理端来源 - main.ts 同进程监听两个端口，用 req.socket.localPort 区分端口行为； ADMIN_PORT=PORT 为单端口兼容模式（只创建一个 server，无 EADDRINUSE） - 端口非法在生产环境中止启动；ADMIN_PORT=PORT 只 warn - 启动日志分别打印两个端口的访问地址 需求 2：动作数据支持 VMD（MikuMikuDance） - vmd-parser.ts：二进制解析（30 字节头 + Shift-JIS 模型名 + 111 字节/条骨骼 关键帧 + morph 段）、MMD 贝塞尔插值、GBK 模型名回退、固定 30fps - mmd-skeleton.ts：标准 MMD 骨架；静止比例从参考 PMX 骨骼段实测得到 （足首 1.43 / 膝 6.57 / 髋 11.50 / 首 16.21 / 頭 17.16，腿长 10.09） - mmd-pose.ts：FK + 两骨骼解析腿部 IK（膝盖朝正面，不可达收敛为伸直） + 左手系→右手系 Z 镜像（由真实数据对照实验确定：94.1% vs 5.9%） - retarget.ts：抽出 worldFramesToKeypointFrames()，BVH 与 VMD 共用重定向 - MotionFormat 增 vmd、扩展名映射增 .vmd；管理端上传支持 .vmd - scripts/inspect-vmd.mjs：上传前自查工具 契约：rest-api / data-models / model-formats → 0.2.0（另两库已同步逐字节一致） 验证：85 项单测通过（VMD 31 项）；契约与 29 条路由一致；typecheck/build 通过； 真实样本经 HTTP 端到端：霜雪千年 2901 帧（IK 腿）、恋爱循环 4604 帧（FK 腿） 均 preprocessState=done、0 NaN、0 越界（测试数据已从数据库清理）。
This commit is contained in:
@@ -30,7 +30,7 @@ opendance-web ←── 本仓库
|
||||
| 数据库 | **现有 MySQL 兼容实例**（当前部署为 MariaDB 10.11.19），mysql2 驱动 |
|
||||
| 管理前端 | React 18 + Vite + TypeScript |
|
||||
| 3D 预览 | three.js + @pixiv/three-vrm |
|
||||
| 多格式解析 | BVH 内置纯 TS 解析器；FBX/glTF 走可选外部 Assimp |
|
||||
| 多格式解析 | BVH / VMD 内置纯 TS 解析器；FBX/glTF 走可选外部 Assimp |
|
||||
| 认证 | **本版本不含认证**（内网部署）；上线前须补 ≥ T-WEB-011 |
|
||||
|
||||
## 3. 单次会话加载范围
|
||||
@@ -77,9 +77,15 @@ opendance-web/
|
||||
│ └── open-source-credits.md # 开源声明锚点（三端共用）
|
||||
├── web-server/ # NestJS 服务端
|
||||
│ ├── src/ # 源码（entities / modules / preprocess）
|
||||
│ │ └── preprocess/ # BVH / VMD / FBX → MediaPipe33
|
||||
│ │ ├── vmd-parser.ts # VMD 二进制 + Shift-JIS + 贝塞尔插值
|
||||
│ │ ├── mmd-skeleton.ts # 标准 MMD 骨架（静止比例实测自参考 PMX）
|
||||
│ │ ├── mmd-pose.ts # MMD FK + 两骨骼腿部 IK + 左手系→右手系 Z 镜像
|
||||
│ │ └── retarget.ts # worldFramesToKeypointFrames()：BVH / VMD 共用
|
||||
│ ├── admin/ # React 管理端
|
||||
│ ├── test/ # 单元测试 + 端到端冒烟
|
||||
│ ├── test/ # 单元测试 + 端到端冒烟（含 mmd-vmd.spec.ts）
|
||||
│ └── scripts/ # migrate.mjs / check-contracts.mjs / check-routes.mjs
|
||||
│ # / inspect-vmd.mjs（VMD 诊断工具）
|
||||
├── deploy/ # ★ 业务服务部署（不含 MySQL、不含反代）
|
||||
│ ├── install.sh # 一键部署（systemd / OpenRC / SysVinit / 后台进程）
|
||||
│ ├── uninstall.sh
|
||||
@@ -99,6 +105,8 @@ opendance-web/
|
||||
**也不使用 Docker**，**也不部署反向代理**：本端只提供业务服务
|
||||
（API + 自带的管理端页面），反代由另外的服务负责，
|
||||
本项目只在 `deploy/proxy/` 下提供 IIS 与 nginx 的配置说明文档。
|
||||
业务服务监听**两个端口**（软件 API 端口 `PORT` + 管理端端口 `ADMIN_PORT`），
|
||||
约定见 §9。
|
||||
2. **`DB_SYNCHRONIZE` 生产必须为 `false`**，所有表结构变更走 migration；每个
|
||||
migration 必须可逆。
|
||||
3. **绝不把凭证写入仓库**。`.env` 已在 `.gitignore` 中，只提交 `.env.example`。
|
||||
@@ -143,13 +151,55 @@ git push origin task/T-WEB-0XX
|
||||
```
|
||||
DB_HOST DB_PORT DB_USER DB_PASS DB_NAME
|
||||
DB_SYNCHRONIZE=false
|
||||
PORT=3000 # 软件 API 端口（客户端调用，不含管理页面）
|
||||
ADMIN_PORT=3001 # 管理端端口（默认 PORT + 1；等于 PORT 为单端口兼容模式）
|
||||
HOST=0.0.0.0 # 软件 API 监听地址
|
||||
ADMIN_HOST=0.0.0.0 # 可选，管理端监听地址，默认跟随 HOST
|
||||
STORAGE_DIR=/data/storage
|
||||
UPLOAD_MAX_BYTES=536870912
|
||||
ASSIMP_BIN=assimp # 可选
|
||||
CONTRACTS_DIR=/contracts # 可选，读取实时契约版本
|
||||
```
|
||||
|
||||
## 9. 上下文超标时的拆分策略
|
||||
## 9. 双端口约定（软件 API 端口 / 管理端端口）
|
||||
|
||||
- **软件 API 端口**：`PORT`，默认 **3000**。给 Windows/Godot 客户端与 Android App
|
||||
调用，只提供 `/api`、`/health`、`/static`、`/contracts`；**不提供管理页面**，
|
||||
`/`、`/songs` 等一律 404（有意设计，避免管理页暴露在客户端调用的端口上）。
|
||||
- **管理端端口**：`ADMIN_PORT`，默认 `PORT + 1`（即 **3001**）。给浏览器访问，
|
||||
提供管理页面（含 SPA 深链接回退）与上面全部接口。
|
||||
- `ADMIN_HOST` 可选，默认跟随 `HOST`；可用它把管理端限制在本机或内网。
|
||||
- `ADMIN_PORT === PORT` 为**单端口兼容模式**：管理页面回到 API 端口，日志提示
|
||||
「未分端口」，只 warn 不中止启动。
|
||||
- 端口非法（非 1..65535 整数）在生产环境会中断启动。
|
||||
- 启动日志分别打印两行：`软件 API 端口：…` 与 `管理端端口：…`。
|
||||
- 反向代理按用途分别转发两个端口；`/health` 两个端口都提供，可用于存活探测。
|
||||
细则见 `deploy/proxy/README.md` 与 `tasks/010-deploy.md`。
|
||||
|
||||
## 10. VMD 动作通路（MikuMikuDance）
|
||||
|
||||
```
|
||||
.vmd ─▶ vmd-parser.ts ─▶ mmd-skeleton.ts ─▶ mmd-pose.ts ─▶ retarget.ts
|
||||
二进制 + Shift-JIS 标准 MMD 骨架 FK + 腿部 IK worldFramesToKeypointFrames()
|
||||
+ 贝塞尔插值 + Z 镜像 （与 BVH 共用）
|
||||
```
|
||||
|
||||
- `MotionFormat.Vmd = 'vmd'`，扩展名 `.vmd`，固定 **30 fps**（上传时填写的 `fps` 被忽略）。
|
||||
- VMD 二进制：30 字节头 + 20 字节 Shift-JIS 模型名 + 111 字节/条的骨骼关键帧 + morph 段；
|
||||
只有旋转（少数骨骼带位移）、不含骨骼长度，因此必须靠 `mmd-skeleton.ts` 的标准骨架
|
||||
（静止比例从参考 PMX 实测）做 FK。
|
||||
- **腿部驱动自动判定**：`足ＩＫ` 有非零位移 → 两骨骼解析 IK（膝盖朝角色正面弯，
|
||||
不可达时收敛为伸直）；否则用 FK 旋转。部分动作数据把腿烘焙成 FK。
|
||||
- **手性**：MMD 为左手系，统一做 Z 镜像（旋转 `(x,y,z,w) → (-x,-y,z,w)`、位移 z 取反）
|
||||
后进入右手系通路。由真实数据对照实验确定：腿部烘焙为 FK 的样本中，`zMirrored`
|
||||
下「膝盖朝前」占 94.1%，不转换仅 5.9%。
|
||||
- `worldFramesToKeypointFrames()` 为 BVH / VMD 共用：骨盆归零 / 自适应缩放 /
|
||||
图像空间投影 / 9 个关节角完全一致。
|
||||
- 诊断工具：`node scripts/inspect-vmd.mjs 动作.vmd [--frames N] [--json out.json]`
|
||||
（打印头部/模型名/帧数/轨道数、未识别骨骼、IK 还是 FK、关键点序列异常统计、膝肘角分布）。
|
||||
- 契约 `contracts/model-formats.md` §2.3；测试 `test/mmd-vmd.spec.ts`（31 项）。
|
||||
|
||||
## 11. 上下文超标时的拆分策略
|
||||
|
||||
| 超标原因 | 拆分方式 |
|
||||
|---|---|
|
||||
|
||||
Reference in New Issue
Block a user