# Nano Banana AI 图像编辑器 - iFlow 上下文

## 项目概述

这是一个基于 React 和 TypeScript 的 AI 图像生成与编辑应用，名为 Nano Banana AI Image Editor。它利用 Google Gemini 2.5 Flash Image 模型，提供文本到图像生成和基于自然语言的图像编辑功能。该应用具有现代化的用户界面，支持交互式画布、区域选择和历史记录管理。

主要技术栈包括：
- **前端框架**: React 18, TypeScript
- **状态管理**: Zustand (应用状态), React Query (服务端状态)
- **UI 库**: Tailwind CSS
- **画布库**: Konva.js (react-konva)
- **AI 集成**: Google Generative AI SDK (Gemini)
- **数据存储**: IndexedDB (通过 idb-keyval)
- **构建工具**: Vite
- **桌面应用**: Electron

项目结构遵循标准的 React 应用组织方式，主要源代码位于 `src/` 目录下。该项目同时支持Web和桌面应用（Electron）。

## 构建和运行

### 开发环境

1. **安装依赖**:
   ```bash
   npm install
   ```

2. **配置环境变量**:
   - 复制 `.env.example` 为 `.env`
   - 在 `.env` 文件中设置 `VITE_GEMINI_API_KEY` (必需)
   - 可选设置 `VITE_ACCESS_TOKEN` 和 `VITE_UPLOAD_ASSET_URL` 以启用图像上传功能

3. **启动开发服务器**:
   ```bash
   # 启动Web开发服务器
   npm run dev
   
   # 启动Electron开发环境
   npm run electron:dev
   ```
   访问 `http://localhost:5173` 查看Web应用。

### 构建和部署

- **构建生产版本**:
  ```bash
  # 构建Web版本
  npm run build
  
  # 构建Electron桌面应用
  npm run electron:build
  ```

- **预览生产构建**:
  ```bash
  npm run preview
  ```

### 测试

- **运行测试**:
  ```bash
  npm run test
  ```

- **运行测试并监听变化**:
  ```bash
  npm run test:watch
  ```

### 代码质量

- **运行 ESLint**:
  ```bash
  npm run lint
  ```

## 开发约定

### 代码风格

- 使用 TypeScript 进行类型安全检查
- 使用 ESLint 进行代码规范检查
- 使用 Prettier 进行代码格式化 (通过 ESLint 配置集成)
- 组件文件使用 `.tsx` 扩展名
- 工具函数文件使用 `.ts` 扩展名

### 项目结构约定

```
src/
├── components/          # React 组件
│   ├── ui/             # 可重用的 UI 组件
│   │   ├── Button.tsx
│   │   ├── Input.tsx
│   │   └── Textarea.tsx
│   ├── CustomTitleBar.tsx  # 自定义标题栏（用于Electron应用）
│   ├── Header.tsx          # 应用头部和导航
│   ├── PromptComposer.tsx  # 提示输入和工具选择
│   ├── ImageCanvas.tsx     # 使用 Konva 的交互式画布
│   ├── HistoryPanel.tsx    # 生成历史和变体
│   ├── InfoModal.tsx       # 关于模态框和链接
│   ├── Toast.tsx           # 消息提示组件
│   └── ToastContext.tsx    # 消息提示上下文
├── services/           # 外部服务集成
│   ├── geminiService.ts    # Gemini API 客户端
│   ├── indexedDBService.ts # IndexedDB 数据库服务
│   ├── cacheService.ts     # IndexedDB 缓存层（未使用）
│   ├── referenceImageService.ts # 参考图像处理（未使用）
│   └── uploadService.ts    # 图像上传服务（未使用）
├── store/              # Zustand 状态管理
│   └── useAppStore.ts      # 全局应用状态
├── hooks/              # 自定义 React 钩子
│   ├── useImageGeneration.ts  # 生成和编辑逻辑
│   ├── useKeyboardShortcuts.ts # 键盘导航
│   └── useIndexedDBListener.ts # IndexedDB监听器（未使用）
├── utils/              # 工具函数
│   ├── cn.ts              # 类名工具
│   └── imageUtils.ts      # 图像处理助手
├── types/              # TypeScript 类型定义
│   └── index.ts           # 核心类型定义
└── __tests__/          # 测试文件
    ├── ImageCanvas.test.tsx
    ├── PromptComposer.test.tsx
    ├── useAppStore.test.ts
    └── useImageGeneration.test.ts
```

### 组件开发

- 组件应保持较小的体积（建议小于200行）
- 使用函数式组件和 React Hooks
- 组件应具有明确的接口（Props）
- 尽可能使用 TypeScript 进行类型定义

### 状态管理

- 全局状态使用 Zustand 管理 (`src/store/useAppStore.ts`)
- 服务端状态使用 React Query 管理
- 组件内部状态使用 React 的 useState 和 useReducer

### 测试

- 使用 Jest 和 React Testing Library 进行测试
- 测试文件放在 `src/__tests__` 目录下
- 测试文件名应与被测试文件名对应，加上 `.test.tsx` 或 `.test.ts` 后缀

### 贡献指南

1. 遵循既定的代码风格和项目结构
2. 保持组件在 200 行以内
3. 维护类型安全，严格使用 TypeScript 和正确定义
4. 彻底测试，确保键盘导航和可访问性
5. 记录更改，更新 README 并添加内联注释
6. 遵守 AGPL-3.0 许可证

## 项目特性

### AI 图像生成与编辑
- 文本到图像生成：使用 Google Gemini 2.5 Flash Image 模型从描述性提示创建图像
- 对话式编辑：使用自然语言指令修改现有图像
- 区域感知选择：通过绘制遮罩来针对特定区域进行编辑

### 用户界面
- 交互式画布：支持平滑缩放、平移和导航大图像
- 画笔工具：可变画笔尺寸以实现精确的遮罩绘制
- 响应式设计：在所有设备上都能完美运行
- 键盘快捷键：使用热键提高工作效率

### 数据管理
- 生成历史：跟踪所有创作和编辑记录
- 变体比较：生成并并排比较多个版本
- 离线缓存：使用 IndexedDB 存储以实现离线资产访问
- 项目管理：有序存储所有生成的内容

### 部署选项
- Web 应用：标准的 Web 应用程序，可在浏览器中运行
- 桌面应用：使用 Electron 构建的桌面应用程序，支持 Windows、macOS 和 Linux

## 依赖包更新

项目已清理未使用的依赖包，当前依赖包括：

### 运行时依赖
- `@google/genai`: Google Generative AI SDK
- `@radix-ui/react-dialog`: React 对话框组件
- `@tanstack/react-query`: 服务端状态管理
- `class-variance-authority`, `clsx`, `tailwind-merge`: 类名工具
- `idb-keyval`: IndexedDB 封装库
- `konva`, `react-konva`: Canvas 图形库
- `lucide-react`: 图标库
- `react`, `react-dom`: React 核心库
- `react-day-picker`: 日期选择器组件
- `zustand`: 客户端状态管理

### 开发依赖
- `@eslint/js`, `eslint`, `typescript-eslint`: 代码质量工具
- `@testing-library/*`: 测试工具
- `electron-builder`: Electron 应用构建工具
- `typescript`: TypeScript 编译器
- `vite`: 构建工具