# 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` 验证启动日志里的版本号。