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 越界（测试数据已从数据库清理）。
2026-09-15 08:47:37 +08:00
parent 76725e5ce3
commit bba5bcf59e
35 changed files with 2658 additions and 192 deletions
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { describeAccess } from '../src/config/access-hint';
+import { describeAccess, describeDualAccess, preferredUrl } from '../src/config/access-hint';

 /**
 * 启动日志里"该访问哪个地址"必须与真实绑定一致。
@@ -38,3 +38,76 @@ describe('启动日志的访问地址推导', () => {
    expect(describeAccess('10.0.0.1', 80).urls).toEqual(['http://10.0.0.1:80']);
  });
 });
+
+/**
+ * 双端口模式下，启动日志必须分别说清"客户端调接口用哪个地址"和
+ * "浏览器看管理页面用哪个地址"，否则客户端会把管理端口当成 API 端口。
+ */
+describe('双端口访问提示', () => {
+  it('分端口时分别给出软件 API 与管理端两行，并标明各自职责', () => {
+    const hint = describeDualAccess({
+      apiHost: '0.0.0.0',
+      apiPort: 3111,
+      adminHost: '0.0.0.0',
+      adminPort: 3112,
+    });
+    expect(hint.sharedPort).toBe(false);
+    expect(hint.apiLine).toContain('软件 API 端口：');
+    expect(hint.apiLine).toContain(':3111');
+    expect(hint.apiLine).toContain('/api、/health、/static、/contracts');
+    expect(hint.adminLine).toContain('管理端端口：');
+    expect(hint.adminLine).toContain(':3112');
+    expect(hint.adminLine).toContain('浏览器访问');
+    expect(hint.adminLine).not.toContain('未分端口');
+    expect(hint.sharedNotice).toBe('');
+  });
+
+  it('绝不把 0.0.0.0 写进可访问地址', () => {
+    const hint = describeDualAccess({
+      apiHost: '0.0.0.0',
+      apiPort: 3000,
+      adminHost: '0.0.0.0',
+      adminPort: 3001,
+    });
+    expect(hint.apiLine).not.toContain('0.0.0.0');
+    expect(hint.adminLine).not.toContain('0.0.0.0');
+    expect(hint.api.urls[0]).toBe('http://127.0.0.1:3000');
+  });
+
+  it('ADMIN_PORT === PORT 时标记为未分端口并给出提示', () => {
+    const hint = describeDualAccess({
+      apiHost: '0.0.0.0',
+      apiPort: 3000,
+      adminHost: '0.0.0.0',
+      adminPort: 3000,
+    });
+    expect(hint.sharedPort).toBe(true);
+    expect(hint.sharedNotice).toContain('未分端口');
+    expect(hint.adminLine).toContain('未分端口');
+    expect(hint.adminLine).toContain(':3000');
+  });
+
+  it('绑定回环时保留"只能本机访问"的告警依据', () => {
+    const hint = describeDualAccess({
+      apiHost: '127.0.0.1',
+      apiPort: 3000,
+      adminHost: '127.0.0.1',
+      adminPort: 3001,
+    });
+    expect(hint.loopbackOnly).toBe(true);
+    expect(hint.apiLine).toContain('http://127.0.0.1:3000');
+  });
+
+  it('preferredUrl 优先挑真实网卡地址，没有才回落到回环地址', () => {
+    expect(
+      preferredUrl({
+        listen: '',
+        urls: ['http://127.0.0.1:3000', 'http://192.168.1.10:3000'],
+        loopbackOnly: false,
+      }),
+    ).toBe('http://192.168.1.10:3000');
+    expect(
+      preferredUrl({ listen: '', urls: ['http://127.0.0.1:3000'], loopbackOnly: true }),
+    ).toBe('http://127.0.0.1:3000');
+  });
+});