test(accept): 产物级端到端验收自动化 + 实体注册核对落到 dist（v0.7.4 实测全通过）

背景：`npm run verify` 跑的是源码与刚构建的 dist，而交付给部署方的是 `dist-release/*.tar.gz`；两者之间隔着「解包 → npm install --omit=dev → 迁移 → 起进程」四步。本项目三次生产事故（v0.7.0/v0.7.1 起不来、v0.7.3 场景上传 400、 v0.7.4 `No metadata for "Scene"`）全都只在产物真正跑起来时才暴露。一、`scripts/check-bootstrap.mjs` 新增「产物级实体注册核对」直接读包内 `dist/entities/`：逐个 import 每个 *.entity.js（@Entity() 装饰器在模块加载时写 metadata），要求 * 每个实体文件里被 @Entity() 装饰的类都在 ENTITIES 里； * ENTITIES 里不允许有未装饰的成员；不允许重复； * Scene 必须注册（点名）。为什么必须单独有这一条：漏注册实体**不影响启动**（TypeORM 只按 ENTITIES 注册， DI 图照样解析、/health 正常、migrationsPending 0），只在第一次查该实体时抛 `No metadata`，导致 /api/scenes、/api/catalog/export、/api/catalog/version、 /api/reviews?status=pending 全部 500 —— 客户端一个目录都拉不到。原来的启动冒烟与 entities-registry.spec.ts（查 src/）都抓不到它。反向验证（在真实 v0.7.4 发布包里复现生产缺陷）：把包内 dist/entities/index.js 的 ENTITIES 去掉 Scene 后，核对立即失败并给出「scene.entity.js 里的 Scene 没有注册进 ENTITIES」与「ENTITIES 里没有 Scene」；还原后通过。二、`scripts/accept-release.sh`（新增）：一个 tar.gz 的产物级端到端验收解包 → 装生产依赖 → 跑迁移 → 起服务 → 校验 /health 关键字段（版本 / 数据库 / migrationsPending / scenes.available）→ 产物级实体注册核对（用仓库当前的 checker 覆盖包内旧版本，验收标准以最新为准）→ 跑发布包自带的 test/smoke.mjs → 停服务。只需要一个现成的 MySQL/MariaDB，不装数据库（与项目「不部署 MySQL」的边界一致）。实测（opendance-web-v0.7.4.tar.gz + 真实 MySQL 9.7.2，全新库从零迁移）： ✓ /health version=0.7.4 与 package.json 一致 ✓ 数据库已连接（opendance_accept，pending=0） ✓ scenes.available=true（生产 v0.7.3 是 false + No metadata） ✓ 产物级实体注册核对通过：6 个实体文件全部注册进 ENTITIES（含 Scene） == 结果：80 通过 / 0 失败 == 冒烟 [7] 段即 ④ 验收：POST /api/scenes 201、一律 pending、GLB 直传不重编码、 glbUrl 生成、重力/风/摩擦/坡度/出生点/相机模式按配置原样入库、越界夹紧与非法枚举回退、审核通过后 catalog/export 的 scenes[] 带完整物理参数与 GLB/缩略图字段、目录指纹纳入场景变更、详情、状态过滤、DELETE 204。 `npm run verify` 全绿：契约 6 项 / 35 路由 / 版本一致 / 295 项测试 / build / 产物级注册核对 / 启动冒烟。
2026-09-17 04:44:30 +08:00
parent 2da02ee423
commit 06b476c4e2
3 changed files with 379 additions and 1 deletions
@@ -177,3 +177,68 @@ TypeORM 的 DataSource **只按 `ENTITIES` 注册 metadata**，漏注册的后
 * 核对 `AddScenes` 迁移文件确实存在（迁移文件缺失时 `showMigrations()` 仍会显示 0 个待执行）。

 这类"漏注册"既过得了 `tsc`，也过得了启动冒烟（应用能启动），因此**只能靠静态核对兜住**。
