1

docs/technical/MATCH3D_RODIN_ASSET_TAB_2026-05-10.md

@@ -0,0 +1,75 @@
+# 抓大鹅 Rodin 3D 素材 Tab 接入方案 2026-05-10
+
+## 1. 范围
+
+本方案用于把抓大鹅结果页调整为多 Tab 工作台，并新增 `3D素材` Tab。该 Tab 专门服务抓大鹅玩法内物件、奖励、障碍等 3D 素材的 Rodin 生成试验。
+
+本次复用已有 Hyper3D Rodin Gen-2 后端安全代理，不新增 SpacetimeDB 表；草稿生成链路会把 Rodin 模型转存到 OSS，并通过 Match3D 作品 profile 的 `generatedItemAssets` 恢复。不得把 Hyper3D API Key、上游下载 URL 或本地 Data URL 写成正式资产真相。
+
+## 2. 页面结构
+
+抓大鹅结果页拆为三个 Tab：
+
+1. `作品信息`：承接封面、游戏名称、标签、简介。
+2. `玩法配置`：承接题材、消除次数、难度、参考图与局内数量摘要。
+3. `3D素材`：展示 Rodin 素材列表，点击列表项进入详情生成页。
+
+`3D素材` Tab 的列表布局参考 RPG 结果页角色列表：移动端纵向卡片，桌面端多列紧凑卡片；卡片展示素材名和状态。详情页只保留模型预览、素材名称和 `重新生成` 按钮。
+
+## 3. Rodin 任务边界
+
+前端只维护当前页面内的临时重新生成任务状态：
+
+1. 素材槽位名称。
+2. 模型预览。草稿生成的 `/generated-match3d-assets/...` GLB 必须通过同源 `/api/assets/read-bytes` 由后端换签并读取字节，前端再转成 Blob URL 后交给 Three.js GLTFLoader，避免浏览器直接 `fetch` OSS 签名 URL 时被 CORS 拦截。
+3. 图生模型参考图只作为重新生成的隐藏输入来源，不在详情页展示。上传图片在前端直接读成 Data URL；草稿生成的 `/generated-match3d-assets/...` 图片必须通过 `/api/assets/read-bytes` 转成 Data URL 后提交给 Hyper3D。
+4. Hyper3D `taskUuid` 与 `subscriptionKey`。
+5. 查询到的状态、进度与下载文件列表。
+
+正式资产链后续再接：
+
+1. 下载文件转存 OSS。
+2. `asset_object` 确认。
+3. `asset_entity_binding` 绑定到 Match3D 作品或物件槽位。
+
+首版不得把上游下载 URL 直接写入 Match3D profile，也不得把 Data URL 持久化到 SpacetimeDB。
+
+## 4. 接口复用
+
+继续使用既有前端 client：
+
+```text
+src/services/hyper3dModelGenerationService.ts
+```
+
+对应后端路由：
+
+```text
+POST /api/assets/hyper3d/text-to-model
+POST /api/assets/hyper3d/image-to-model
+POST /api/assets/hyper3d/status
+POST /api/assets/hyper3d/download
+```
+
+请求参数默认使用：
+
+```text
+geometryFileFormat = glb
+material = PBR
+quality = medium
+meshMode = Quad
+previewRender = true
+conditionMode = concat
+```
+
+## 5. 验收
+
+建议执行：
+
+```powershell
+npm run check:encoding
+npm run test -- src\components\match3d-result\Match3DResultView.test.tsx
+npm run typecheck
+```
+
+真实 Rodin 生成会消耗 Hyper3D Credit，只在本地私密环境配置 `HYPER3D_API_KEY` 或 `RODIN_API_KEY` 后手动验证。