181 lines
6.8 KiB
Markdown
181 lines
6.8 KiB
Markdown
# 后端架构图 — 文生图提示词
|
||
|
||
你是一位技术架构可视化专家。请根据以下描述，生成一张 **gen2d 后端架构详图**，风格：**技术文档风格，白色或浅灰背景，清晰的层次关系和连线**。
|
||
|
||
## 标题
|
||
|
||
gen2d Backend Architecture (Go + Gin + Eino)
|
||
|
||
## 整体布局
|
||
|
||
自上而下的分层架构图，共 5 层。
|
||
|
||
---
|
||
|
||
### 第 1 层：入口 (Entry Point)
|
||
|
||
```
|
||
cmd/main.go → 初始化 Config → 初始化 Logger → 初始化 DB → 注册路由 → 启动 HTTP Server (:8080)
|
||
```
|
||
|
||
用横向箭头串联的流程表示。
|
||
|
||
---
|
||
|
||
### 第 2 层：HTTP 层 (Handler + Middleware)
|
||
|
||
分为两个子块并排放置：
|
||
|
||
#### 左块：Middlewares (中间件链)
|
||
|
||
三个中间件纵向排列，用向下箭头串联：
|
||
1. **Logger Middleware** — 生成 X-Request-ID，记录 method/path/status/latency
|
||
2. **Auth Middleware** — JWT Bearer Token 校验，注入 UserID 到 context
|
||
3. **Recovery Middleware** — Panic 恢复 + 堆栈日志
|
||
|
||
#### 右块：Handlers (路由处理)
|
||
|
||
按路由分组展示：
|
||
|
||
| 路由前缀 | Handler | 说明 |
|
||
|---------|---------|------|
|
||
| `/health` | health.go | 健康检查 |
|
||
| `/auth/*` | register.go, login.go | 认证（独立路径） |
|
||
| `/api/v1/projects/*` | project handlers | 工程 CRUD + 风格管理 |
|
||
| `/api/v1/generate` | generate.go | 提交生成任务 |
|
||
| `/api/v1/tasks/*` | task handlers | 任务查询 + 素材获取 |
|
||
| `/api/v1/prompt/*` | prompt.go | 提示词优化 |
|
||
| `/api/v1/assets/*` | storage.go | 素材下载 (302 重定向) |
|
||
|
||
在 Handler 块内用小字标注：**"薄层: 仅参数绑定 + 校验 + 调用 Service + 返回统一响应"**
|
||
|
||
---
|
||
|
||
### 第 3 层：Service 层 (核心业务逻辑)
|
||
|
||
这是整个图的核心区域，占比最大。分为四个子块：
|
||
|
||
#### 3a. Pipeline 编排 (pipeline.go)
|
||
|
||
用流程图展示 Eino `compose.Graph` 的节点编排：
|
||
|
||
```
|
||
┌─────────────────┐
|
||
│ PipelineInput │ (user prompt + assetType + styles + params)
|
||
└────────┬────────┘
|
||
▼
|
||
┌──────────────────────┐
|
||
│ ① PromptOptimizer │ 合并工程风格 + 任务风格覆盖
|
||
│ 输出: 三段式提示词 │ 调用 LLM 生成规范化提示词
|
||
└──────────┬───────────┘
|
||
▼
|
||
┌──────────────────────┐
|
||
│ ② AssetGenerator │ OpenAI 兼容接口 /v1/images/generations
|
||
│ 输出: 原始图片列表 │ 支持多图生成 (n 参数)
|
||
└──────────┬───────────┘
|
||
▼
|
||
┌──────────────────────┐
|
||
│ ③ QualitySupervisor │ 视觉模型检查风格一致性
|
||
│ 输出: pass / fail │
|
||
└──────┬──────┬────────┘
|
||
│ │
|
||
pass fail (retry < 3) ──→ 回到 ① (RejectReason 回填)
|
||
│ │
|
||
│ fail (retry ≥ 3) ──→ 降级输出 ↓
|
||
▼ │
|
||
┌──────────────────────┐ │
|
||
│ ④ FormatAdapter │ ◄──────┘
|
||
│ spritesheet 打包 │
|
||
│ 上传七牛云 + 写 DB │
|
||
└──────────┬───────────┘
|
||
▼
|
||
┌──────────────────┐
|
||
│ PipelineOutput │ (assets[] + metadata)
|
||
└──────────────────┘
|
||
```
|
||
|
||
#### 3b. 节点实现 (nodes.go)
|
||
|
||
四个节点用一个表格或四个小卡片展示，每个卡片包含：
|
||
- **节点名称**
|
||
- Lambda 输入 → 输出 类型签名
|
||
- StatePreHandler / StatePostHandler 交互说明
|
||
|
||
| 节点 | 输入 → 输出 | State 交互 |
|
||
|------|-----------|-----------|
|
||
| PromptOptimizer | PipelineInput → string | Pre: 注入 RejectReason; Post: 写 FinalPrompt |
|
||
| AssetGenerator | string → []Image | Post: 写 RawImages |
|
||
| QualitySupervisor | []Image → bool | Post: 写 PassQuality, RejectReason, RetryCount |
|
||
| FormatAdapter | []Image → PipelineOutput | 无 State 交互，直接输出 |
|
||
|
||
#### 3c. 类型定义 (types.go)
|
||
|
||
一个小卡片展示三个核心结构体的字段：
|
||
- **PipelineInput**：Prompt, AssetType, ProjectStyle, TaskStyle, Params
|
||
- **PipelineState**：Input, FinalPrompt, RawImages, PassQuality, RejectReason, RetryCount
|
||
- **PipelineOutput**：Assets[], Metadata
|
||
|
||
#### 3d. 辅助 Service
|
||
|
||
并排两个小块：
|
||
- **auth.go**：注册 / 登录 / JWT 签发 (HS256) / Token 校验
|
||
- **storage.go**：七牛云上传 (token 鉴权) / 下载 URL 生成 / 删除
|
||
- **inference.go**：AI API 调用封装 (文生图 + 图片编辑)
|
||
- **prompt_agent.go**：LLM 提示词优化 Agent (OpenAI 兼容 Chat Completions, 含回退模板)
|
||
|
||
---
|
||
|
||
### 第 4 层：数据访问层
|
||
|
||
- **db.go**：GORM SQLite 连接初始化 + 自动建表 (CREATE TABLE IF NOT EXISTS)
|
||
- **cache.go**：sync.Map 内存缓存，用于请求去重 (hash → taskId)
|
||
- **config.go**：环境变量读取 + 配置结构体
|
||
|
||
---
|
||
|
||
### 第 5 层：外部依赖 (底部并排)
|
||
|
||
1. **SQLite** (`data/gen2d.db`)
|
||
- 5 张表：user, project, project_style, task, asset
|
||
- ER: user 1→N project 1→1 project_style, project 1→N task 1→N asset
|
||
- 全部 CASCADE 删除
|
||
|
||
2. **七牛云 Kodo**
|
||
- Bucket 存储 Key 格式：`users/{uid}/projects/{pid}/tasks/{tid}/output/{file}`
|
||
- CDN URL + 签名参数 (默认 3600s 过期)
|
||
|
||
3. **LLM API (外部)**
|
||
- OpenAI 兼容 `/v1/images/generations` — 文生图
|
||
- OpenAI 兼容 `/v1/chat/completions` — 提示词优化
|
||
- 可替换模型提供商
|
||
|
||
---
|
||
|
||
## 色彩与排版指南
|
||
|
||
- **标题横幅**：深蓝 (#1E3A5F)，白色文字
|
||
- **第 2 层 (Handler)**：浅蓝 (#E8F4FD)，深蓝边框
|
||
- **第 3 层 (Service)**：浅绿 (#E6F7EE)，深绿边框 — 这是核心层，用稍大的面积
|
||
- **管线节点**：用不同深浅绿色区分：
|
||
- ① 浅绿 #D1FAE5
|
||
- ② 中绿 #A7F3D0
|
||
- ③ 中绿 #6EE7B7
|
||
- ④ 深绿 #34D399
|
||
- **第 4 层 (Data)**：浅黄 (#FEF3C7)，深黄边框
|
||
- **第 5 层 (External)**：浅灰 (#F3F4F6)，深灰边框
|
||
- **箭头颜色**：
|
||
- 正常流程：实线 绿色
|
||
- 重试/回退：虚线 橙色
|
||
- 降级路径：虚线 红色
|
||
|
||
- 文字：sans-serif，英文为主，括号内中文辅助说明
|
||
- 所有框使用圆角 (border-radius: 8px)
|
||
- 层与层之间用虚线分隔，标注层名称在左侧
|
||
|
||
## 附加约束
|
||
|
||
- 保持技术文档风格，干净利落
|
||
- 所有组件名称与代码库中的实际命名一致 (pipeline.go, nodes.go, types.go 等)
|
||
- 画面比例 3:4 或 A4 竖版比例，适合放入文档
|
||
- 不要使用 3D 效果或过度装饰
|