fix(scenes): 场景表不可用不再拖垮整站（生产事故修复）+ 诊断脚本
现场（真实部署 v0.7.2）：数据库缺 scenes 表，于是
/api/scenes、/api/scenes/:id、/api/catalog/export、/api/catalog/version、
/api/reviews?status=pending 全部 500，而 /api/songs、/api/motions、/api/models
正常。后果不是"场景不可用"，而是客户端拉不到任何目录（Windows/Android 全废）、
管理端待审列表打不开。`/health` 却显示 database.connected=true、
migrationsPending=0 —— 因为 DataSource.showMigrations() 只比较**代码里加载到的**
迁移；部署的 dist 若缺 AddScenes.js，该迁移不在比较集合里，于是"没有待执行迁移"
但表不存在（最隐蔽的一种不一致）。
修复思路：契约与文档都写明「场景是可选资源」（没有可用场景时客户端回退内置空
场景），所以场景表的问题不允许影响与场景无关的功能 —— 改为降级：
- ScenesService 新增 queryScenes() 包装：数据库层面失败时返回空结果，**只记一次
日志**（避免刷屏），原因写入 diagnostics()；下一次查询成功即自动复位；
- ReviewsService.listByStatus() 对场景查询单独 catch，待审列表照常返回其它资源；
- /health 新增 scenes: { available, error } —— 降级但绝不静默；
- HealthModule 增加 imports: [ScenesModule]（HealthController 注入了 ScenesService，
Nest 的 DI 按模块解析，漏了会直接 UnknownDependenciesException；
scripts/check-bootstrap.mjs 已能拦住这一类）。
新增 web-server/scripts/diagnose-scenes.mjs（默认只读）：打印运行期真实连的库、
表清单、typeorm_migrations 记录、**代码实际加载的迁移**、scenes 实际列 vs 实体
期望列的逐列 diff；`--fix` 仅在缺表时用迁移里同一份 DDL 幂等补表。
顺带修正 models.controller.ts 的误导性注释：模型上传**不接受** isPrimary/status
（契约：上传一律 pending，默认模型由审核通过时带 setPrimary=true 或
POST /api/models/:id/primary 设定）。test/smoke.mjs 此前正是按错误预期断言
"isPrimary 已置位"，已改为：上传断言 pending + isPrimary=false → 审核通过时带
setPrimary=true → 再断言 isPrimary=true；同时给目录导出/指纹等检查补上失败细节
（HTTP 状态 + 响应体），并把待审列表查询的 pageSize 放大到 200（避免库里待审项多
时新条目被挤出第一页）。
文档：README.md/.txt 增加 v0.7.3 修订说明；tasks/015-scene-management.md 增
「缺陷修复记录二」；开发文档 §4.12 补充硬性要求（场景不可用必须降级 + /health 暴露
+ showMigrations 的陷阱说明）。
测试：新增 test/scenes-degradation.spec.ts（6 项）；npm run verify 通过
（契约六项一致、35 条路由、21 文件 / 276 项测试、nest build、启动冒烟）；
发布产物解压后 npm ci --omit=dev + node dist/main.js 实测打印「应用版本 v0.7.3」。
注意：Gitea 附件上传通道仍故障（1 KB 也瞬时 500），因此本版**尚未上传 Release**，
产物先在本地交付（sha256 见 SHA256SUMS）。
This commit is contained in:
@@ -10,7 +10,31 @@ OpenDance Studio **阶段一**: Web 管理服务端(NestJS + TypeORM + 现有 My
|
||||
|
||||
## 状态
|
||||
|
||||
**阶段一已完成**: T-WEB-001 -> T-WEB-016 全部落地,当前版本 **v0.7.2**(契约 `rest-api 0.5.0`、`websocket-keypoints 0.2.0`、`data-models 0.7.0`、`model-formats 0.5.0`、`skeleton-topology 0.2.0`、`database 0.4.0`)。
|
||||
**阶段一已完成**: T-WEB-001 -> T-WEB-016 全部落地,当前版本 **v0.7.3**(契约 `rest-api 0.5.0`、`websocket-keypoints 0.2.0`、`data-models 0.7.0`、`model-formats 0.5.0`、`skeleton-topology 0.2.0`、`database 0.4.0`)。
|
||||
|
||||
v0.7.3 修订(**场景表不可用不再拖垮整站** —— 生产事故修复):
|
||||
|
||||
1. **现场**:数据库里没有 `scenes` 表(迁移没落到该库 / 部署的 dist 里缺迁移文件),于是
|
||||
`GET /api/scenes`、`/api/catalog/export`、`/api/catalog/version`、
|
||||
`/api/reviews?status=pending` **全部 500**,而 `/api/songs`、`/api/models` 正常。
|
||||
后果是**客户端拉不到任何目录**(Windows/Android 都用不了)、管理端待审列表也打不开;
|
||||
2. **契约与文档都写明「场景是可选资源」**(没有可用场景时客户端回退内置空场景),所以
|
||||
场景表不可用**不应该**连带打挂与场景无关的功能。本次改为**降级**:
|
||||
* `ScenesService` 新增 `queryScenes()` 包装:数据库层面失败时返回空结果、
|
||||
**只记一次日志**(避免刷屏),并把原因记在 `diagnostics()` 里;
|
||||
* 表恢复后自动回到可用状态(下一次成功查询即清除降级标记);
|
||||
* `ReviewsService.listByStatus()` 对场景查询单独 catch,待审列表照常返回其它资源;
|
||||
* `/health` 新增 `scenes: { available, error }` —— **降级但绝不静默**;
|
||||
3. **新增诊断脚本** `web-server/scripts/diagnose-scenes.mjs`(默认只读):
|
||||
打印运行期真实连的库、表清单、`typeorm_migrations` 记录、**代码实际加载的迁移**
|
||||
(用于识别"迁移没被加载 → `/health` 显示 pending 0 但表不存在"这种最隐蔽的情况)、
|
||||
以及 `scenes` 实际列 vs 实体期望列的逐列 diff;`--fix` 仅在缺表时用迁移里
|
||||
同一份 DDL 幂等补表;
|
||||
4. 顺带修正 `models.controller.ts` 里一句误导性注释:模型上传**不接受**
|
||||
`isPrimary`/`status`(契约:上传一律 `pending`,默认模型由审核通过时带
|
||||
`setPrimary=true` 或 `POST /api/models/:id/primary` 设定) —— 冒烟脚本此前正是
|
||||
按错误预期断言,已同步修正;
|
||||
5. 新增 6 项测试(`test/scenes-degradation.spec.ts`)锁定降级行为。
|
||||
|
||||
v0.7.2 修订(**修复产物"装得上、起不来"+ `/health` 报错版本号**):
|
||||
|
||||
@@ -131,15 +155,15 @@ v0.2.0 主要变更:
|
||||
3. 取得发布包并校验(**本仓库的真实发布地址**, 域名 `gitea.kasugano.cn`、属主 `zijunchiang` 属部署必需信息, 不是隐私项)
|
||||
|
||||
```bash
|
||||
curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.7.2/opendance-web-v0.7.2.tar.gz
|
||||
curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.7.2/SHA256SUMS
|
||||
curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.7.3/opendance-web-v0.7.3.tar.gz
|
||||
curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.7.3/SHA256SUMS
|
||||
sha256sum -c SHA256SUMS # 期望输出 "OK"
|
||||
```
|
||||
|
||||
4. 解压并生成配置(交互式引导,逐项问答,口令不回显)
|
||||
|
||||
```bash
|
||||
tar -xzf opendance-web-v0.7.2.tar.gz && cd opendance-web-v0.7.2
|
||||
tar -xzf opendance-web-v0.7.3.tar.gz && cd opendance-web-v0.7.3
|
||||
bash deploy/init-env.sh
|
||||
```
|
||||
|
||||
@@ -210,8 +234,8 @@ FLUSH PRIVILEGES;
|
||||
### 5. 部署步骤
|
||||
|
||||
```bash
|
||||
tar -xzf opendance-web-v0.7.2.tar.gz
|
||||
cd opendance-web-v0.7.2
|
||||
tar -xzf opendance-web-v0.7.3.tar.gz
|
||||
cd opendance-web-v0.7.3
|
||||
bash deploy/init-env.sh # 首次启动引导: 逐项问答生成 deploy/.env(见下)
|
||||
bash deploy/install.sh # 已以 root 登录, 不需要 sudo
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user