photography/frontend/CLAUDE.md

Frontend Module - CLAUDE.md

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

模块说明

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

开发命令

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

基础命令

# 安装依赖
make install
# 或者
bun install

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

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

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

代码质量

# 代码检查
make lint
# 或者
bun run lint

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

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

快速命令

# 快速开始（安装依赖+启动开发）
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 - 移动端检测钩子

数据结构

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)

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）

开发工作流

首次设置

make setup    # 创建环境变量文件
make install  # 安装依赖

日常开发

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

部署前检查

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 进行样式管理
• 配置了自动代码格式化和类型检查