# 无限画布 3D 生成（Tripo3D）开发文档

## 0. 文档信息

- 文档版本：v1.0（开发方案）
- 编写日期：2026-02-28
- 适用项目：`ai-chatbot-main`（Next.js + 无限画布）
- 目标：在无限画布左侧工具栏新增「3D生成」入口，并新增独立 3D 生成页面，接入 Tripo3D OpenAPI，实现文生3D/图生3D并回流到画布节点

---

## 1. 背景与目标

当前无限画布已支持图片、视频、文本、实时画布等工作流，但缺少 3D 资产生产能力。新增 3D 生成能力后，用户可在同一工作空间内完成：

1. 文案到 3D（Text to 3D）
2. 图片到 3D（Image to 3D）
3. 3D 资产预览、格式转换、导入画布、下载复用

本次先完成「文档先行」：明确 API、架构、页面、数据流、错误处理、安全与验收标准，为后续编码提供统一基线。

---

## 2. Tripo3D API 研究结论（用于接入实现）

## 2.1 基础信息

- Base URL：`https://api.tripo3d.ai/v2/openapi`
- 鉴权：`Authorization: Bearer <TRIPO_API_KEY>`
- 通用响应结构：
  - 成功：`{ code: 0, data: ... }`
  - 失败：`{ code: 非0, message, suggestion }`
- 响应头可包含追踪字段：`X-Tripo-Trace-ID`

## 2.2 本项目相关接口

| 能力 | 方法 | 路径 | 用途 |
|---|---|---|---|
| 创建任务 | POST | `/task` | 发起 text_to_model / image_to_model / convert_model 等任务 |
| 查询任务 | GET | `/task/{task_id}` | 轮询任务状态与输出 |
| 上传图片（STS） | POST | `/upload/sts` | 图生3D前上传参考图并获取 token |
| STS Token | POST | `/upload/sts/token` | 进阶上传流程（S3 直传） |
| 查询余额 | GET | `/user/balance` | 展示可用额度 |

## 2.3 任务类型（本期聚焦）

- `text_to_model`（MVP 必做）
- `image_to_model`（MVP 必做）
- `convert_model`（MVP 建议做：统一为 GLB/GLTF）
- `refine_model`（V1.1）
- `multiview_to_model`（V1.1）

## 2.4 任务状态

- 进行中：`queued`、`running`
- 结束态：`success`、`failed`、`banned`、`expired`、`cancelled`、`unknown`

建议前端状态映射：

- `queued/running` -> `generating`
- `success` -> `completed`
- 其他结束态 -> `failed`

## 2.5 输出字段（按可用性优先级）

任务成功后输出可能在以下字段出现：

1. `pbr_model`
2. `model`
3. `base_model`
4. `generated_image`（预览图）
5. `rendered_image`（预览图）

建议导入画布时优先选择：`pbr_model > model > base_model`。

## 2.6 已确认可选模型版本（写入产品文案与参数面板）

可用版本示例（官方文档中出现）：

- `Turbo-v1.0-20250506`（建议默认）
- `v3.1-20260211`
- `v3.0-20250812`
- `v2.5-20250123`
- `v2.0-20240919`
- `v1.4-20240625`（部分可能已废弃）

说明：模型版本可能变更，运行时应允许后台动态配置默认值与可选列表。

## 2.7 关键约束

- 速率与并发（文档值）：
  - Refine 并发上限：5
  - 其他任务并发上限：10
  - 图片上传：10 QPS
- 图片输入：
  - 格式：`webp | jpeg | png`
  - 尺寸：20~6000px（建议 >256px）
- 输出 URL 可能短时有效（文档提到默认较短有效期），不能只在前端缓存，建议尽快回存到自有存储

## 2.8 典型错误码（需做前端友好映射）

- `1002`：鉴权失败
- `1004`：参数错误
- `1007`：触发限流
- `2000`：超出限制
- `2001`：任务不存在
- `2002`：任务类型不支持
- `2004`：文件类型不支持
- `2008`：内容策略拦截
- `2010`：余额不足
- `2015`：模型版本废弃
- `2017`：模型版本无效

