docs: 更新架构文档，文件存储切换为七牛云对象存储

- _index.md: 技术栈加入七牛云对象存储 - api.md: 新增素材下载接口，asset URL 改为 CDN URL - backend.md: 分层结构新增 storage.go，FormatAdapter 职责增加上传 - database.md: 文件存储改为七牛云，配置表新增 GEN2D_QINIU_* 环境变量
2026-05-25 12:57:41 +08:00
parent 30a46ff74b
commit f61508a249
4 changed files with 43 additions and 34 deletions
@@ -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) — 美术风格、色调、线条等风格键分类与可选值
@@ -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 自动携带认证信息）
@@ -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 使用。

 ---
@@ -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` 中扩展字段即可，无需额外依赖。