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:
+10
-7
@@ -1,7 +1,7 @@
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
title: OpenDance Studio Web 管理服务端 API
|
||||
version: 0.1.0
|
||||
version: 0.2.0
|
||||
description: |
|
||||
OpenDance Studio 的唯一数据源与契约权威。
|
||||
契约版本见 contracts/VERSION。字段语义见 contracts/data-models.md。
|
||||
@@ -11,11 +11,14 @@ info:
|
||||
- 来源五元组(sourceType/sourceName/sourceUrl/license/author)在三类资产上均为必填
|
||||
servers:
|
||||
- url: http://localhost:3000
|
||||
description: 本地开发
|
||||
- url: http://<host>
|
||||
description: 本地开发(软件 API 端口)
|
||||
- url: http://<host>:3000
|
||||
description: >-
|
||||
Linux 业务服务部署。服务自带管理端页面,反向代理(外部提供,非本项目交付物)
|
||||
只需将请求整体转发到该地址即可,无需托管静态文件或配置 SPA 回退。
|
||||
Linux 业务服务部署的**软件 API 端口**(`PORT`,默认 3000)。Windows/Godot 客户端与
|
||||
Android App 调用本端口的 /api、/health、/static、/contracts。
|
||||
管理端页面在**管理端口**(`ADMIN_PORT`,默认 3001),该端口同时提供全部接口;
|
||||
API 端口不提供管理页面,未命中的路径一律 404。
|
||||
反向代理由另外的服务提供(非本项目交付物),按用途分别转发到对应端口即可。
|
||||
|
||||
tags:
|
||||
- name: health
|
||||
@@ -180,7 +183,7 @@ paths:
|
||||
schema: { type: integer, format: int64 }
|
||||
- name: format
|
||||
in: query
|
||||
schema: { type: string, enum: [bvh, fbx, gltf, glb, keypoints-json] }
|
||||
schema: { type: string, enum: [bvh, vmd, fbx, gltf, glb, keypoints-json] }
|
||||
- name: status
|
||||
in: query
|
||||
schema: { $ref: '#/components/schemas/PublishStatus' }
|
||||
@@ -589,7 +592,7 @@ components:
|
||||
enum: [draft, pending, published, rejected]
|
||||
MotionFormat:
|
||||
type: string
|
||||
enum: [bvh, fbx, gltf, glb, keypoints-json]
|
||||
enum: [bvh, vmd, fbx, gltf, glb, keypoints-json]
|
||||
ModelFormat:
|
||||
type: string
|
||||
enum: [vrm, glb, gltf, fbx]
|
||||
|
||||
Reference in New Issue
Block a user