imagecreator/docs/superpowers/specs/2026-03-24-imagecreator-design.md

# 图片生成网站设计文档

## 项目概述

**项目名称**: ImageCreator
**项目类型**: 前后端分离的 Web 应用
**核心功能**: 用户注册登录后，通过提示词优化 + 图像生成（T2I/I2I）实现图片创作
**目标用户**: 需要生成图片的普通用户、内容创作者

## 技术架构

### 整体架构

```
┌─────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Vue 3 前端 │ ←→  │  FastAPI 后端    │ ←→  │  图像生成 API   │
│  (用户界面)  │     │  (业务逻辑)       │     │  Gemini/OpenAI  │
└─────────────┘     └────────┬─────────┘     └─────────────────┘
                            ↓
                    ┌───────────────┐
                    │  PostgreSQL   │
                    └───────────────┘
```

### 技术栈

| 层级 | 技术 | 说明 |
|------|------|------|
| 前端框架 | Vue 3 + TypeScript | 组合式 API |
| 前端构建 | Vite | 快速构建工具 |
| 前端 UI | Naive UI + TailwindCSS | 组件库 + 样式 |
| 后端框架 | FastAPI (Python) | 高性能 API 框架 |
| 数据库 | PostgreSQL | 用户数据、历史记录 |
| ORM | SQLAlchemy | 数据库操作 |
| 认证 | JWT | 无状态认证 |
| 图像存储 | 本地文件系统 | 生成的图片存储 |

### 项目结构

```
/opt/imagecreator/imagecreator/
├── backend/                  # FastAPI 后端
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py           # FastAPI 入口
│   │   ├── config.py         # 配置管理
│   │   ├── api/             # API 路由
│   │   │   ├── __init__.py
│   │   │   ├── auth.py      # 认证相关路由
│   │   │   ├── users.py     # 用户路由
│   │   │   ├── images.py     # 图片生成路由
│   │   │   └── history.py    # 历史记录路由
│   │   ├── core/            # 核心模块
│   │   │   ├── __init__.py
│   │   │   ├── security.py   # JWT / 密码处理
│   │   │   └── config.py     # 配置加载
│   │   ├── models/          # 数据库模型
│   │   │   ├── __init__.py
│   │   │   ├── user.py      # 用户模型
│   │   │   └── history.py   # 生成历史模型
│   │   ├── schemas/         # Pydantic schemas
│   │   │   ├── __init__.py
│   │   │   ├── auth.py
│   │   │   ├── user.py
│   │   │   ├── image.py
│   │   │   └── history.py
│   │   └── services/        # 业务逻辑
│   │       ├── __init__.py
│   │       ├── auth.py      # 认证服务
│   │       ├── image.py     # 图像生成服务
│   │       └── prompt.py    # 提示词优化服务
│   ├── requirements.txt
│   └── init_db.py           # 数据库初始化
├── frontend/                # Vue 3 前端
│   ├── src/
│   │   ├── api/            # API 调用
│   │   │   ├── index.ts
│   │   │   ├── auth.ts
│   │   │   └── images.ts
│   │   ├── components/     # 组件
│   │   │   ├── ImageGenerator.vue
│   │   │   ├── PromptOptimizer.vue
│   │   │   ├── ImageHistory.vue
│   │   │   └── ...
│   │   ├── views/          # 页面
│   │   │   ├── Login.vue
│   │   │   ├── Register.vue
│   │   │   ├── Home.vue
│   │   │   └── History.vue
│   │   ├── stores/         # 状态管理
│   │   ├── router/         # 路由
│   │   ├── App.vue
│   │   └── main.ts
│   ├── package.json
│   └── vite.config.ts
├── docker-compose.yml
└── README.md
```

## 功能模块

### 1. 用户系统

#### 1.1 注册
- 用户名（唯一）
- 邮箱（唯一）
- 密码（加密存储）

#### 1.2 登录
- 用户名/邮箱 + 密码
- 返回 JWT token

#### 1.3 用户信息
- 查看/修改个人信息
- 密码修改

### 2. 提示词优化

#### 2.1 优化策略
参考 prompt-optimizer 的图像优化模板：

