Files

xujiang fe59c8b499 feat: 添加 pre-commit hooks 配置

- 安装 husky 和 lint-staged 用于 Git hooks 管理
- 配置 pre-commit 检查：ESLint、TypeScript、Prettier
- 添加 Prettier 代码格式化配置和插件
- 更新项目文档说明 pre-commit 工作流程
- 配置文件包括：
  - .husky/pre-commit: Git pre-commit hook 脚本
  - lint-staged.config.js: lint-staged 配置
  - frontend/.prettierrc: Prettier 配置
  - frontend/.prettierignore: Prettier 忽略文件

现在每次提交前会自动运行代码检查和格式化

2025-07-09 09:29:33 +08:00

7.9 KiB

Raw Blame History

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/ 目录中运行。

运行开发服务器:

cd frontend && make dev
# 或者
cd frontend && export PATH="$HOME/.bun/bin:$PATH" && bun run dev

构建生产版本:

cd frontend && make build

启动生产服务器:

cd frontend && make start

代码检查:

cd frontend && make lint

类型检查:

cd frontend && make type-check

代码格式化:

cd frontend && make format

安装依赖:

cd frontend && make install

快速设置和启动:

cd frontend && make quick

Makefile 命令

项目包含一个全面的 Makefile，包含以下命令：

make help - 显示所有可用命令
make install - 安装依赖
make dev - 启动开发服务器
make build - 构建生产版本
make start - 启动生产服务器
make clean - 清理构建文件和缓存
make status - 检查项目状态
make add PACKAGE=name - 添加依赖
make add-dev PACKAGE=name - 添加开发依赖
make remove PACKAGE=name - 移除依赖
make type-check - 运行 TypeScript 类型检查
make lint - 运行代码检查
make format - 格式化代码
make setup - 设置开发环境
make deploy-prep - 准备生产部署
make quick - 快速启动（安装依赖并启动开发服务器）
make update - 更新所有依赖
make reinstall - 清理并重新安装依赖

项目结构

这是一个 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/timeline-stats.tsx - 时间轴统计信息
components/filter-bar.tsx - 照片分类过滤
components/about-view.tsx - 关于页面组件
components/contact-view.tsx - 联系页面组件
components/theme-provider.tsx - 主题提供者（深色模式支持）
components/providers/query-provider.tsx - TanStack Query 提供者
components/loading-spinner.tsx - 加载动画组件
components/ui/ - 来自 shadcn/ui 的可重用 UI 组件
lib/api.ts - 使用 axios 的 API 配置
lib/queries.ts - 用于数据获取的 TanStack Query hooks
lib/utils.ts - 工具函数
hooks/use-mobile.tsx - 移动端检测钩子
hooks/use-toast.ts - 通知钩子

数据结构

从 API 获取的照片具有以下 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 - 获取分类列表
POST /api/photos - 添加新照片
PUT /api/photos/:id - 更新照片信息
DELETE /api/photos/:id - 删除照片

启动模拟 API 服务器：

cd frontend && node mock-api.js

环境变量

.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 状态防止服务端/客户端不匹配

开发流程

所有开发都在 frontend/ 目录中进行
首次设置：make setup 创建环境变量文件
使用 make dev 或 bun run dev 启动开发服务器
使用 make lint 检查代码规范问题
使用 make type-check 运行 TypeScript 检查
使用 make format 格式化代码
部署前使用 make deploy-prep 进行完整检查和构建
使用 make status 检查项目健康状况

Pre-commit Hooks

项目配置了 pre-commit hooks，会在每次提交前自动运行：

ESLint 检查和修复 - 自动检查和修复代码规范问题
TypeScript 类型检查 - 确保类型安全
Prettier 格式化 - 统一代码格式

Pre-commit hooks 会在以下情况触发：

提交时自动运行（无需手动执行）
检查失败时会阻止提交
支持自动修复的问题会被自动修复

快速开始工作流程

cd frontend
make quick    # 安装依赖并启动开发服务器

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 等）
使用 Prettier 进行代码格式化
支持通过 make format 统一代码风格

文件锁定和包管理

使用 bun.lockb 而非 package-lock.json 作为锁定文件
项目名称：my-v0-project（可能需要更新为更合适的名称）
所有包管理操作都应通过 Makefile 命令执行，确保使用 bun

7.9 KiB Raw Blame History Unescape Escape