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
@@ -10,6 +10,35 @@ export interface AccessHint {
  loopbackOnly: boolean;
 }

+/** 软件 API 端口对外提供的接口路径范围，用于启动日志。 */
+const API_SCOPE = '/api、/health、/static、/contracts';
+
+/** 双端口模式（软件 API 端口 + 管理端端口）的访问提示。 */
+export interface DualAccessHint {
+  /** 软件 API 端口（Windows/Godot 客户端、Android App 调用）。 */
+  api: AccessHint;
+  /** 管理端端口（浏览器访问）。 */
+  admin: AccessHint;
+  /** 是否为单端口兼容模式（ADMIN_PORT === PORT）。 */
+  sharedPort: boolean;
+  /** 是否只监听回环（两个端口都只在本机可访问时才为 true）。 */
+  loopbackOnly: boolean;
+  /** 启动日志第一行：软件 API 端口。 */
+  apiLine: string;
+  /** 启动日志第二行：管理端端口。 */
+  adminLine: string;
+  /** 单端口兼容模式下的提示文案；未分端口时为空串。 */
+  sharedNotice: string;
+}
+
+/** describeDualAccess 的入参。 */
+export interface DualAccessOptions {
+  apiHost: string;
+  apiPort: number;
+  adminHost: string;
+  adminPort: number;
+}
+
 /**
 * 把绑定地址翻译成"人能看懂、能直接用"的访问地址。
 *
@@ -37,3 +66,41 @@ export function describeAccess(bindHost: string, port: number): AccessHint {
  }
  return { listen: `0.0.0.0:${port}（全部网卡，外部可访问）`, urls, loopbackOnly: false };
 }
+
+/** 取一个"外部设备也能访问"的地址优先展示；没有真实网卡时回落到回环地址。 */
+export function preferredUrl(hint: AccessHint): string {
+  const external = hint.urls.find((url) => !/127\.0\.0\.1|localhost|\[::1\]/.test(url));
+  return external ?? hint.urls[0];
+}
+
+/**
+ * 描述"软件 API 端口 + 管理端端口"两个端口，供启动日志直接打印。
+ *
+ * 客户端（Windows/Godot、Android）与管理端（浏览器）的职责不同，
+ * 必须分别告诉使用者该访问哪个地址、该地址提供什么，避免把管理页面
+ * 挂到客户端调用的端口上。
+ */
+export function describeDualAccess(options: DualAccessOptions): DualAccessHint {
+  const api = describeAccess(options.apiHost, options.apiPort);
+  const admin = describeAccess(options.adminHost, options.adminPort);
+  const sharedPort = options.adminPort === options.apiPort;
+
+  const apiLine = `软件 API 端口：${preferredUrl(api)}（${API_SCOPE}）`;
+  const adminLine = sharedPort
+    ? `管理端端口：  ${preferredUrl(admin)}（未分端口，与软件 API 同一端口；` +
+      '浏览器访问，含管理页面与全部接口）'
+    : `管理端端口：  ${preferredUrl(admin)}（浏览器访问，含管理页面与全部接口）`;
+
+  return {
+    api,
+    admin,
+    sharedPort,
+    loopbackOnly: api.loopbackOnly || admin.loopbackOnly,
+    apiLine,
+    adminLine,
+    sharedNotice: sharedPort
+      ? `ADMIN_PORT 与 PORT 相同（${options.apiPort}），未分端口：` +
+        '管理页面与软件 API 共用同一端口，行为与旧版一致'
+      : '',
+  };
+}
@@ -34,7 +34,16 @@ export class AppConfig {
  }

  /**
-   * 监听地址。
+   * 管理端端口（浏览器访问）。
+   * 未设置 ADMIN_PORT 时默认取 PORT + 1，与管理端端口分开：
+   * 软件 API 端口只提供接口，管理端口同时提供管理端页面与全部接口。
+   */
+  get adminPort(): number {
+    return this.config.get<number>('adminPort') ?? this.port + 1;
+  }
+
+  /**
+   * 监听地址（软件 API 端口）。
   * 反向代理与后端同机时建议设为 127.0.0.1（仅本机可访问）；
   * 代理在其他机器上时必须为 0.0.0.0，并用防火墙限制来源。
   */
