# 后端架构图 — 文生图提示词

你是一位技术架构可视化专家。请根据以下描述，生成一张 **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 效果或过度装饰