Merge branch 'develop' of gitee.com:hezhaohui123/gen2d into feat/async-generate-pipeline
Signed-off-by: 何朝晖 <hezhaohui0807@163.com>
This commit is contained in:
Gitee
+2
-2
@@ -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) — 美术风格、色调、线条等风格键分类与可选值
|
||||
|
||||
+19
-5
@@ -300,7 +300,7 @@ POST /api/v1/prompt/optimize
|
||||
|
||||
### DELETE /api/v1/projects/:projectId
|
||||
|
||||
级联删除工程下的所有任务、素材及本地文件。
|
||||
级联删除工程下的所有任务、素材及七牛云对象。
|
||||
|
||||
响应：
|
||||
|
||||
@@ -368,10 +368,11 @@ POST /api/v1/prompt/optimize
|
||||
|
||||
| 状态 | 方法 | 路径 | 说明 |
|
||||
|------|------|------|------|
|
||||
| [ ] | POST | `/api/v1/generate` | 提交生成任务，返回 taskId |
|
||||
| [ ] | GET | `/api/v1/tasks/:taskId` | 查询任务状态与进度 |
|
||||
| [ ] | GET | `/api/v1/tasks/:taskId/assets` | 获取生成结果（素材列表 + 元数据） |
|
||||
| [x] | POST | `/api/v1/generate` | 提交生成任务，返回 taskId |
|
||||
| [x] | GET | `/api/v1/tasks/:taskId` | 查询任务状态与进度 |
|
||||
| [x] | 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 自动携带认证信息）
|
||||
|
||||
+59
-19
@@ -14,32 +14,32 @@ backend/internal/
|
||||
│ ├── health.go # [已有] 健康检查
|
||||
│ ├── register.go # [已有] 用户注册（handler 骨架 + 参数校验）
|
||||
│ ├── login.go # [已有] 用户登录（handler 骨架 + 参数校验）
|
||||
│ ├── project.go # 工程 CRUD + 任务列表
|
||||
│ ├── generate.go # 生成任务提交 / 查询 / WebSocket
|
||||
│ └── project_style.go # 工程风格 CRUD
|
||||
│ ├── generate.go # [已有] 素材生成（异步管线 + 任务查询）
|
||||
│ ├── edit.go # [已有] 图片编辑
|
||||
│ ├── prompt.go # [已有] 提示词优化
|
||||
│ └── storage.go # [已有] 素材下载（重定向到七牛云 CDN）
|
||||
├── service/ # 业务逻辑层
|
||||
│ ├── pipeline.go # [已有] Eino compose.Graph 编排：PromptOptimizer → AssetGenerator → QualitySupervisor → FormatAdapter
|
||||
│ ├── nodes.go # [已有] 管线四个节点的实现（每个节点单一职责）
|
||||
│ ├── types.go # [已有] 管线输入/状态/输出的显式结构体定义
|
||||
│ ├── inference.go # [已有] AI 推理 API 调用封装（当前为 mock 实现）
|
||||
│ ├── inference.go # [已有] AI 推理 API 调用封装（文生图 + 图片编辑）
|
||||
│ ├── prompt_agent.go # [已有] LLM 提示词优化 Agent
|
||||
│ ├── pipeline_test.go # [已有] 管线测试（happy path / 重试 / 降级 / 风格合并）
|
||||
│ ├── auth.go # 用户认证：注册、登录、JWT 签发与校验
|
||||
│ └── project_style.go # 工程风格管理 & 风格合并逻辑
|
||||
│ ├── auth.go # [已有] 用户认证：注册、登录、JWT 签发与校验
|
||||
│ └── storage.go # [已有] 七牛云对象存储：上传、下载 URL 生成、删除
|
||||
├── model/ # 数据模型 / DTO
|
||||
│ ├── response.go # [已有] 统一响应
|
||||
│ ├── user.go # [已有] 用户模型
|
||||
│ ├── task.go # 生成任务 & 素材
|
||||
│ └── style.go # 工程风格 & 任务风格覆盖
|
||||
├── middleware/ # 中间件
|
||||
│ ├── logger.go
|
||||
│ ├── auth.go # JWT 认证中间件（从 Cookie 读取 Token）
|
||||
│ └── ratelimit.go
|
||||
│ └── user.go # [已有] 用户模型
|
||||
├── mildware/ # 中间件
|
||||
│ ├── logger.go # [已有] 请求日志 + Panic 恢复中间件（基于 slog）
|
||||
│ └── auth.go # [已有] JWT 认证中间件
|
||||
├── logger/ # [已有] 日志包（基于 log/slog）
|
||||
│ └── logger.go # 日志初始化、全局 logger、context 注入
|
||||
├── config/ # [已有] 配置
|
||||
│ └── config.go
|
||||
├── queue/ # 异步任务队列
|
||||
│ └── jobqueue.go
|
||||
└── cache/ # 缓存层（请求去重）
|
||||
└── cache.go
|
||||
│ ├── config.go
|
||||
│ └── config.yml
|
||||
└── db/ # [已有] 数据库初始化
|
||||
└── db.go
|
||||
```
|
||||
|
||||
## 分层原则
|
||||
@@ -48,6 +48,46 @@ backend/internal/
|
||||
- **service**：承载所有业务逻辑。`pipeline.go` 通过 Eino `compose.Graph` 编排四个节点；`nodes.go` 实现各节点逻辑；`types.go` 定义显式状态结构体。
|
||||
- **model**：纯数据结构，不含业务逻辑。
|
||||
|
||||
## 日志系统
|
||||
|
||||
基于 Go 标准库 `log/slog`，无需第三方依赖。
|
||||
|
||||
### 核心组件
|
||||
|
||||
- **`internal/logger/logger.go`**：日志初始化与 context 注入
|
||||
- `Init(level, format)` — 初始化全局 logger（level: debug/info/warn/error，format: text/json）
|
||||
- `FromCtx(ctx)` — 从 context 提取带 request_id 的 logger
|
||||
- `WithRequestID(ctx, id)` — 创建带 request_id 的 logger 并存入 context
|
||||
|
||||
- **`internal/mildware/logger.go`**：HTTP 请求日志 + Panic 恢复中间件
|
||||
- `Logger()` — 为每个请求生成 request_id（注入 header `X-Request-ID`），记录 method/path/status/latency/client_ip
|
||||
- `Recovery()` — 自定义 panic 恢复，记录 request 上下文和堆栈
|
||||
|
||||
### 日志级别使用规范
|
||||
|
||||
| 级别 | 场景 |
|
||||
|------|------|
|
||||
| Debug | 开发调试信息 |
|
||||
| Info | 正常业务流程（API 调用、任务完成等） |
|
||||
| Warn | 可恢复的异常（认证失败、LLM 回退模板等） |
|
||||
| Error | 不可恢复的错误（API 调用失败、数据库错误等） |
|
||||
|
||||
### 配置
|
||||
|
||||
```yaml
|
||||
log:
|
||||
level: info # debug / info / warn / error
|
||||
format: text # text（开发）/ json（生产）
|
||||
```
|
||||
|
||||
环境变量：`GEN2D_LOG_LEVEL`、`GEN2D_LOG_FORMAT`
|
||||
|
||||
### 错误处理原则
|
||||
|
||||
- 服务端错误（5xx）：先用 `slog.Error` 记录完整错误（含 request_id），返回客户端通用描述
|
||||
- 客户端错误（4xx）：用 `slog.Warn` 记录，返回具体提示
|
||||
- 内部错误细节不泄露给客户端
|
||||
|
||||
## 多阶段生成管线
|
||||
|
||||
gen2d 的核心生成流程采用 Eino `compose.Graph` 编排的三阶段管线，含质检不通过时的重优化分支。
|
||||
@@ -106,7 +146,7 @@ finalStyle = merge(projectStyle.KVPairs, taskStyle.KVPairs)
|
||||
|
||||
- **输入**：通过质检的图片 + 素材类型
|
||||
- **输出**：游戏引擎可用的素材文件 + 元数据
|
||||
- **职责**：格式转换、spritesheet 打包、元数据生成。
|
||||
- **职责**：格式转换、spritesheet 打包、元数据生成、上传素材到七牛云对象存储。
|
||||
- **示例**：输入 4 张 64×64 的角色行走帧 PNG → 输出一张 256×64 的 spritesheet + JSON 元数据（帧尺寸、帧数、锚点偏移），可直接拖入 Unity 2D Animation 使用。
|
||||
|
||||
---
|
||||
|
||||
+20
-27
@@ -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` 中扩展字段即可，无需额外依赖。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user