zijunchiang
2433cd22a5
两个都是**只有真正启动服务才会暴露**的缺陷，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。
3.0 KiB
3.0 KiB
T-WEB-011 管理端展示当前版本号
- 状态: done
- 依赖: T-WEB-010
- 文档: v1.6 §11（版本号展示）
目标
管理端页面左下角展示当前运行版本 vX.Y.Z，且与 GET /health 的 version
同源（文档 §11.1 的硬性要求：单一来源、可核对）。
方案
| 项 | 做法 |
|---|---|
| 唯一来源 | web-server/package.json 的 version（同时是 /health 的 version） |
| 注入方式 | Vite 构建期 define: { __APP_VERSION__: <package.json version> } |
| 展示位置 | admin/src/components/Layout.tsx 侧边栏底部 APP_VERSION_LABEL |
| 禁止重复 | admin/src/lib/version.ts 是唯一读取点，界面不出现版本号字面量 |
/health 的 version 取 process.env.npm_package_version（由 npm 脚本注入），
与构建期注入管理端的值来自同一个 package.json，因此不可能不一致。
验收（文档 §11.3）
| 验收项 | 结果 |
|---|---|
管理端任一页面左下角可见 vX.Y.Z |
✅ 侧边栏底部固定显示 |
与 GET /health 的 version 相同 |
✅ 同源于 web-server/package.json |
| 与产物文件名一致 | ✅ opendance-web-vX.Y.Z.tar.gz；打包脚本读取同一个 package.json |
缺陷修复记录（v0.7.2）
缺陷：/health 的 version 在正式部署里永远是 0.1.0。
原实现是 process.env.npm_package_version ?? '0.1.0'。这个环境变量
只在通过 npm 脚本启动时才存在，而本项目的正式部署方式是原生服务
（systemd / OpenRC / initd，ExecStart=node dist/main.js）—— npm 不参与，
于是它恒为 undefined，/health 就回退到硬编码的 0.1.0。
这直接违反文档 §11.2 第 4 条「可核对：Web 端至少与 GET /health 的 version 一致」：
管理端左下角显示 v0.7.x，而 /health 说 0.1.0。
修复：
- 新增
src/config/app-version.ts作为运行时唯一解析点，按优先级尝试APP_VERSION环境变量 → 运行入口旁的package.json→ 工作目录的package.json→npm_package_version，每一步都做包名校验 （必须是opendance-web-server），避免读到上层仓库的package.json； 全都拿不到时返回显式的0.0.0，而不是伪装成某个具体版本； /health改为version: resolveAppVersion()；main.ts启动首行也打印应用版本 vX.Y.Z，即使后面数据库连不上、进程退出， 日志里也一定能看到本次运行的版本号。
防线：
scripts/check-version.mjs（并入npm run contracts:check）校验web-server/package.json=admin/package.json=project.yaml，并 禁止health.controller.ts再出现硬编码版本回退（正则拦截?? 'x.y.z'）； 管理端已构建时还会断言产物 JS 内确实含vX.Y.Z；test/app-version.spec.ts12 项，其中一项显式模拟无 npm 环境变量的原生部署；scripts/check-bootstrap.mjs用真实的node dist/main.js验证启动日志里的版本号。