抓大鹅 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：

作品信息：承接封面、游戏名称、标签、简介。
玩法配置：承接题材、消除次数、难度、参考图与局内数量摘要。
3D素材：展示 Rodin 素材列表，点击列表项进入详情生成页。

3D素材 Tab 的列表布局参考 RPG 结果页角色列表：移动端纵向卡片，桌面端多列紧凑卡片；卡片展示素材名和状态。详情页只保留模型预览、素材名称和 重新生成 按钮。

3. Rodin 任务边界

前端只维护当前页面内的临时重新生成任务状态：

素材槽位名称。
模型预览。草稿生成的 /generated-match3d-assets/... GLB 必须通过同源 /api/assets/read-bytes 由后端换签并读取字节，前端再转成 Blob URL 后交给 Three.js GLTFLoader，避免浏览器直接 fetch OSS 签名 URL 时被 CORS 拦截。
图生模型参考图只作为重新生成的隐藏输入来源，不在详情页展示。上传图片在前端直接读成 Data URL；草稿生成的 /generated-match3d-assets/... 图片必须通过 /api/assets/read-bytes 转成 Data URL 后提交给 Hyper3D。
Hyper3D taskUuid 与 subscriptionKey。
查询到的状态、进度与下载文件列表。

正式资产链后续再接：

下载文件转存 OSS。
asset_object 确认。
asset_entity_binding 绑定到 Match3D 作品或物件槽位。

首版不得把上游下载 URL 直接写入 Match3D profile，也不得把 Data URL 持久化到 SpacetimeDB。

4. 接口复用

继续使用既有前端 client：

src/services/hyper3dModelGenerationService.ts

对应后端路由：

POST /api/assets/hyper3d/text-to-model
POST /api/assets/hyper3d/image-to-model
POST /api/assets/hyper3d/status
POST /api/assets/hyper3d/download

请求参数默认使用：

geometryFileFormat = glb
material = PBR
quality = medium
meshMode = Quad
previewRender = true
conditionMode = concat

5. 验收

建议执行：

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 后手动验证。

2.8 KiB Raw Blame History Unescape Escape