---

## 3. 业务范围定义

## 3.1 MVP（本期上线）

1. 无限画布左侧工具栏新增 `3D生成` 按钮
2. 新增页面：`/canvas/[id]/model3d`
3. 支持文生3D、图生3D
4. 支持任务轮询、结果预览、一键导入画布
5. 支持下载 3D 文件（至少 GLB/GLTF）
6. 错误态、超时态、重试机制可用

## 3.2 V1.1（增强）

1. refine_model 二次精修
2. 批量任务队列与历史检索
3. 多格式导出（USDZ/FBX/OBJ/STL/3MF）
4. 3D 资产库与复用

---

## 4. 现有系统接入点（基于当前代码）

已确认关键文件：

- 画布主页面：`/Users/lanmu/Desktop/ai-chatbot-main/app/canvas/[id]/page.tsx`
- 画布工作区：`/Users/lanmu/Desktop/ai-chatbot-main/components/canvas/CanvasWorkspace.tsx`
- 画布状态：`/Users/lanmu/Desktop/ai-chatbot-main/store/canvas/index.ts`
- 节点类型定义：`/Users/lanmu/Desktop/ai-chatbot-main/types/canvas/index.ts`
- 现有独立功能页范式（实时画布）：`/Users/lanmu/Desktop/ai-chatbot-main/app/canvas/[id]/realtime/page.tsx`
- 全局设计 Token：`/Users/lanmu/Desktop/ai-chatbot-main/app/globals.css`

当前节点类型暂不含 3D，需扩展：

- 现状：`message | image | video | text | scene-fusion`
- 新增：`model3d`

项目已具备 3D 渲染依赖（无需新增核心依赖）：

- `three`
- `@react-three/fiber`
- `@react-three/drei`

---

## 5. 页面与交互设计（参考图布局 + 站内 UI 规范）

## 5.1 页面路由

- 新页面：`/canvas/[id]/model3d`
- 从画布侧栏按钮进入；关闭后返回 `/canvas/[id]`

## 5.2 结构分区（桌面端）

- 顶部：轻量标题栏（返回、项目名、余额、帮助）
- 左侧参数区（约 320px）：
  - 生成模式切换：文生3D / 图生3D
  - Prompt 输入
  - 参考图上传（图生3D）
  - 高级参数折叠（模型版本、面数、贴图、PBR、seed）
  - 主按钮：开始生成
- 中央预览区（主视觉）：
  - 3D Viewer（OrbitControls）
  - 状态覆盖层（排队中/生成中/失败）
  - 结果操作（导入画布、下载、重新生成）
- 右侧任务区（约 300px）：
  - 当前任务状态卡
  - 最近任务历史（可重开结果）
  - 输出资源信息（格式、大小、创建时间）

## 5.3 视觉规范（必须遵循站内风格）

使用现有 Token，不复制参考图配色：

- 背景：`bg-background`
- 卡片：`bg-card border`
- 主色：`bg-primary text-primary-foreground`
- 辅助文本：`text-muted-foreground`
- 圆角：与现有画布一致（`rounded-xl/2xl`）
- 毛玻璃与阴影：沿用 `backdrop-blur` + `shadow-sm/2xl`

## 5.4 移动端策略

- 左右栏折叠为抽屉（参数抽屉 + 任务抽屉）
- 中央 Viewer 全宽
- 关键操作固定底栏（生成 / 导入画布）

---

## 6. 系统架构设计

```mermaid
flowchart LR
  A["Canvas Sidebar: 3D生成"] --> B["/canvas/[id]/model3d 页面"]
  B --> C["Next.js API: /api/canvas/3d/*"]
  C --> D["Tripo OpenAPI"]
  D --> C
  C --> E["任务状态返回前端"]
  E --> B
  B --> F["导入画布 model3d 节点"]
  F --> G["CanvasStore + CanvasProject.canvasData"]
```

