# 抓大鹅 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` 后手动验证。