fix(boot): CatalogModule 漏 import ScenesModule 导致产物起不来 + /health 版本号错

两个都是**只有真正启动服务才会暴露**的缺陷，v0.7.0 / v0.7.1 的产物受影响。 1. 【致命】CatalogModule 漏 import ScenesModule CatalogService 因为 catalog/export 要下发 scenes[] 而注入 ScenesService，但 CatalogModule 的 imports 只列了 SongsModule / MotionsModule / ModelsModule。 Nest 的 DI 按模块解析，于是 node dist/main.js 在 bootstrap 阶段直接抛 UnknownDependenciesException: Nest can't resolve dependencies of the CatalogService (... ? ...) —— 服务完全起不来（装得上、起不来）。为什么三层检查全绿：nest build/tsc 看不出运行时 DI；258 项单元测试直接 new 服务或测纯函数，从不编译 AppModule；打包脚本只校验文件清单与压缩包完整性。修复：CatalogModule.imports 补上 ScenesModule。 2. /health 的 version 在原生部署下永远是 0.1.0 原实现 process.env.npm_package_version ?? '0.1.0'，而该变量只在 npm 脚本下存在；正式部署是原生服务（ExecStart=node dist/main.js），npm 不参与 -> 恒为 undefined -> 回退到硬编码 0.1.0，与管理端左下角展示的 vX.Y.Z 冲突，违反文档 11.2 第 4 条「可核对：Web 端至少与 GET /health 的 version 一致」。修复：新增 src/config/app-version.ts 作为运行时唯一解析点（APP_VERSION -> 运行入口旁/工作目录的 package.json（带包名校验） -> npm_package_version -> 显式 0.0.0），/health 改用 resolveAppVersion()， main.ts 启动首行也打印版本号。新增 12 项测试，其中一项显式模拟无 npm 环境变量的原生部署。防线（都挂进了 verify 与打包脚本） - scripts/check-bootstrap.mjs：以正式部署方式（node dist/main.js、无 npm 环境变量、不需要数据库）拉起真实产物，断言①无依赖解析类错误②启动日志的应用版本等于 package.json ③已推进到数据库连接阶段。已做反向验证：删掉 ScenesModule 后该检查立刻失败。 - scripts/check-version.mjs（并入 contracts:check）：校验 web-server/package.json = admin/package.json = project.yaml，正则禁止 health.controller.ts 再出现硬编码版本回退，管理端已构建时断言产物 JS 含 vX.Y.Z。 - npm run verify 现在包含 bootstrap:check；package-release.sh 在构建后、打包前各跑一次（构建管理端后再跑 version:check，因为此时才需要校验产物内版本）。文档：README.md / README.txt 增加 v0.7.2 修订说明； tasks/011-version-display.md 与 tasks/015-scene-management.md 补「缺陷修复记录」（含为什么当时没被发现的三层检查对照表）。验证：npm run verify 通过（契约六项一致、35 条路由、258 项测试、nest build、启动冒烟）；产物 opendance-web-v0.7.2.tar.gz sha256 f04ecc85d17517ec00754238616eb1237cdb2fe17440af6dce731827c0922b26。
2026-09-17 01:49:52 +08:00
parent 698d60bb65
commit 2433cd22a5
16 changed files with 673 additions and 22 deletions
@@ -0,0 +1,111 @@
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+  PACKAGE_NAME,
+  UNKNOWN_VERSION,
+  packageJsonCandidates,
+  parsePackageVersion,
+  resetAppVersionCache,
+  resolveAppVersion,
+} from '../src/config/app-version';
+
+/**
+ * 版本号展示的**运行时唯一来源**（文档 §11.1 / §11.2）。
+ *
+ * 这里守护的是一个真实发生过的缺陷：原来 `/health` 用
+ * `process.env.npm_package_version ?? '0.1.0'`，而正式部署方式是原生服务
+ * （`ExecStart=node dist/main.js`），npm 不参与 → 该环境变量为 undefined →
+ * `/health` 在真实部署里永远报 **0.1.0**，与管理端左下角展示的 vX.Y.Z 不一致，
+ * 直接违反「可核对：Web 端至少与 GET /health 的 version 一致」。
+ */
+
+const serverPackageJson = JSON.parse(
+  readFileSync(resolve(__dirname, '..', 'package.json'), 'utf8'),
+) as { name: string; version: string };
+
+afterEach(() => {
+  delete process.env.APP_VERSION;
+  resetAppVersionCache();
+});
+
+describe('parsePackageVersion（纯函数：只在包名与格式都对时才认）', () => {
+  it('接受本项目的 package.json', () => {
+    expect(
+      parsePackageVersion(JSON.stringify({ name: PACKAGE_NAME, version: '1.2.3' })),
+    ).toBe('1.2.3');
+  });
+
+  it('接受带预发布后缀的版本', () => {
+    expect(
+      parsePackageVersion(JSON.stringify({ name: PACKAGE_NAME, version: '1.2.3-rc.1' })),
+    ).toBe('1.2.3-rc.1');
+  });
+
+  it('拒绝包名不匹配的文件（避免读到上层仓库的 package.json）', () => {
+    expect(parsePackageVersion(JSON.stringify({ name: 'some-other-pkg', version: '9.9.9' }))).toBeNull();
+  });
+
+  it('拒绝缺少 name / version 的文件', () => {
+    expect(parsePackageVersion(JSON.stringify({ version: '1.2.3' }))).toBeNull();
+    expect(parsePackageVersion(JSON.stringify({ name: PACKAGE_NAME }))).toBeNull();
+    expect(parsePackageVersion(JSON.stringify({ name: PACKAGE_NAME, version: 123 }))).toBeNull();
+  });
+
+  it('拒绝非版本串（例如 workspace:*）', () => {
+    expect(parsePackageVersion(JSON.stringify({ name: PACKAGE_NAME, version: 'workspace:*' }))).toBeNull();
+    expect(parsePackageVersion(JSON.stringify({ name: PACKAGE_NAME, version: '^1.0.0' }))).toBeNull();
+  });
+
+  it('拒绝非法 JSON 与非对象', () => {
+    expect(parsePackageVersion('{ 不是 JSON')).toBeNull();
+    expect(parsePackageVersion('"字符串"')).toBeNull();
+    expect(parsePackageVersion('null')).toBeNull();
+  });
+});
+
+describe('resolveAppVersion（运行时解析）', () => {
+  it('解析结果等于 web-server/package.json 的 version（单一来源）', () => {
+    expect(resolveAppVersion()).toBe(serverPackageJson.version);
+  });
+
+  it('与 package.json 里声明的包名一致（校验逻辑没有把别的包读进来）', () => {
+    expect(serverPackageJson.name).toBe(PACKAGE_NAME);
+  });
+
+  it('未通过 npm 启动时也能拿到真实版本（不依赖 npm_package_version）', () => {
+    // 模拟原生部署：systemd 直接跑 node dist/main.js，没有 npm 环境变量
+    const saved = process.env.npm_package_version;
+    delete process.env.npm_package_version;
+    delete process.env.APP_VERSION;
+    resetAppVersionCache();
+    try {
+      const version = resolveAppVersion();
+      expect(version).toBe(serverPackageJson.version);
+      expect(version).not.toBe('0.1.0');
+      expect(version).not.toBe(UNKNOWN_VERSION);
+    } finally {
+      if (saved !== undefined) process.env.npm_package_version = saved;
+      resetAppVersionCache();
+    }
+  });
+
+  it('APP_VERSION 环境变量可显式覆盖（运维不重新打包也能改）', () => {
+    process.env.APP_VERSION = '9.8.7';
+    resetAppVersionCache();
+    expect(resolveAppVersion()).toBe('9.8.7');
+  });
+
+  it('候选路径包含工作目录（systemd WorkingDirectory=web-server）', () => {
+    const candidates = packageJsonCandidates();
+    expect(candidates).toContain(join(process.cwd(), 'package.json'));
+    // 去重：同一路径不应出现两次
+    expect(new Set(candidates).size).toBe(candidates.length);
+  });
+
+  it('结果稳定（同一进程内缓存，不会来回变）', () => {
+    const first = resolveAppVersion();
+    const second = resolveAppVersion();
+    expect(first).toBe(second);
+  });
+});