## 6.1 前端层

- 新建页面组件：`app/canvas/[id]/model3d/page.tsx`
- 新建 3D 业务组件（建议）：
  - `components/canvas/Model3DStudio.tsx`
  - `components/canvas/model3d/Model3DViewer.tsx`
  - `components/canvas/model3d/TaskHistoryPanel.tsx`
- 在 `app/canvas/[id]/page.tsx` 左侧工具栏新增入口按钮（图标建议 `Box`）

## 6.2 后端 API 代理层

新增接口（同域代理，隐藏 Tripo Key）：

1. `POST /api/canvas/3d/upload-image`
2. `POST /api/canvas/3d/tasks`
3. `GET /api/canvas/3d/tasks/[taskId]`
4. `GET /api/canvas/3d/balance`
5. `POST /api/canvas/3d/import`（可选，做导入封装）

## 6.3 Tripo 适配层

新增服务层（建议）：

- `lib/tripo/client.ts`：底层请求、鉴权头、trace-id 提取
- `lib/tripo/types.ts`：请求/响应类型
- `lib/tripo/mappers.ts`：错误码与状态映射

---

## 7. 详细数据流

## 7.1 文生3D流程

1. 前端提交 `prompt + modelVersion + params`
2. 后端 `POST /task`（`type=text_to_model`）
3. 返回 `taskId`
4. 前端轮询 `GET /api/canvas/3d/tasks/[taskId]`
5. 成功后拿到模型 URL（优先 `pbr_model`）
6. 预览通过后点击「导入画布」
7. 生成 `model3d` 节点并持久化画布

## 7.2 图生3D流程

1. 上传参考图到后端
2. 后端调用 Tripo `POST /upload/sts`，拿到 image token
3. 后端 `POST /task`（`type=image_to_model`）
4. 后续轮询与导入同上

## 7.3 轮询策略

- 初始间隔：2s
- 单任务最大时长：8~10 分钟（可配置）
- 超时处理：标记失败并提示可重试
- 页面离开后自动停止轮询

---

## 8. 内部 API 合同（建议定稿）

## 8.1 `POST /api/canvas/3d/upload-image`

请求：`multipart/form-data`（file）

响应：

```json
{
  "success": true,
  "data": {
    "imageToken": "xxxx",
    "source": "tripo-sts"
  }
}
```

## 8.2 `POST /api/canvas/3d/tasks`

请求（文生）：

```json
{
  "taskType": "text_to_model",
  "prompt": "a cute toy robot",
  "modelVersion": "Turbo-v1.0-20250506",
  "faceLimit": 120000,
  "texture": true,
  "pbr": true
}
```

请求（图生）：

```json
{
  "taskType": "image_to_model",
  "imageToken": "xxxx",
  "modelVersion": "Turbo-v1.0-20250506",
  "faceLimit": 120000,
  "texture": true,
  "pbr": true
}
```

响应：

```json
{
  "success": true,
  "data": {
    "taskId": "task_xxx",
    "status": "queued"
  }
}
```

## 8.3 `GET /api/canvas/3d/tasks/[taskId]`

响应（成功）：

```json
{
  "success": true,
  "data": {
    "taskId": "task_xxx",
    "status": "success",
    "outputs": {
      "modelUrl": "https://...",
      "previewImageUrl": "https://..."
    },
    "raw": {}
  }
}
```

响应（失败）：

```json
{
  "success": false,
  "error": "余额不足",
  "code": 2010,
  "retryable": false
}
```

## 8.4 `GET /api/canvas/3d/balance`

```json
{
  "success": true,
  "data": {
    "balance": 123.45,
    "unit": "credits"
  }
}
```

---

## 9. 无限画布节点扩展方案

## 9.1 类型定义

更新 `types/canvas/index.ts`：

- `NodeType` 新增 `model3d`
- 新增 `Model3DNodeData`：
  - `src`（模型地址）
  - `previewImage?`
  - `format`（glb/gltf/usdz/fbx/obj...）
  - `prompt?`
  - `modelVersion?`
  - `status`
  - `metadata`（faceLimit、texture、seed、taskId、traceId 等）

## 9.2 组件渲染

- 新增：`components/canvas/nodes/Model3DNode.tsx`
- 更新：`components/canvas/CanvasWorkspace.tsx` 渲染分支
- 节点交互：
  - 预览缩略图
  - 下载
  - 复制链接
  - 删除
  - 在新窗口查看 3D

## 9.3 数据持久化

MVP 可不加新表，直接利用现有 `CanvasProject.canvasData` JSON 存储节点。

V1.1 如需任务历史和统计，可新增 `Canvas3DTask` 表。

---

## 10. 后端安全与配置

## 10.1 鉴权与密钥

- Tripo API Key 仅保留在服务端（`TRIPO_API_KEY`）
- 前端严禁直连 Tripo API
- 所有 `/api/canvas/3d/*` 必须校验登录态

## 10.2 输入约束

- 上传文件白名单：`image/png`, `image/jpeg`, `image/webp`
- 文件大小上限建议：10MB（可配置）
- prompt 长度限制（例如 500）

## 10.3 审计日志

每次调用记录：

- userId
- taskId
- taskType
- modelVersion
- tripo code / message
- `X-Tripo-Trace-ID`

---

## 11. 错误处理与降级策略

| 场景 | 检测 | 前端提示 | 系统动作 |
|---|---|---|---|
| API Key 无效 | code=1002 | 服务配置异常 | 终止任务并告警 |
| 速率限制 | code=1007 | 请求过于频繁，请稍后 | 指数退避重试 |
| 余额不足 | code=2010 | 余额不足，请充值 | 终止任务 |
| 模型版本失效 | code=2015/2017 | 当前模型不可用，已切换默认版本 | 自动回退默认模型 |
| 内容审核拦截 | code=2008 | 内容不符合规范 | 终止任务 |
| 任务超时 | 本地计时超阈值 | 生成超时，请重试 | 标记失败，可重提 |

---

## 12. 性能与可观测性

## 12.1 性能

- 限制单用户并发任务数（建议 2~3）
- 轮询仅对活跃任务执行
- 3D 预览默认启用轻量灯光与压缩纹理，避免页面卡顿

## 12.2 可观测性

- API 耗时埋点：upload/create/poll/import
- 失败率指标：按任务类型、模型版本、错误码聚合
- 成功耗时 P50/P90/P99

---

## 13. 研发排期（建议）

## 阶段 A（1~2 天）：后端通路

1. Tripo client + API 代理路由
2. 上传、创建任务、轮询、余额接口
3. 错误映射和日志

## 阶段 B（1~2 天）：前端页面与交互

1. 新建 `/canvas/[id]/model3d`
2. 三栏式页面 + 3D Viewer
3. 任务状态与结果操作

## 阶段 C（1 天）：画布集成与验收

1. 左侧工具栏新增 3D 入口
2. `model3d` 节点落盘与展示
3. 全链路联调 + 回归测试

---

## 14. 验收标准（Definition of Done）

1. 用户可从无限画布一键进入 3D 生成页
2. 文生3D与图生3D至少各成功 10 次，成功率 >= 95%（测试环境）
3. 生成成功后 1 次点击可导入画布，并在刷新后仍保留节点
4. 失败场景提示清晰，不出现无响应状态
5. 页面风格符合站内 UI 规范（Token、按钮、间距、圆角、暗黑模式）

---

## 15. 参考文档

- Tripo 文档入口：<https://platform.tripo3d.ai/docs/introduction>
- Tripo OpenAPI Base：<https://api.tripo3d.ai/v2/openapi>

> 备注：Tripo 文档为动态站点，模型版本与限制可能变化；实现时应将默认版本、可选版本与限额做成后台可配置项，而不是硬编码。