76 lines
3.0 KiB
Markdown
76 lines
3.0 KiB
Markdown
# 抓大鹅 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 任务边界
|
||
|
||
前端只维护当前页面内的临时重新生成任务状态；草稿生成得到的正式模型资产从 `generatedItemAssets.modelSrc` 恢复：
|
||
|
||
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` 后手动验证。
|