8c5c9a5f8e
- Fix React hydration mismatch in ThemeProvider with mounted state check - Update layout.tsx to use light theme by default instead of system - Optimize photo filtering with useMemo in page.tsx - Add Express mock API for development - Update CLAUDE.md with comprehensive project documentation - Create backend/ and admin/ directories for future development
184 lines
5.6 KiB
Markdown
184 lines
5.6 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
本文件为 Claude Code (claude.ai/code) 在此代码库中工作时提供指导。
|
||
|
||
## 开发命令
|
||
|
||
**重要提示**: 所有给我的提示尽量使用中文，此项目使用 bun 作为包管理器。所有命令都应在 `frontend/` 目录中运行。
|
||
|
||
运行开发服务器:
|
||
```bash
|
||
cd frontend && make dev
|
||
# 或者
|
||
cd frontend && export PATH="$HOME/.bun/bin:$PATH" && bun run dev
|
||
```
|
||
|
||
构建生产版本:
|
||
```bash
|
||
cd frontend && make build
|
||
```
|
||
|
||
启动生产服务器:
|
||
```bash
|
||
cd frontend && make start
|
||
```
|
||
|
||
代码检查:
|
||
```bash
|
||
cd frontend && make lint
|
||
```
|
||
|
||
类型检查:
|
||
```bash
|
||
cd frontend && make type-check
|
||
```
|
||
|
||
安装依赖:
|
||
```bash
|
||
cd frontend && make install
|
||
```
|
||
|
||
快速设置和启动:
|
||
```bash
|
||
cd frontend && make quick
|
||
```
|
||
|
||
## Makefile 命令
|
||
|
||
项目包含一个全面的 Makefile，包含以下命令：
|
||
- `make help` - 显示所有可用命令
|
||
- `make install` - 安装依赖
|
||
- `make dev` - 启动开发服务器
|
||
- `make build` - 构建生产版本
|
||
- `make clean` - 清理构建文件
|
||
- `make status` - 检查项目状态
|
||
- `make add PACKAGE=name` - 添加依赖
|
||
- `make remove PACKAGE=name` - 移除依赖
|
||
|
||
## 项目结构
|
||
|
||
这是一个 Next.js 15 摄影作品集应用，具有以下架构：
|
||
|
||
### 目录结构
|
||
```
|
||
photography/
|
||
├── frontend/ # 主要的 Next.js 应用程序 (活跃开发)
|
||
├── backend/ # 后端 API 目录 (空，预留)
|
||
├── admin/ # 管理后台目录 (空，预留)
|
||
├── ui/ # UI 组件备份目录 (非活跃)
|
||
└── CLAUDE.md # 项目指导文件
|
||
```
|
||
|
||
### 技术栈
|
||
- **主目录**: `frontend/` - 包含 Next.js 应用
|
||
- **包管理器**: bun (比 npm/yarn 更快)
|
||
- **框架**: Next.js 15 配合 React 19, TypeScript 和 Tailwind CSS
|
||
- **组件库**: Radix UI 组件配合 shadcn/ui
|
||
- **数据获取**: TanStack Query (React Query) v5 配合 Axios
|
||
- **状态管理**: React hooks (useState, useEffect) 用于本地状态
|
||
- **样式**: Tailwind CSS 配合自定义主题配置
|
||
- **图像**: Next.js Image 组件，启用未优化设置
|
||
- **表单**: React Hook Form 配合 Zod 验证
|
||
- **主题**: next-themes 提供深色模式支持
|
||
|
||
## 关键组件
|
||
|
||
- `app/page.tsx` - 主应用，包含照片画廊、时间轴、关于和联系页面
|
||
- `components/photo-gallery.tsx` - 基于网格的照片画廊，带悬停效果
|
||
- `components/navigation.tsx` - 粘性导航，带移动菜单
|
||
- `components/photo-modal.tsx` - 照片详情模态框，带导航
|
||
- `components/timeline-view.tsx` - 基于时间轴的照片展示
|
||
- `components/filter-bar.tsx` - 照片分类过滤
|
||
- `components/ui/` - 来自 shadcn/ui 的可重用 UI 组件
|
||
- `lib/api.ts` - 使用 axios 的 API 配置
|
||
- `lib/queries.ts` - 用于数据获取的 TanStack Query hooks
|
||
|
||
## 数据结构
|
||
|
||
从 API 获取的照片具有以下 TypeScript 接口：
|
||
```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
|
||
}
|
||
}
|
||
```
|
||
|
||
### Mock API
|
||
项目包含一个 Express 模拟 API (`mock-api.js`)，提供以下端点：
|
||
- `GET /api/photos` - 获取所有照片
|
||
- `GET /api/photos/:id` - 获取单个照片
|
||
- `GET /api/categories` - 获取分类列表
|
||
- 标准 CRUD 操作用于照片管理
|
||
|
||
## 环境变量
|
||
|
||
`.env.local` 中需要的环境变量：
|
||
```
|
||
NEXT_PUBLIC_API_URL=http://localhost:3001/api
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
### 关键配置文件
|
||
- **`next.config.mjs`** - Next.js 配置，构建时忽略错误，图像未优化
|
||
- **`tailwind.config.ts`** - Tailwind CSS 自定义主题配置
|
||
- **`tsconfig.json`** - TypeScript 严格模式，路径别名 (`@/*`)
|
||
- **`components.json`** - shadcn/ui 组件配置
|
||
- **`.bunfig.toml`** - bun 包管理器配置
|
||
|
||
### 特性配置
|
||
- 使用 bun 进行包管理（比 npm 更快）
|
||
- 启用 TypeScript 严格模式，配置路径别名（`@/*`）
|
||
- 构建时忽略 ESLint 和 TypeScript 错误（开发环境设置）
|
||
- 图像未优化，便于开发
|
||
- 通过 next-themes 配置深色模式支持
|
||
- 响应式设计，采用移动端优先方法
|
||
- 使用 TanStack Query 进行数据获取，自动缓存
|
||
- 水合错误修复：ThemeProvider 使用 mounted 状态防止服务端/客户端不匹配
|
||
|
||
## 开发流程
|
||
|
||
1. 所有开发都在 `frontend/` 目录中进行
|
||
2. 使用 `make dev` 或 `bun run dev` 启动开发服务器
|
||
3. 使用 `make lint` 检查代码规范问题
|
||
4. 使用 `make type-check` 运行 TypeScript 检查
|
||
5. 部署前使用 `make build` 构建
|
||
6. 使用 `make status` 检查项目健康状况
|
||
|
||
## Bun 特定说明
|
||
|
||
- Bun 在包管理方面比 npm 快得多
|
||
- 锁定文件是 `bun.lockb` 而不是 `package-lock.json`
|
||
- 使用 `bun add` 而不是 `npm install` 来添加包
|
||
- 在 `.bunfig.toml` 中配置 bun 特定设置
|
||
|
||
## 项目当前状态
|
||
|
||
- **Frontend**: 完全功能性的摄影作品集应用，包含完整的 UI 组件库
|
||
- **Backend**: 空目录，预留给未来的 API 开发
|
||
- **Admin**: 空目录，预留给未来的管理后台开发
|
||
- **UI**: 组件备份目录，非活跃开发状态
|
||
|
||
## 已知问题和解决方案
|
||
|
||
### 水合错误修复
|
||
- **问题**: React hydration mismatch 错误，由 next-themes 引起
|
||
- **解决方案**: 在 `components/theme-provider.tsx` 中使用 `mounted` 状态，防止服务端/客户端渲染不匹配
|
||
|
||
### 开发环境配置
|
||
- 构建时忽略 TypeScript 和 ESLint 错误（适用于开发环境）
|
||
- 图像未优化设置，便于开发调试
|
||
- 端口自动检测（如果 3000 被占用，会尝试 3001、3002 等） |