@@ -42,6 +51,14 @@ export class AppConfig {
    return this.config.get<string>('bindHost') ?? '0.0.0.0';
  }

+  /**
+   * 管理端监听地址，默认与 HOST 一致。
+   * 需要"接口对外、管理端只对本机"时，可单独把 ADMIN_HOST 设为 127.0.0.1。
+   */
+  get adminHost(): string {
+    return this.config.get<string>('adminHost') ?? this.bindHost;
+  }
+
  get storageDir(): string {
    return this.config.get<string>('storageDir') ?? resolve(process.cwd(), 'storage');
  }
@@ -89,40 +106,114 @@ function bool(value: string | undefined, fallback = false): boolean {
  return value === 'true' || value === '1';
 }

+/**
+ * 解析端口环境变量。
+ * 未设置或空白时使用 fallback；非法值（NaN、越界、非整数）原样返回，
+ * 交由 validateEnv 统一报问题，避免在这里静默纠正错误配置。
+ */
+export function parsePort(raw: string | undefined, fallback: number): number {
+  if (raw === undefined || raw.trim() === '') return fallback;
+  return Number(raw);
+}
+
+/**
+ * 管理端端口：优先 ADMIN_PORT，未设置时回落到 PORT + 1。
+ * 允许 ADMIN_PORT === PORT（单端口兼容模式，行为与旧版一致）。
+ */
+export function resolveAdminPort(port: number, rawAdminPort?: string): number {
+  if (rawAdminPort === undefined || rawAdminPort.trim() === '') return port + 1;
+  return Number(rawAdminPort);
+}
+
+/** 是否为单端口兼容模式（管理端与软件 API 共用同一端口）。 */
+export function isSamePort(port: number, adminPort: number): boolean {
+  return Number.isInteger(port) && port === adminPort;
+}
+
+/**
+ * 按请求进入的端口判断是否为管理端请求。
+ *
+ * 软件 API 端口不提供管理端页面：根路径 `/` 与任意前端路径都必须 404；
+ * 单端口兼容模式（ADMIN_PORT === PORT）下所有请求都按管理端处理。
+ * localPort 缺失时按软件 API 端口处理（宁可少给页面，不可把管理页挂到接口端口）。
+ */
+export function isAdminPortRequest(
+  localPort: number | undefined,
+  port: number,
+  adminPort: number,
+): boolean {
+  if (isSamePort(port, adminPort)) return true;
+  return localPort === adminPort;
+}
+
 /** @nestjs/config 的 load 工厂 */
