From 203dcd8a9cd608974751dda3cf45739eab18e384 Mon Sep 17 00:00:00 2001
From: zijunchiang <miyu@kasugano.cn>
Date: Tue, 15 Sep 2026 21:18:21 +0800
Subject: [PATCH] =?UTF-8?q?chore(contracts):=20=E5=90=8C=E6=AD=A5=20rest-a?=
 =?UTF-8?q?pi=EF=BC=88=E6=96=B0=E5=A2=9E=20POST=20/api/models/{id}/reanaly?=
 =?UTF-8?q?ze=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 contracts/rest-api.yaml | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/contracts/rest-api.yaml b/contracts/rest-api.yaml
index 2971303..66dc71b 100644
--- a/contracts/rest-api.yaml
+++ b/contracts/rest-api.yaml
@@ -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: