From f61508a24964b51ade22b86bc4bf5b08a4d7e165 Mon Sep 17 00:00:00 2001 From: wonder Date: Mon, 25 May 2026 12:57:41 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E6=9E=B6=E6=9E=84?= =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=8C=E6=96=87=E4=BB=B6=E5=AD=98=E5=82=A8?= =?UTF-8?q?=E5=88=87=E6=8D=A2=E4=B8=BA=E4=B8=83=E7=89=9B=E4=BA=91=E5=AF=B9?= =?UTF-8?q?=E8=B1=A1=E5=AD=98=E5=82=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - _index.md: 技术栈加入七牛云对象存储 - api.md: 新增素材下载接口，asset URL 改为 CDN URL - backend.md: 分层结构新增 storage.go，FormatAdapter 职责增加上传 - database.md: 文件存储改为七牛云，配置表新增 GEN2D_QINIU_* 环境变量 --- docs/_index.md | 4 ++-- docs/api.md | 18 ++++++++++++++++-- docs/backend.md | 8 +++++--- docs/database.md | 47 ++++++++++++++++++++--------------------------- 4 files changed, 43 insertions(+), 34 deletions(-) diff --git a/docs/_index.md b/docs/_index.md index 2526eb6..b1a5453 100644 --- a/docs/_index.md +++ b/docs/_index.md @@ -4,13 +4,13 @@ gen2d — AI 驱动的 2D 游戏素材生成工具。通过文本提示词生成 ## 技术栈 -Go + Gin + Eino / Vite + React + TypeScript + zustand / SQLite / 可替换 AI 推理模型 +Go + Gin + Eino / Vite + React + TypeScript + zustand / SQLite / 七牛云对象存储 / 可替换 AI 推理模型 ## 文档索引 - [后端工程](backend.md) — 分层结构、管线设计（PromptOptimizer → AssetGenerator → QualitySupervisor → FormatAdapter）、风格模型 - [前端工程](frontend.md) — 组件树、状态管理、路由、WebSocket 通信 - [异步任务](async-tasks.md) — 任务队列、状态机、并发控制、失败重试 -- [数据存储](database.md) — SQLite 选型、表结构、本地文件存储 +- [数据存储](database.md) — SQLite 选型、表结构、七牛云对象存储 - [API 设计](api.md) — 接口列表、请求/响应示例、实现状态 - [预设风格键](style-keys.md) — 美术风格、色调、线条等风格键分类与可选值 diff --git a/docs/api.md b/docs/api.md index 74bf155..c06ffa7 100644 --- a/docs/api.md +++ b/docs/api.md @@ -300,7 +300,7 @@ POST /api/v1/prompt/optimize ### DELETE /api/v1/projects/:projectId -级联删除工程下的所有任务、素材及本地文件。 +级联删除工程下的所有任务、素材及七牛云对象。 响应： @@ -372,6 +372,7 @@ POST /api/v1/prompt/optimize | [ ] | GET | `/api/v1/tasks/:taskId` | 查询任务状态与进度 | | [ ] | GET | `/api/v1/tasks/:taskId/assets` | 获取生成结果（素材列表 + 元数据） | | [ ] | WS | `/api/v1/tasks/:taskId/ws` | WebSocket 实时进度推送 | +| [x] | GET | `/api/v1/assets/download` | 下载素材（重定向到 CDN） | ### POST /api/v1/generate @@ -483,7 +484,7 @@ POST /api/v1/prompt/optimize "assets": [ { "id": "asset_001", - "url": "users/user_a1B2c3D4/projects/proj_abc123/tasks/task_xyz789/output/spritesheet.png", + "url": "https://cdn.example.com/users/user_a1B2c3D4/projects/proj_abc123/tasks/task_xyz789/output/spritesheet.png", "format": "png", "width": 256, "height": 64, @@ -499,6 +500,19 @@ POST /api/v1/prompt/optimize } ``` +### GET /api/v1/assets/download + +需认证。返回 302 重定向到七牛云 CDN URL。 + +| 参数 | 类型 | 说明 | +|------|------|------| +| `key` | string | 对象存储 Key，查询参数 | + +响应： +- HTTP 302，`Location` 头指向 CDN URL +- 400：缺少 key 参数 +- 500：生成下载链接失败 + ### WebSocket 消息格式 连接路径：`ws://host/api/v1/tasks/:taskId/ws`（通过 httpOnly Cookie 自动携带认证信息） diff --git a/docs/backend.md b/docs/backend.md index 9a50263..947357e 100644 --- a/docs/backend.md +++ b/docs/backend.md @@ -16,7 +16,8 @@ backend/internal/ │ ├── login.go # [已有] 用户登录（handler 骨架 + 参数校验） │ ├── project.go # 工程 CRUD + 任务列表 │ ├── generate.go # 生成任务提交 / 查询 / WebSocket -│ └── project_style.go # 工程风格 CRUD +│ ├── project_style.go # 工程风格 CRUD +│ └── storage.go # [已有] 素材下载（重定向到七牛云 CDN） ├── service/ # 业务逻辑层 │ ├── pipeline.go # [已有] Eino compose.Graph 编排：PromptOptimizer → AssetGenerator → QualitySupervisor → FormatAdapter │ ├── nodes.go # [已有] 管线四个节点的实现（每个节点单一职责） @@ -24,7 +25,8 @@ backend/internal/ │ ├── inference.go # [已有] AI 推理 API 调用封装（当前为 mock 实现） │ ├── pipeline_test.go # [已有] 管线测试（happy path / 重试 / 降级 / 风格合并） │ ├── auth.go # 用户认证：注册、登录、JWT 签发与校验 -│ └── project_style.go # 工程风格管理 & 风格合并逻辑 +│ ├── project_style.go # 工程风格管理 & 风格合并逻辑 +│ └── storage.go # [已有] 七牛云对象存储：上传、下载 URL 生成、删除 ├── model/ # 数据模型 / DTO │ ├── response.go # [已有] 统一响应 │ ├── user.go # [已有] 用户模型 @@ -106,7 +108,7 @@ finalStyle = merge(projectStyle.KVPairs, taskStyle.KVPairs) - **输入**：通过质检的图片 + 素材类型 - **输出**：游戏引擎可用的素材文件 + 元数据 -- **职责**：格式转换、spritesheet 打包、元数据生成。 +- **职责**：格式转换、spritesheet 打包、元数据生成、上传素材到七牛云对象存储。 - **示例**：输入 4 张 64×64 的角色行走帧 PNG → 输出一张 256×64 的 spritesheet + JSON 元数据（帧尺寸、帧数、锚点偏移），可直接拖入 Unity 2D Animation 使用。 --- diff --git a/docs/database.md b/docs/database.md index 1658709..c5b7589 100644 --- a/docs/database.md +++ b/docs/database.md @@ -5,7 +5,7 @@ | 用途 | 方案 | 说明 | |------|------|------| | 持久化存储 | SQLite 3 | 工程、任务、素材元数据、风格配置全部落库，单文件部署 | -| 文件存储 | 本地文件系统 | 生成的图片与 spritesheet 文件保存到本地目录，通过 Gin 静态文件服务访问 | +| 文件存储 | 七牛云对象存储 | 生成的图片与 spritesheet 文件上传到七牛云 Bucket，通过 CDN URL 访问 | | 认证 | JWT + Cookie | 简单注册登录，httpOnly Cookie 鉴权 | | 缓存 / 去重 | 应用层内存 | 请求去重通过应用层 `sync.Map` 实现短期去重窗口，无需外部依赖 | @@ -133,44 +133,33 @@ task 1 ── N asset ## 文件存储 -生成的素材文件保存到本地文件系统，通过 Gin 静态文件服务访问。 +生成的素材文件上传到七牛云对象存储，通过 CDN URL 访问。 -### 目录结构 +### 存储结构 + +对象 Key 命名规则（与原有本地路径保持一致）： ``` -{dataDir}/ -└── users/ - └── {userId}/ - └── projects/ - └── {projectId}/ - └── tasks/ - └── {taskId}/ - ├── raw/ # AssetGenerator 输出的原始图片 - │ ├── 0.png - │ ├── 1.png - │ └── ... - ├── output/ # FormatAdapter 输出的最终素材 - │ ├── spritesheet.png - │ └── metadata.json - └── pipeline.log # 管线执行日志 +users/{userId}/projects/{projectId}/tasks/{taskId}/output/{filename} ``` -`dataDir` 通过环境变量 `GEN2D_DATA_DIR` 配置，默认 `./data`。 +示例： +``` +users/user_a1B2c3/projects/proj_abc/tasks/task_xyz/output/spritesheet.png +``` ### 访问方式 -Gin 静态文件服务，路由 `/files/*` 映射到 `{dataDir}/` 目录： +素材上传后返回 CDN URL，前端直接通过该 URL 访问图片。 -```go -router.Static("/files", dataDir) -``` +下载接口 `GET /api/v1/assets/download?key=...` 返回 302 重定向到 CDN URL。 ### asset 表的 url 字段 -存储相对路径，前端通过 `/files/{url}` 拼接访问： +存储七牛云 CDN 完整 URL，如： +`https://cdn.example.com/users/user_a1B2c3/projects/proj_abc/tasks/task_xyz/output/spritesheet.png` -- 如 `users/user_a1B2c3/projects/proj_abc/tasks/task_xyz/output/spritesheet.png` -- 前端拼接为 `/files/users/user_a1B2c3/projects/proj_abc/tasks/task_xyz/output/spritesheet.png` +前端直接使用该 URL 加载图片，无需拼接路径。 --- @@ -194,9 +183,13 @@ router.Static("/files", dataDir) |----------|--------|------| | `GEN2D_SERVER_PORT` | `8080` | HTTP 服务监听端口 | | `GEN2D_DB_PATH` | `./data/gen2d.db` | SQLite 数据库文件路径 | -| `GEN2D_DATA_DIR` | `./data` | 本地文件存储根目录 | | `GEN2D_JWT_SECRET` | — | JWT 签名密钥（必填） | | `GEN2D_JWT_EXPIRE` | `7200` | Token 过期时间（秒） | +| `GEN2D_QINIU_ACCESS_KEY` | — | 七牛云 AccessKey | +| `GEN2D_QINIU_SECRET_KEY` | — | 七牛云 SecretKey | +| `GEN2D_QINIU_BUCKET` | — | 七牛云 Bucket 名称 | +| `GEN2D_QINIU_CDN_HOST` | — | CDN 域名（如 `https://cdn.example.com`） | +| `GEN2D_QINIU_USE_HTTPS` | `true` | 是否使用 HTTPS | 在 `config.go` 中扩展字段即可，无需额外依赖。