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:
2026-09-15 08:47:37 +08:00
parent 76725e5ce3
commit bba5bcf59e
35 changed files with 2658 additions and 192 deletions
+6 -6
View File
@@ -32,7 +32,7 @@ tasks:
status: done
- id: T-WEB-004
file: tasks/004-motion-upload.md
scope: 动作数据上传 + 来源字段
scope: 动作数据上传(BVH / VMD / FBX / glTF / keypoints)+ 来源字段
status: done
- id: T-WEB-005
file: tasks/005-model-upload.md
@@ -40,7 +40,7 @@ tasks:
status: done
- id: T-WEB-006
file: tasks/006-keypoint-preprocess.md
scope: BVH/FBX → 关键点序列预处理
scope: BVH / VMD / FBX → 关键点序列预处理
status: done
- id: T-WEB-007
file: tasks/007-upload-review.md
@@ -56,16 +56,16 @@ tasks:
status: done
- id: T-WEB-010
file: tasks/010-deploy.md
scope: 部署脚本(不部署 MySQL)
scope: 部署脚本(双端口:软件 API 3000 + 管理端 3001,不部署 MySQL)
status: done
deliverable:
artifact: opendance-web-v0.1.0.tar.gz
packaging: Linux 业务服务(系统服务托管,不含 MySQL、不含反向代理、不使用 Docker)
packaging: Linux 业务服务(系统服务托管,双端口:软件 API + 管理端,不含 MySQL、不含反向代理、不使用 Docker)
includes:
- web-server/ # NestJS 源码 + 构建产物
- web-server/ # NestJS 源码 + 构建产物(含 BVH / VMD 内置解析)
- admin/ # React 管理端构建产物
- deploy/ # install.sh / systemd / openrc / initd / ctl.sh / .env.example
- deploy/ # install.sh / systemd / openrc / initd / ctl.sh / .env.example(PORT、ADMIN_PORT)
- deploy/proxy/ # 反向代理说明(nginx / IIS,仅供参考不部署)
- contracts/ # 当前版本契约快照
- THIRD_PARTY.md # 开源声明