# 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

项目结构遵循标准的 React 应用组织方式，主要源代码位于 `src/` 目录下。

## 构建和运行

### 开发环境

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

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

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

### 构建和部署

- **构建生产版本**:
  ```bash
  npm run 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 组件
│   ├── PromptComposer.tsx  # 提示输入和工具选择
│   ├── ImageCanvas.tsx     # 使用 Konva 的交互式画布
│   ├── HistoryPanel.tsx    # 生成历史和变体
│   ├── Header.tsx          # 应用头部和导航
│   └── InfoModal.tsx       # 关于模态框和链接
├── services/           # 外部服务集成
│   ├── geminiService.ts    # Gemini API 客户端
│   ├── uploadService.ts    # 图像上传服务
│   ├── cacheService.ts     # IndexedDB 缓存层
│   └── referenceImageService.ts # 参考图像处理
├── store/              # Zustand 状态管理
│   └── useAppStore.ts      # 全局应用状态
├── hooks/              # 自定义 React 钩子
│   ├── useImageGeneration.ts  # 生成和编辑逻辑
│   └── useKeyboardShortcuts.ts # 键盘导航
├── utils/              # 工具函数
│   ├── cn.ts              # 类名工具
│   └── imageUtils.ts      # 图像处理助手
└── types/              # TypeScript 类型定义
    └── index.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 许可证