# gen2d 架构设计

gen2d — AI 驱动的 2D 游戏素材生成工具。通过文本提示词生成风格一致、管线友好的 Sprite、背景、UI 元素与动画帧，无缝融入 Unity / Godot 等主流 2D 游戏引擎工作流。

## 技术栈

Go + Gin + Eino / Vite + React + TypeScript + zustand / SQLite / 七牛云对象存储 / 可替换 AI 推理模型

## 文档索引

| 文档 | 说明 |
|------|------|
| [后端工程](backend.md) | 分层结构、管线设计（PromptOptimizer → AssetGenerator → QualitySupervisor → FormatAdapter）、风格模型 |
| [前端工程](frontend.md) | 组件树、状态管理、路由、三栏工作台、自定义标签 |
| [API 设计](api.md) | 接口列表、请求/响应示例、错误码、认证 |
| [数据存储](database.md) | SQLite 选型、表结构、ER 关系、对象存储、去重策略 |
| [异步任务](async-tasks.md) | 任务生命周期、并发控制、重试策略、进度推送 |
| [预设风格键](style-keys.md) | 美术风格、色调、线条等风格键分类与可选值 |
| [架构图提示词](prompts/) | 全局/后端/前端架构图生成提示词，供多模态 AI 生成架构图 |
| [实施计划](PLAN.md) | 限流（令牌桶）、协程池、RabbitMQ 异步化的详细设计方案与实施步骤 |

## 系统架构

```
┌─────────────────────────────────────────────────────────┐
│                     Frontend (Vite + React)              │
│  ┌─────────┐ ┌──────────┐ ┌────────────┐ ┌──────────┐  │
│  │ 画廊页   │ │ 三栏工作台 │ │ 结果预览页  │ │ 登录注册  │  │
│  └─────────┘ └──────────┘ └────────────┘ └──────────┘  │
│                      │ HTTP / WebSocket                  │
└──────────────────────┼──────────────────────────────────┘
                       │
┌──────────────────────┼──────────────────────────────────┐
│                 Backend (Go + Gin + Eino)                │
│                      │                                   │
│  ┌───────────────────▼──────────────────────────────┐   │
│  │              Eino compose.Graph                    │   │
│  │  ┌──────────────┐  ┌──────────────┐               │   │
│  │  │PromptOptimizer│─▶│AssetGenerator│               │   │
│  │  └──────────────┘  └──────────────┘               │   │
│  │          ▲                 │                       │   │
│  │          │    ┌────────────▼──────────┐            │   │
│  │          │    │  QualitySupervisor    │            │   │
│  │          │    └────────────┬──────────┘            │   │
│  │          │          pass   │  fail (retry < 3)      │   │
│  │          └────────────────┘                        │   │
│  │          fail, retry ≥ 3                           │   │
│  │                    │  ┌──────────────┐              │   │
│  │                    └─▶│FormatAdapter │              │   │
│  │                       └──────────────┘              │   │
│  └────────────────────────────────────────────────────┘  │
│                      │                                   │
│         ┌────────────┼────────────┐                      │
│         │            │            │                      │
│    ┌────▼───┐  ┌─────▼────┐ ┌───▼──────┐               │
│    │ SQLite  │  │ 七牛云 Kodo│ │ LLM API  │               │
│    └────────┘  └──────────┘ └──────────┘               │
└─────────────────────────────────────────────────────────┘
```

## 核心概念

### 生成管线（Pipeline）

基于 Eino `compose.Graph` 的四阶段管线。每个阶段是一个 Lambda 节点，通过 `StatePreHandler` / `StatePostHandler` 读写全局状态。质检不通过时，Graph 分支自动触发重优化，最多重试 3 次，超过后降级输出保证任务不阻塞。

详见 [后端工程](backend.md#多阶段生成管线)。

### 风格系统（Style）

风格分为两层：

- **工程风格（Project Style）**：工程级别的 kvPairs，保证同一工程下所有素材风格一致
- **任务风格覆盖（Task Style Override）**：单次生成任务的风格差异，仅覆盖需要变化的键

合并逻辑：`finalStyle = merge(projectStyle, taskStyle)`，任务同名键覆盖工程风格。

详见 [后端工程 — 风格模型](backend.md#风格模型) 和 [预设风格键](style-keys.md)。

### 任务系统（Task）

采用"提交-异步执行-轮询/推送"模式。API 同步返回 taskId，后台 goroutine 执行管线，前端通过 HTTP 轮询或 WebSocket 获取实时进度。

详见 [异步任务](async-tasks.md)。

### 数据模型

```
user 1──N project
project 1──1 project_style
project 1──N task
task 1──N asset
```

详见 [数据存储](database.md#er-关系)。

## 命令行参考

### 后端

```bash
cd backend
go mod tidy                  # 安装依赖
go run cmd/main.go           # 开发服务器
go build -o bin/gen2d cmd/main.go  # 构建
go test ./...                # 全部测试
go test -run TestX ./internal/service/  # 单测
golangci-lint run            # 代码检查
```

### 前端

```bash
cd frontend
npm install          # 安装依赖
npm run dev          # 开发服务器
npm run build        # 生产构建
npm run preview      # 预览构建产物
npm run typecheck    # 类型检查
```