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。
This commit is contained in:
2026-09-17 01:49:52 +08:00
parent 698d60bb65
commit 2433cd22a5
16 changed files with 673 additions and 22 deletions
+23 -5
View File
@@ -1,5 +1,5 @@
================================================================
OpenDance Studio -- Web 管理服务端 v0.7.1 使用说明
OpenDance Studio -- Web 管理服务端 v0.7.2 使用说明
================================================================
本服务端是 OpenDance Studio 三端中的第一端, 负责管理歌曲、VRM 模型与
@@ -8,6 +8,24 @@ OpenDance Studio -- Web 管理服务端 v0.7.1 使用说明
重要: 本服务端 不部署、不管理 MySQL。数据库为部署方提供的现有实例,
连接信息通过 .env 注入。
v0.7.2 修订 - 修复产物"装得上、起不来" + /health 报错版本号
1. CatalogModule 漏 import ScenesModule(致命): CatalogService 注入
ScenesService, 但 CatalogModule 只列了 Songs/Motions/Models。Nest 的 DI
按模块解析 -> node dist/main.js 在 bootstrap 直接抛
UnknownDependenciesException -> v0.7.0/v0.7.1 的产物根本起不来。
当时 build 通过、258 项测试全绿、打包完整性校验通过, 因为它们都不编译 AppModule。
2. 新增启动冒烟 scripts/check-bootstrap.mjs(挂进 verify 与打包脚本):
以正式部署方式(node dist/main.js, 无 npm 环境变量, 不需要数据库)拉起真实产物,
断言无依赖解析错误 + 应用版本等于 package.json + 已推进到数据库连接阶段。
已反向验证: 删掉 ScenesModule 后该检查立刻失败。
3. /health 版本号在原生部署下永远是 0.1.0: 原来用 npm_package_version,
该变量只在 npm 脚本下存在。新增 src/config/app-version.ts 作为运行时唯一
解析点(APP_VERSION -> package.json(带包名校验) -> npm_package_version -> 0.0.0),
main.ts 启动首行也打印版本号。
4. 新增 scripts/check-version.mjs(并入 contracts:check): 校验三处版本一致并
禁止 health.controller.ts 硬编码版本回退; 打包脚本构建管理端后再跑一次。
5. 新增 12 项测试(含"模拟无 npm 环境变量的原生部署")。
v0.7.1 修订 - 契约补齐 + 文档补齐(契约 websocket-keypoints 0.1.0 -> 0.2.0)
1. 补齐 rest-api.yaml 里漏写的场景结构(CatalogBundle.scenes[] + Scene +
SceneConfig): catalog/export 自 v0.7.0 起就返回 scenes[],规格漏写会导致
@@ -159,11 +177,11 @@ v0.2.1 修订
2. 准备一个现有的 MySQL / MariaDB 实例, 并建好库与账号(见下方"前置要求")
本项目不会创建数据库本身
3. 取得发布包并校验(地址用你们自己的制品库替换)
curl -LO https://<制品库地址>/opendance-web-v0.7.1.tar.gz
curl -LO https://<制品库地址>/opendance-web-v0.7.2.tar.gz
curl -LO https://<制品库地址>/SHA256SUMS
sha256sum -c SHA256SUMS # 期望输出 "OK"
4. 解压并生成配置(交互式引导, 逐项问答, 口令不回显)
tar -xzf opendance-web-v0.7.1.tar.gz && cd opendance-web-v0.7.1
tar -xzf opendance-web-v0.7.2.tar.gz && cd opendance-web-v0.7.2
bash deploy/init-env.sh
5. 安装(建用户与目录 -> 装依赖 -> 迁移 -> 注册系统服务 -> 等健康检查)
bash deploy/install.sh
@@ -221,8 +239,8 @@ v0.2.1 修订
(本项目不会创建数据库本身, 也不需要 GRANT OPTION / FILE / SUPER 等管理权限)
部署步骤
tar -xzf opendance-web-v0.7.1.tar.gz
cd opendance-web-v0.7.1
tar -xzf opendance-web-v0.7.2.tar.gz
cd opendance-web-v0.7.2
bash deploy/init-env.sh # 首次启动引导: 逐项问答生成 deploy/.env(见下)
bash deploy/install.sh # 已以 root 登录, 不需要 sudo