9e381c783d
All checks were successful
Deploy Frontend / deploy (push) Successful in 2m38s
## 📁 模块化重构 ### 新增模块 CLAUDE.md - `frontend/CLAUDE.md` - 前端开发指导 (Next.js, React, TypeScript) - `docs/deployment/CLAUDE.md` - 部署配置指导 (Caddy, 服务器配置) - `.gitea/workflows/CLAUDE.md` - CI/CD 流程指导 (Gitea Actions) ### 根目录 CLAUDE.md 优化 - 重构为项目概览和模块导航 - 提供模块选择指导 - 减少单个文件的上下文长度 ### 自动化机制 - 创建 `scripts/update-claude-docs.sh` 自动更新脚本 - 集成到 pre-commit hooks 中 - 文件变更时自动更新对应模块的 CLAUDE.md ## 🎯 优化效果 ### 上下文优化 - 每个模块独立的 CLAUDE.md 文件 - 大幅减少单次处理的上下文长度 - 提高 Claude 处理效率和准确性 ### 开发体验 - 根据工作内容选择对应模块 - 模块化的文档更聚焦和专业 - 自动维护文档时间戳 ### 项目结构 ``` photography/ ├── CLAUDE.md # 项目概览和模块导航 ├── frontend/CLAUDE.md # 前端开发指导 ├── docs/deployment/CLAUDE.md # 部署配置指导 ├── .gitea/workflows/CLAUDE.md # CI/CD 流程指导 └── scripts/update-claude-docs.sh # 自动更新脚本 ``` 现在 Claude 工作时只需关注单个模块的文档，大幅提升处理效率！
226 lines
5.4 KiB
Markdown
226 lines
5.4 KiB
Markdown
# 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 进行样式管理
|
||
- 配置了自动代码格式化和类型检查 |