docs(web): 任务说明、DSH 约束与交付文档

2026-09-14 19:00:55 +08:00
parent 5a8b77b0a4
commit b9215d4190
16 changed files with 1461 additions and 0 deletions
@@ -0,0 +1,49 @@
+# T-WEB-009 模型管理界面 + 来源展示
+
+- **状态**：done
+- **依赖**：T-WEB-005
+
+## 目标
+
+React 管理端的模型管理页面：列表、上传、**来源信息完整展示**、VRM 优先设置、
+3D 预览。
+
+## load
+
+```
+DSH.md
+contracts/rest-api.yaml          # 锚点：#/paths/~1api~1models
+contracts/data-models.md         # 锚点：§4 Model、§4.1 VRM 优先规则
+web-server/admin/src/pages/ModelsPage.tsx
+web-server/admin/src/components/VrmPreview.tsx
+```
+
+## 交付物
+
+| 路径 | 说明 |
+|---|---|
+| `src/pages/ModelsPage.tsx` | 模型列表 + 上传表单 + 设为默认 |
+| `src/components/VrmPreview.tsx` | three.js + @pixiv/three-vrm 的 3D 预览面板 |
+
+## 页面能力
+
+- 表格列：预览缩略图、名称、格式（VRM 高亮徽章）、VRM 版本、是否默认、
+  **来源五元组**、许可、状态、操作
+- **来源展示（本任务验收重点）**：整行展示 `sourceType` + `sourceName` + `author`
+  + `license`，`sourceUrl` 可点击外链跳转
+- 上传：`POST /api/models`（multipart `file` + 名称 + `isPrimary` + 来源五元组 +
+  状态），客户端校验与歌曲页一致
+- 「设为默认」→ `POST /api/models/:id/primary`，成功后刷新列表以反映互斥结果
+- 3D 预览：`GLTFLoader` + `VRMLoaderPlugin` 加载 `fileUrl`，
+  支持鼠标拖拽旋转与滚轮缩放，正确处理 VRM 0.x / 1.0 元数据差异、
+  未选择模型、加载失败三种状态，卸载时释放资源
+
+## 验收
+
+```bash
+cd web-server/admin
+npm run build     # 必须成功
+```
+
+另由 `npm run test:smoke`（[4] 段落）验证后端确实在列表接口返回完整来源字段，
+供本页面展示。