feat(models): 新增历史模型回填(reanalyze)并修复存储去重的悬挂文件问题

背景:升级到带 models.stats 的版本后,库里已有模型没有分析与缩略图,
审核界面会全部显示"未分析、无预览图"。E2E 验证时还发现一个真问题:
sha256 去重命中旧资产但文件不存在(换过 STORAGE_DIR、或只恢复数据库)时,
分析会静默产出"全 0 结果"。

- POST /api/models/:id/reanalyze:重新分析(面数/骨骼树/humanoid/可驱动性)
  并重建缩略图,只改 stats 与 thumbnailAssetId;文件在存储中不存在时返回 409,
  避免用空结果覆盖已有分析数据
- scripts/reanalyze-models.mjs:批量回填 CLI(--dry-run / --model-id / --force)
- StorageService.persistBuffer:去重命中但文件不存在时按原路径**自愈补写**
- 契约:rest-api 新增 /api/models/{id}/reanalyze(路由 29 → 30 条)
- 文档:README / tasks/005 / 发布说明补回填章节与升级步骤

实测:真实 21MB VRM(290 骨骼)回填出面数 53552 / 顶点 44662 / humanoid 7/22,
并重建 512×512 缩略图;文件缺失场景返回 409 且不覆盖既有数据。
测试 168 项通过;契约与 30 条路由一致。
This commit is contained in:
2026-09-15 21:18:15 +08:00
parent 53bf182476
commit c342a804a1
8 changed files with 210 additions and 4 deletions
+19
View File
@@ -398,6 +398,25 @@ paths:
responses:
'204': { description: 已删除 }
/api/models/{id}/reanalyze:
parameters: [{ $ref: '#/components/parameters/Id' }]
post:
tags: [models]
summary: 重新分析模型并重建缩略图(升级回填 / 文件替换后刷新)
description: |
重新计算 `stats`(面数、骨骼树、humanoid 覆盖、可驱动性)并重出缩略图,
只改这两个字段。用于:升级到带 `stats` 的版本后回填历史模型、
模型文件被替换后刷新、缩略图渲染器升级后重出图。
批量回填用 `node scripts/reanalyze-models.mjs --url http://127.0.0.1:3000`。
responses:
'200':
description: 重新分析后的模型
content:
application/json:
schema: { $ref: '#/components/schemas/Model' }
'404': { $ref: '#/components/responses/NotFound' }
'409': { description: 模型没有文件资产,无法分析 }
/api/models/{id}/primary:
parameters: [{ $ref: '#/components/parameters/Id' }]
post: