<!-- Generated by SpecStory -->

# 项目 README 编写指导 (2025-05-25 22:27:58)

_**User**_

结合整个项目写一个 readme。

---

_**Assistant**_

I'll help you create a comprehensive README for your photo gallery site project. Let me first explore the project structure to understand what we're working with.

---

<details>
            <summary>Listed current directory • **20** results</summary>
        
| Name |
|-------|
| 📄 `package.json` |
| 📁 `node_modules` |
| 📁 `.git` |
| 📄 `pnpm-lock.yaml` |
| 📄 `index.html` |
| 📄 `vite.config.ts` |
| 📁 `dist` |
| 📄 `env.ts` |
| 📁 `src` |
| 📄 `tsconfig.json` |
| 📄 `eslint.config.mjs` |
| 📁 `scripts` |
| 📁 `public` |
| 📁 `plugins` |
| 📁 `.vscode` |
| 📁 `.github` |
| 📄 `.gitignore` |
| 📄 `.prettierrc.mjs` |
| 📄 `renovate.json` |
| 📄 `vercel.json` |

</details>

---

Read file: package.json

---

<details>
            <summary>Listed directory src • **19** results</summary>
        
| Name |
|-------|
| 📁 `lib` |
| 📄 `global.d.ts` |
| 📁 `hooks` |
| 📁 `components` |
| 📁 `icons` |
| 📁 `atoms` |
| 📁 `styles` |
| 📁 `modules` |
| 📄 `App.tsx` |
| 📁 `data` |
| 📁 `pages` |
| 📄 `main.tsx` |
| 📄 `router.tsx` |
| 📁 `types` |
| 📁 `providers` |
| 📁 `store` |
| 📁 `assets` |
| 📄 `framer-lazy-feature.ts` |
| 📄 `vite-env.d.ts` |

</details>

---

Read file: src/App.tsx

---

Read file: src/router.tsx

---

<details>
            <summary>Listed directory src/pages • **1** results</summary>
        
| Name |
|-------|
| 📁 `(main)` |

</details>

---

<details>
            <summary>Listed directory src/pages/(main) • **1** results</summary>
        
| Name |
|-------|
| 📄 `index.tsx` |

</details>

---

Read file: src/pages/(main)/index.tsx

---

<details>
            <summary>Listed directory src/modules • **1** results</summary>
        
| Name |
|-------|
| 📁 `gallery` |

</details>

---

<details>
            <summary>Listed directory src/modules/gallery • **2** results</summary>
        
| Name |
|-------|
| 📄 `MasonryRoot.tsx` |
| 📄 `PhotoMasonryItem.tsx` |

</details>

---

Read file: src/modules/gallery/MasonryRoot.tsx

---

Read file: env.ts

---

<details>
            <summary>Listed directory scripts • **2** results</summary>
        
| Name |
|-------|
| 📄 `build-manifest.ts` |
| 📄 `test-s3.js` |

</details>

---

Read file: scripts/build-manifest.ts

---

Read file: vite.config.ts

---

Read file: vercel.json

---

<details>
            <summary>Listed directory src/components • **3** results</summary>
        
| Name |
|-------|
| 📁 `photo-viewer` |
| 📁 `ui` |
| 📁 `common` |

</details>

---

<details>
            <summary>Listed directory src/components/photo-viewer • **6** results</summary>
        
| Name |
|-------|
| 📄 `ExifPanel.tsx` |
| 📄 `ProgressiveImage.tsx` |
| 📄 `PhotoViewer.tsx` |
| 📄 `GalleryThumbnail.tsx` |
| 📄 `index.ts` |
| 📄 `PhotoViewer.css` |

</details>

---

Now I have a comprehensive understanding of the project. Let me create a detailed README file.

---

```diff
- 
+ # Photo Gallery Site
+ 
+ 一个现代化的照片画廊网站，支持从 S3 存储自动同步照片，具有瀑布流布局、EXIF 信息展示、缩略图生成等功能。
+ 
+ ## ✨ 特性
+ 
+ - 🖼️ **瀑布流布局** - 使用 Masonic 实现的响应式瀑布流照片展示
+ - 📱 **响应式设计** - 完美适配桌面端和移动端
+ - 🔍 **照片查看器** - 支持缩放、平移、手势操作的全屏照片查看
+ - 📊 **EXIF 信息** - 详细的照片元数据展示（拍摄时间、相机参数等）
+ - 🌈 **BlurHash** - 优雅的图片加载占位符
+ - 🚀 **渐进式加载** - 缩略图到高清图的平滑过渡
+ - ☁️ **S3 集成** - 自动从 S3 存储同步照片
+ - 🔄 **自动构建** - 智能的增量更新机制
+ - 🎨 **现代 UI** - 基于 Tailwind CSS 的精美界面
+ - 🌙 **深色模式** - 支持明暗主题切换
+ - 📅 **排序功能** - 支持按时间升序/降序排列
+ 
+ ## 🛠️ 技术栈
+ 
+ ### 前端框架
+ - **React 19** - 最新的 React 版本
+ - **TypeScript** - 类型安全的 JavaScript
+ - **Vite** - 快速的构建工具
+ - **React Router** - 客户端路由
+ 
+ ### UI 组件
+ - **Tailwind CSS** - 实用优先的 CSS 框架
+ - **DaisyUI** - Tailwind CSS 组件库
+ - **Headless UI** - 无样式的可访问组件
+ - **Radix UI** - 高质量的 React 组件
+ - **Framer Motion** - 流畅的动画库
+ 
+ ### 状态管理
+ - **Jotai** - 原子化状态管理
+ - **Zustand** - 轻量级状态管理
+ - **TanStack Query** - 服务端状态管理
+ 
+ ### 图片处理
+ - **Sharp** - 高性能图片处理
+ - **BlurHash** - 图片占位符生成
+ - **React Image Gallery** - 图片画廊组件
+ - **React Zoom Pan Pinch** - 图片缩放平移
+ 
+ ### 云服务
+ - **AWS S3** - 图片存储
+ - **Vercel** - 部署平台
+ 
+ ### 开发工具
+ - **ESLint** - 代码检查
+ - **Prettier** - 代码格式化
+ - **Simple Git Hooks** - Git 钩子
+ - **Lint Staged** - 暂存文件检查
+ 
+ ## 📦 安装
+ 
+ ### 环境要求
+ - Node.js 18+
+ - pnpm 8+
+ 
+ ### 克隆项目
+ ```bash
+ git clone https://github.com/innei/photo-gallery-site.git
+ cd photo-gallery-site
+ ```
+ 
+ ### 安装依赖
+ ```bash
+ pnpm install
+ ```
+ 
+ ### 环境配置
+ 创建 `.env` 文件并配置以下环境变量：
+ 
+ ```env
+ # S3 配置
+ S3_REGION=us-east-1
+ S3_ACCESS_KEY_ID=your_access_key_id
+ S3_SECRET_ACCESS_KEY=your_secret_access_key
+ S3_ENDPOINT=https://s3.us-east-1.amazonaws.com
+ S3_BUCKET_NAME=your_bucket_name
+ S3_PREFIX=photos/
+ S3_CUSTOM_DOMAIN=your_custom_domain.com
+ ```
+ 
+ ## 🚀 使用
+ 
+ ### 开发模式
+ ```bash
+ pnpm dev
+ ```
+ 
+ ### 构建照片清单
+ ```bash
+ # 增量更新（默认）
+ pnpm run build:manifest
+ 
+ # 全量更新
+ pnpm run build:manifest -- --force
+ ```
+ 
+ ### 测试 S3 连接
+ ```bash
+ pnpm run test:s3
+ ```
+ 
+ ### 构建生产版本
+ ```bash
+ pnpm run build
+ ```
+ 
+ ### 预览生产版本
+ ```bash
+ pnpm run serve
+ ```
+ 
+ ## 📁 项目结构
+ 
+ ```
+ photo-gallery-site/
+ ├── src/
+ │   ├── components/          # UI 组件
+ │   │   ├── photo-viewer/    # 照片查看器组件
+ │   │   ├── ui/              # 基础 UI 组件
+ │   │   └── common/          # 通用组件
+ │   ├── modules/             # 功能模块
+ │   │   └── gallery/         # 画廊模块
+ │   ├── pages/               # 页面组件
+ │   ├── hooks/               # 自定义 Hooks
+ │   ├── atoms/               # Jotai 原子状态
+ │   ├── store/               # Zustand 状态
+ │   ├── data/                # 数据文件
+ │   ├── types/               # TypeScript 类型
+ │   ├── lib/                 # 工具库
+ │   └── styles/              # 样式文件
+ ├── scripts/                 # 构建脚本
+ │   ├── build-manifest.ts    # 照片清单构建
+ │   └── test-s3.js          # S3 连接测试
+ ├── public/                  # 静态资源
+ │   └── thumbnails/          # 缩略图目录
+ └── plugins/                 # Vite 插件
+ ```
+ 
+ ## 🔧 核心功能
+ 
+ ### 照片同步
+ 项目通过 `build-manifest.ts` 脚本自动从 S3 存储同步照片：
+ 
+ 1. **扫描 S3 存储桶** - 获取所有支持格式的图片文件
+ 2. **提取 EXIF 信息** - 读取照片的元数据信息
+ 3. **生成缩略图** - 创建 WebP 格式的缩略图
+ 4. **生成 BlurHash** - 为每张照片生成占位符
+ 5. **构建清单文件** - 生成包含所有照片信息的 JSON 文件
+ 
+ ### 瀑布流布局
+ 使用 Masonic 库实现高性能的瀑布流布局：
+ - 虚拟化渲染，支持大量图片
+ - 响应式列数调整
+ - 平滑的滚动体验
+ 
+ ### 照片查看器
+ 功能丰富的照片查看器：
+ - 全屏查看模式
+ - 缩放和平移操作
+ - 手势支持（移动端）
+ - 键盘导航
+ - EXIF 信息面板
+ 
+ ## 🌐 部署
+ 
+ ### Vercel 部署
+ 项目已配置 Vercel 部署，只需：
+ 
+ 1. 连接 GitHub 仓库到 Vercel
+ 2. 配置环境变量
+ 3. 自动部署
+ 
+ ### 自定义部署
+ ```bash
+ # 构建项目
+ pnpm run build
+ 
+ # 部署 dist 目录到你的服务器
+ ```
+ 
+ ## 📝 开发指南
+ 
+ ### 添加新照片
+ 1. 将照片上传到 S3 存储桶
+ 2. 运行 `pnpm run build:manifest` 更新照片清单
+ 3. 重新构建和部署项目
+ 
+ ### 自定义样式
+ 项目使用 Tailwind CSS，可以通过以下方式自定义：
+ - 修改 `tailwind.config.js`
+ - 在 `src/styles/` 目录添加自定义样式
+ 
+ ### 添加新功能
+ 1. 在 `src/modules/` 创建新的功能模块
+ 2. 在 `src/components/` 添加相关组件
+ 3. 更新路由配置
+ 
+ ## 🤝 贡献
+ 
+ 欢迎提交 Issue 和 Pull Request！
+ 
+ ### 开发流程
+ 1. Fork 项目
+ 2. 创建功能分支
+ 3. 提交更改
+ 4. 推送到分支
+ 5. 创建 Pull Request
+ 
+ ### 代码规范
+ - 使用 ESLint 和 Prettier 保持代码风格一致
+ - 提交前会自动运行代码检查
+ - 遵循 TypeScript 最佳实践
+ 
+ ## 📄 许可证
+ 
+ MIT License
+ 
+ ## 🙏 致谢
+ 
+ - [Masonic](https://github.com/jaredLunde/masonic) - 瀑布流布局
+ - [Sharp](https://sharp.pixelplumbing.com/) - 图片处理
+ - [BlurHash](https://blurha.sh/) - 图片占位符
+ - [Tailwind CSS](https://tailwindcss.com/) - CSS 框架
+ 
+ ---
+ 
+ 如果这个项目对你有帮助，请给个 ⭐️ 支持一下！ 
```

