# Frontend Module - CLAUDE.md

此文件为 Claude Code 在前端模块中工作时提供指导。

## 模块说明
这是摄影作品集项目的前端模块，使用 Next.js 15 + React 19 + TypeScript + Tailwind CSS 构建。

## 开发命令

**重要**: 所有命令都应在当前目录 (`frontend/`) 中运行，使用 bun 作为包管理器。

### 基础命令
```bash
# 安装依赖
make install
# 或者
bun install

# 开发服务器
make dev
# 或者  
bun run dev

# 构建生产版本
make build
# 或者
bun run build

# 启动生产服务器
make start
# 或者
bun run start
```

### 代码质量
```bash
# 代码检查
make lint
# 或者
bun run lint

# 类型检查
make type-check  
# 或者
bun run type-check

# 代码格式化
make format
# 或者
bun run format
```

### 快速命令
```bash
# 快速开始（安装依赖+启动开发）
make quick

# 部署准备（完整检查+构建）
make deploy-prep
```

## 技术栈

### 核心框架
- **Next.js 15** - React 框架，配置静态导出
- **React 19** - UI 库
- **TypeScript** - 类型安全
- **Tailwind CSS** - 样式框架

### 组件库
- **Radix UI** - 无障碍组件基础
- **shadcn/ui** - 预构建组件库
- **Lucide React** - 图标库

### 数据管理
- **TanStack Query v5** - 数据获取和缓存
- **Axios** - HTTP 客户端
- **React Hook Form + Zod** - 表单处理和验证

### 开发工具
- **ESLint** - 代码检查（Next.js 严格模式）
- **Prettier** - 代码格式化
- **TypeScript** - 类型检查
- **Husky + lint-staged** - Git hooks

## 项目结构

```
frontend/
├── app/                    # Next.js App Router
│   ├── globals.css        # 全局样式
│   ├── layout.tsx         # 根布局
│   └── page.tsx           # 主页
├── components/            # React 组件
│   ├── ui/               # shadcn/ui 组件
│   ├── photo-gallery.tsx # 照片画廊
│   ├── navigation.tsx    # 导航组件
│   └── ...
├── hooks/                # 自定义 hooks
├── lib/                  # 工具库
│   ├── api.ts           # API 配置
│   ├── queries.ts       # TanStack Query hooks
│   └── utils.ts         # 工具函数
├── public/              # 静态资源
├── styles/              # 样式文件
├── out/                 # 静态导出输出 (构建后生成)
└── 配置文件...
```

## 关键组件

### 主要页面组件
- `app/page.tsx` - 主应用，包含照片画廊、时间轴、关于、联系页面
- `components/photo-gallery.tsx` - 基于网格的照片画廊，带悬停效果
- `components/navigation.tsx` - 粘性导航，带移动菜单
- `components/photo-modal.tsx` - 照片详情模态框，带导航
- `components/timeline-view.tsx` - 基于时间轴的照片展示

### UI 组件
- `components/ui/` - 来自 shadcn/ui 的可重用 UI 组件
- `components/theme-provider.tsx` - 主题提供者（深色模式支持）
- `components/loading-spinner.tsx` - 加载动画组件

### 数据层
- `lib/api.ts` - 使用 axios 的 API 配置
- `lib/queries.ts` - 用于数据获取的 TanStack Query hooks
- `hooks/use-mobile.tsx` - 移动端检测钩子

## 数据结构

```typescript
interface Photo {
  id: number
  src: string
  title: string
  description: string
  category: string
  tags: string[]
  date: string
  exif: {
    camera: string
    lens: string
    settings: string
    location: string
  }
}
```

## 配置文件

### 核心配置
- **`next.config.mjs`** - Next.js 配置，静态导出设置
- **`tailwind.config.ts`** - Tailwind CSS 自定义主题
- **`tsconfig.json`** - TypeScript 配置，严格模式
- **`.eslintrc.json`** - ESLint 配置，Next.js 严格模式
- **`.prettierrc`** - Prettier 代码格式化配置

### 包管理
- **`package.json`** - 项目依赖和脚本
- **`bun.lock`** - Bun 锁定文件
- **`Makefile`** - 开发命令快捷方式

## 环境配置

### 环境变量 (.env.local)
```bash
NEXT_PUBLIC_API_URL=http://localhost:3001/api
```

### Mock API
项目包含 Express 模拟 API (`mock-api.js`)：
- `GET /api/photos` - 获取所有照片
- `GET /api/photos/:id` - 获取单个照片
- `GET /api/categories` - 获取分类列表

启动方式：`node mock-api.js`

## 部署配置

### 静态导出
- **输出目录**: `out/`
- **导出模式**: 静态文件（`output: 'export'`）
- **图像优化**: 禁用（`unoptimized: true`）

### 构建优化
- 构建时跳过 ESLint 和 TypeScript 错误（开发配置）
- 自动生成静态 HTML 文件
- 支持 SPA 路由（`trailingSlash: true`）

## 开发工作流

### 首次设置
```bash
make setup    # 创建环境变量文件
make install  # 安装依赖
```

### 日常开发
```bash
make dev      # 启动开发服务器
make lint     # 代码检查
make format   # 代码格式化
```

### 部署前检查
```bash
make deploy-prep  # 完整检查和构建
```

## 已知问题和解决方案

### 水合错误修复
- **问题**: React hydration mismatch 错误
- **解决方案**: ThemeProvider 使用 `mounted` 状态防止 SSR/客户端不匹配

### Pre-commit Hooks
- 自动运行 ESLint、TypeScript 检查和 Prettier 格式化
- 配置位于根目录 `lint-staged.config.js`

## 注意事项

- 使用 bun 而非 npm/yarn 进行包管理
- 所有组件使用 TypeScript 严格模式
- 遵循 Next.js App Router 模式
- 使用 Tailwind CSS 进行样式管理
- 配置了自动代码格式化和类型检查