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。
62 lines
3.0 KiB
Markdown
62 lines
3.0 KiB
Markdown
# 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.ts` 12 项，其中一项**显式模拟无 npm 环境变量**的原生部署；
|
||
* `scripts/check-bootstrap.mjs` 用真实的 `node dist/main.js` 验证启动日志里的版本号。
|