---

我已经为你的照片画廊网站项目创建了一个详细的 README 文档。这个 README 包含了以下主要内容：

## 📋 README 内容概览

### ✨ 特性介绍
- 瀑布流布局、响应式设计
- 照片查看器、EXIF 信息展示
- BlurHash 占位符、渐进式加载
- S3 集成、自动构建等核心功能

### 🛠️ 技术栈详解
详细列出了项目使用的所有技术：
- **前端框架**: React 19, TypeScript, Vite, React Router
- **UI 组件**: Tailwind CSS, DaisyUI, Headless UI, Radix UI
- **状态管理**: Jotai, Zustand, TanStack Query
- **图片处理**: Sharp, BlurHash, React Image Gallery
- **云服务**: AWS S3, Vercel

### 📦 安装和配置
- 环境要求和依赖安装
- 详细的环境变量配置说明
- S3 存储配置指南

### 🚀 使用指南
- 开发、构建、部署的完整命令
- 照片清单构建和 S3 测试
- 增量更新和全量更新选项

### 📁 项目结构
清晰的目录结构说明，帮助开发者快速理解代码组织

### 🔧 核心功能说明
- 照片同步机制的详细流程
- 瀑布流布局的实现特点
- 照片查看器的功能特性

### 🌐 部署指南
- Vercel 一键部署
- 自定义部署选项

### 📝 开发指南
- 添加新照片的流程
- 自定义样式的方法
- 扩展新功能的指导

这个 README 文档全面覆盖了项目的各个方面，既适合新用户快速上手，也为开发者提供了详细的技术参考。文档使用了丰富的 emoji 和清晰的结构，让阅读体验更加友好。

---