+
+## 产物级端到端验收（v0.7.4 发布包实测）
+
+上面那条"只能靠静态核对兜住"其实**还不够**：静态核对查的是 `src/`，
+而交付给部署方的是 `dist-release/*.tar.gz`。两者之间隔着
+「解包 → npm install --omit=dev → 迁移 → 起进程」四步，
+`nest build` 没重编译、打包带了旧的 `dist/` 都会让校验全绿而产物仍是坏的。
+
+因此补了两层，并把整条验收自动化：
+
+### 1. 产物级实体注册核对（`scripts/check-bootstrap.mjs` 新增一段）
+
+直接读**产物**里的 `dist/entities/`：逐个 `import` 每个 `*.entity.js`
+（`@Entity()` 装饰器在模块加载时写 metadata），要求
+
+- 每个实体文件里被 `@Entity()` 装饰的类都在 `ENTITIES` 里；
+- `ENTITIES` 里不允许出现没有 `@Entity()` 装饰的成员；
+- `ENTITIES` 不允许重复；
+- `Scene` 必须注册（点名，便于一眼看出是不是又漏了场景）。
+
+原先的启动冒烟只证明"DI 图可解析"，而**漏注册实体恰恰不影响启动** ——
+所以这条必须单独存在。已接入 `npm run verify`。
+
+**反向验证**（在真实 v0.7.4 发布包里复现生产缺陷）：把产物
+`dist/entities/index.js` 的 `ENTITIES` 去掉 `Scene` 后：
+
+```
+✗ 产物级实体注册核对失败（dist/entities 与 ENTITIES 不一致）：
+  - scene.entity.js 里的 Scene 没有注册进 ENTITIES —— 查询该实体会抛
+    `No metadata for "..." was found.`（接口直接 500）
+  - ENTITIES 里没有 Scene —— 场景管理相关接口会全部 500（生产事故根因）
+退出码=1
+```
+
+### 2. 发布包级端到端验收（`scripts/accept-release.sh`，新增）
+
+对一个 tar.gz 一键跑完：解包 → 装生产依赖 → 迁移 → 起服务 → 检查
+`/health` 关键字段（版本 / 数据库 / `migrationsPending` / **`scenes.available`**）
+→ 产物级实体注册核对 → 跑**发布包自带的** `test/smoke.mjs` → 停服务。
+需要一个可连的 MySQL/MariaDB（脚本不装数据库，与项目边界一致）。
+
+```bash
+DB_HOST=127.0.0.1 DB_PORT=3306 DB_USER=opendance DB_PASS=*** DB_NAME=opendance_accept \
+  ASSIMP_BIN=/usr/bin/assimp bash scripts/accept-release.sh dist-release/opendance-web-v0.7.4.tar.gz
+```
+
+**实测（v0.7.4 发布包 + 真实 MySQL 9.7.2）**：
+
+```
+✓ /health 的 version=0.7.4 与 package.json 的 0.7.4 一致
+✓ 数据库已连接（opendance_accept，pending=0）
+✓ 没有未执行的迁移
+✓ scenes.available=true（false 时 error=null）
+✓ 产物级实体注册核对通过：dist/entities/ 下 6 个实体文件全部注册进 ENTITIES（含 Scene）
+== 结果：80 通过 / 0 失败
+产物级验收全部通过
+```
+
+其中冒烟的 `[7]` 段就是本任务的验收：`POST /api/scenes` 201、一律 `pending`、
+GLB 直传不重编码、`glbUrl` 生成、**重力/风/地面摩擦/坡度/出生点/相机模式按配置原样入库**、
+越界值夹紧与非法枚举回退、审核通过后 `catalog/export` 的 `scenes[]` 带完整物理参数与
+GLB/缩略图字段、**目录指纹纳入场景变更**、`GET /api/scenes/:id`、按状态过滤、`DELETE` 204。
+
+> 这一步同时排除了「Linux 上导出/打包产物与源码不一致」的可能：
+> 跑的是发布包里**自带的** `dist/`、`scripts/`、`test/`，不是仓库源码。