-export const configuration = () => ({
-  nodeEnv: process.env.NODE_ENV ?? 'development',
-  port: Number(process.env.PORT ?? 3000),
-  bindHost: process.env.HOST ?? '0.0.0.0',
-  storageDir: process.env.STORAGE_DIR ?? resolve(process.cwd(), 'storage'),
-  adminDir: process.env.ADMIN_DIR ?? resolve(process.cwd(), '..', 'admin'),
-  uploadMaxBytes: Number(process.env.UPLOAD_MAX_BYTES ?? 512 * 1024 * 1024),
-  assimpBin: process.env.ASSIMP_BIN ?? 'assimp',
-  contractsDir: process.env.CONTRACTS_DIR ?? '',
-  db: {
-    host: process.env.DB_HOST ?? '127.0.0.1',
-    port: Number(process.env.DB_PORT ?? 3306),
-    user: process.env.DB_USER ?? 'opendance_app',
-    pass: process.env.DB_PASS ?? '',
-    name: process.env.DB_NAME ?? 'opendance',
-    synchronize: bool(process.env.DB_SYNCHRONIZE, false),
-    logging: bool(process.env.DB_LOGGING, false),
-  },
-});
+export const configuration = () => {
+  const port = parsePort(process.env.PORT, 3000);
+  return {
+    nodeEnv: process.env.NODE_ENV ?? 'development',
+    port,
+    bindHost: process.env.HOST ?? '0.0.0.0',
+    adminPort: resolveAdminPort(port, process.env.ADMIN_PORT),
+    // 管理端监听地址默认与 HOST 一致；未设置 HOST 时同样回落到 0.0.0.0
+    adminHost: process.env.ADMIN_HOST ?? process.env.HOST ?? '0.0.0.0',
+    storageDir: process.env.STORAGE_DIR ?? resolve(process.cwd(), 'storage'),
+    adminDir: process.env.ADMIN_DIR ?? resolve(process.cwd(), '..', 'admin'),
+    uploadMaxBytes: Number(process.env.UPLOAD_MAX_BYTES ?? 512 * 1024 * 1024),
+    assimpBin: process.env.ASSIMP_BIN ?? 'assimp',
+    contractsDir: process.env.CONTRACTS_DIR ?? '',
+    db: {
+      host: process.env.DB_HOST ?? '127.0.0.1',
+      port: Number(process.env.DB_PORT ?? 3306),
+      user: process.env.DB_USER ?? 'opendance_app',
+      pass: process.env.DB_PASS ?? '',
+      name: process.env.DB_NAME ?? 'opendance',
+      synchronize: bool(process.env.DB_SYNCHRONIZE, false),
+      logging: bool(process.env.DB_LOGGING, false),
+    },
+  };
+};
+
+/** 环境变量校验结果：errors 为必须处理的问题，warnings 仅提示、不阻断启动。 */
+export interface EnvValidation {
+  errors: string[];
+  warnings: string[];
+}
+
+/** 端口必须是 1..65535 的整数。 */
+function validatePort(name: string, value: unknown, errors: string[]): void {
+  const valid =
+    typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= 65535;
+  if (!valid) {
+    errors.push(`${name} 非法（当前值 ${String(value)}），必须是 1..65535 的整数`);
+  }
+}

 /**
 * 生产环境下禁止 DB_SYNCHRONIZE=true —— 契约 database.md 明确要求。
- * 返回错误信息数组，供 main.ts 启动时快速失败。
+ * 端口非法属于 errors，供 main.ts 启动时快速失败；
+ * ADMIN_PORT === PORT 只是"未分端口"的兼容模式，属于 warnings，不阻断启动。
 */
-export function validateEnv(env: Record<string, unknown>): string[] {
-  const problems: string[] = [];
+export function validateEnv(env: Record<string, unknown>): EnvValidation {
+  const errors: string[] = [];
+  const warnings: string[] = [];
  const db = (env.db ?? {}) as Record<string, unknown>;

-  if (!db.host) problems.push('DB_HOST 未设置');
-  if (!db.user) problems.push('DB_USER 未设置');
-  if (!db.name) problems.push('DB_NAME 未设置');
+  if (!db.host) errors.push('DB_HOST 未设置');
+  if (!db.user) errors.push('DB_USER 未设置');
+  if (!db.name) errors.push('DB_NAME 未设置');
  if (env.nodeEnv === 'production' && db.synchronize === true) {
-    problems.push('生产环境禁止 DB_SYNCHRONIZE=true，请使用 TypeORM migration');
+    errors.push('生产环境禁止 DB_SYNCHRONIZE=true，请使用 TypeORM migration');
  }
-  return problems;
+
+  validatePort('PORT', env.port, errors);
+  validatePort('ADMIN_PORT', env.adminPort, errors);
+
+  if (isSamePort(env.port as number, env.adminPort as number)) {
+    warnings.push(
+      `ADMIN_PORT 与 PORT 相同（${String(env.port)}），未分端口：` +
+        '管理页面与软件 API 共用同一端口，建议分开部署',
+    );
+  }
+
+  return { errors, warnings };
 }
@@ -9,11 +9,11 @@ import { join } from 'node:path';
 *  未设置该变量时回落到这里的常量）。
 */
 export const CONTRACT_VERSIONS: Readonly<Record<string, string>> = Object.freeze({
-  'rest-api': '0.1.0',
+  'rest-api': '0.2.0',
  'websocket-keypoints': '0.1.0',
-  'data-models': '0.1.0',
+  'data-models': '0.2.0',
  'skeleton-topology': '0.1.0',
-  'model-formats': '0.1.0',
+  'model-formats': '0.2.0',
  database: '0.1.0',
 });