- **文生图优化**: 通用图像生成提示词优化
- **图生图优化**: 针对 I2I 场景的提示词优化
  - 识别添加/删除/替换/增强意图
  - 自然语言描述编辑需求

#### 2.2 优化流程
```
用户输入 → LLM 优化 → 优化后提示词 → 用户确认 → 生成图片
```

### 3. 图片生成

#### 3.1 文生图 (T2I)
- 输入: 优化后的提示词
- 选择模型: Gemini / OpenAI DALL-E
- 输出: 生成的图片

#### 3.2 图生图 (I2I)
- 输入: 参考图片 (base64) + 修改需求描述
- 选择模式:
  - **通用编辑**: 基于描述进行修改
  - **风格迁移**: 转换为指定风格
  - **变体生成**: 生成相似变体
- 选择模型: Gemini
- 输出: 生成的图片

#### 3.3 支持的图像模型
| 模型 | Provider | T2I | I2I | 风格迁移 | 变体 |
|------|----------|-----|-----|----------|------|
| Gemini 2.5 Flash | Google | ✓ | ✓ | ✓ | ✓ |
| DALL-E 3 | OpenAI | ✓ | - | - | - |

### 4. 历史记录

- 记录每次生成的:
  - 原始提示词
  - 优化后提示词
  - 使用的模型
  - 生成的图片
  - 生成时间
- 支持查看、删除

## API 设计

### 认证相关

| 方法 | 路径 | 描述 |
|------|------|------|
| POST | /api/auth/register | 用户注册 |
| POST | /api/auth/login | 用户登录 |
| POST | /api/auth/refresh | 刷新 Token |

### 用户相关

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /api/users/me | 获取当前用户信息 |
| PUT | /api/users/me | 更新用户信息 |

### 图像生成

| 方法 | 路径 | 描述 |
|------|------|------|
| POST | /api/images/optimize | 优化提示词 |
| POST | /api/images/generate | 生成图片 (T2I/I2I) |

### 历史记录

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /api/history | 获取历史记录列表 |
| GET | /api/history/{id} | 获取单条记录详情 |
| DELETE | /api/history/{id} | 删除记录 |

## 数据模型

### User
```
id: UUID (主键)
username: String (唯一, 32字符)
email: String (唯一, 255字符)
hashed_password: String (255字符)
created_at: DateTime
updated_at: DateTime
```

### GenerationHistory
```
id: UUID (主键)
user_id: UUID (外键)
original_prompt: Text
optimized_prompt: Text
mode: Enum (text2image, image2image)
model: String (32字符)
image_url: String (512字符)
input_image_url: String (可选, 512字符)  # I2I 时的输入图
created_at: DateTime
```

## 安全设计

1. **密码加密**: bcrypt
2. **JWT Token**:
   - Access Token: 30分钟有效期
   - Refresh Token: 7天有效期
3. **API 认证**: Bearer Token
4. **输入验证**: Pydantic schemas
5. **CORS**: 限制前端域名访问

## 部署架构

### Docker Compose

```yaml
services:
  backend:
    build: ./backend
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/imagecreator
      - SECRET_KEY=xxx
      - GEMINI_API_KEY=xxx
      - OPENAI_API_KEY=xxx
    depends_on:
      - db

  frontend:
    build: ./frontend
    ports:
      - "3000:80"
    depends_on:
      - backend

  db:
    image: postgres:15
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=pass
      - POSTGRES_DB=imagecreator
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:
```

## 实施计划

### 第一阶段: 基础架构
1. 项目目录结构初始化
2. 后端 FastAPI 框架搭建
3. 数据库模型创建
4. Docker Compose 配置

### 第二阶段: 核心功能
1. 用户认证模块 (注册/登录/JWT)
2. 提示词优化服务
3. 图像生成服务 (T2I/I2I)

### 第三阶段: 前端开发
1. Vue 3 项目初始化
2. 页面开发 (登录/注册/主页/历史)
3. 组件开发 (图像生成器/提示词优化)

### 第四阶段: 集成测试
1. API 联调
2. 前后端联调
3. 部署测试

## 参考项目

- [prompt-optimizer](https://github.com/linshenkx/prompt-optimizer) - 本项目的核心逻辑参考
  - 图像适配器架构
  - 提示词优化模板 (image2image-optimize, text2image-optimize)
  - 服务层设计模式