feat: 重构项目为模块化结构，拆分 CLAUDE.md 文档

## 📁 模块化重构 ### 新增模块 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 工作时只需关注单个模块的文档，大幅提升处理效率！
2025-07-09 10:54:08 +08:00
parent 87c34179fa
commit 9e381c783d
11 changed files with 1122 additions and 222 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -1,248 +1,229 @@
-# CLAUDE.md
+# Photography Portfolio Project - CLAUDE.md

-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+此文件为 Claude Code 在此项目中工作时提供指导。本项目采用模块化结构，每个模块有独立的 CLAUDE.md 文件。

-本文件为 Claude Code (claude.ai/code) 在此代码库中工作时提供指导。
+## 🎯 项目概览

-## 开发命令
+这是一个现代化的摄影作品集网站项目，使用 Next.js 15 + React 19 构建，支持静态部署。

-**重要提示**: 所有给我的提示尽量使用中文，此项目使用 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 format
-```
-
-安装依赖:
-```bash
-cd frontend && make install
-```
-
-快速设置和启动:
-```bash
-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          # 项目指导文件
-```
+### 主要特性
+- 📸 响应式照片画廊和时间轴视图
+- 🌙 深色/浅色主题切换
+- 📱 移动端优化
+- ⚡ 静态生成，极快加载速度
+- 🔒 自动 HTTPS (Let's Encrypt)
+- 🚀 CI/CD 自动部署

 ### 技术栈
- **主目录**: `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 提供深色模式支持
+- **前端**: Next.js 15, React 19, TypeScript, Tailwind CSS
+- **组件**: Radix UI + shadcn/ui
+- **部署**: Caddy + 静态文件
+- **CI/CD**: Gitea Actions

-## 关键组件
+## 📁 项目结构

- `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 接口：
-```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
-  }
-}
+```
+photography/
+├── CLAUDE.md                      # 🔍 当前文件 - 项目总览
+├── lint-staged.config.js           # Pre-commit 配置
+├── frontend/                       # 🎨 前端模块
+│   ├── CLAUDE.md                  # 前端开发指导
+│   ├── app/, components/, lib/    # Next.js 应用
+│   ├── package.json, Makefile    # 构建工具
+│   └── out/                       # 静态导出目录
+├── docs/                          # 📚 文档模块
+│   └── deployment/                # 🚀 部署模块
+│       ├── CLAUDE.md             # 部署配置指导
+│       ├── Caddyfile             # Web 服务器配置
+│       ├── fix-caddy-permissions.sh # 权限修复脚本
+│       └── caddy-setup.md        # 部署文档
+├── .gitea/workflows/              # ⚙️ CI/CD 模块
+│   ├── CLAUDE.md                 # CI/CD 配置指导
+│   └── deploy-frontend.yml       # 自动部署工作流
+├── admin/                         # 📋 管理后台 (预留)
+├── backend/                       # 🔧 后端 API (预留)
+└── ui/                           # 🎨 UI 组件备份
 ```

-### 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 服务器：
+### 根据工作内容选择模块
+
+#### 🎨 前端开发
 ```bash
-cd frontend && node mock-api.js
+# 切换到前端模块
+cd frontend/
+# 参考 frontend/CLAUDE.md
 ```
+**适用场景**: UI 组件开发、样式调整、前端功能实现、React/Next.js 相关工作

-## 环境变量
-
-`.env.local` 中需要的环境变量：
-```
-NEXT_PUBLIC_API_URL=http://localhost:3001/api
+#### 🚀 部署配置
+```bash  
+# 切换到部署模块
+cd docs/deployment/
+# 参考 docs/deployment/CLAUDE.md
 ```
+**适用场景**: 服务器配置、Caddy 设置、权限问题、域名配置、SSL 证书

-## 配置说明
-
-### 关键配置文件
- **`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 setup` 创建环境变量文件
-3. 使用 `make dev` 或 `bun run dev` 启动开发服务器
-4. 使用 `make lint` 检查代码规范问题
-5. 使用 `make type-check` 运行 TypeScript 检查
-6. 使用 `make format` 格式化代码
-7. 部署前使用 `make deploy-prep` 进行完整检查和构建
-8. 使用 `make status` 检查项目健康状况
-
-### Pre-commit Hooks
-
-项目配置了 pre-commit hooks，会在每次提交前自动运行：
- **ESLint 检查和修复** - 自动检查和修复代码规范问题
- **TypeScript 类型检查** - 确保类型安全
- **Prettier 格式化** - 统一代码格式
-
-Pre-commit hooks 会在以下情况触发：
- 提交时自动运行（无需手动执行）
- 检查失败时会阻止提交
- 支持自动修复的问题会被自动修复
-
-相关配置文件：
- `.husky/pre-commit` - Git pre-commit hook 脚本
- `lint-staged.config.js` - lint-staged 配置
- `frontend/.prettierrc` - Prettier 配置
- `frontend/.eslintrc.json` - ESLint 配置
-
-### 快速开始工作流程
+#### ⚙️ CI/CD 流程
 ```bash
-cd frontend
-make quick    # 安装依赖并启动开发服务器
+# 切换到 CI/CD 模块  
+cd .gitea/workflows/
+# 参考 .gitea/workflows/CLAUDE.md
+```
+**适用场景**: 自动部署、构建流程、环境配置、工作流优化
+
+#### 📚 文档和架构
+```bash
+# 在根目录工作
+# 参考当前 CLAUDE.md
+```
+**适用场景**: 项目架构、文档更新、模块协调、整体规划
+
+## 🚀 快速开始
+
+### 开发环境设置
+```bash
+# 1. 克隆项目
+git clone <repository>
+cd photography
+
+# 2. 前端开发
+cd frontend/
+make setup     # 初始化环境
+make quick     # 安装依赖 + 启动开发服务器
 ```

-## Bun 特定说明
+### 部署设置（首次）
+```bash
+# 1. 配置服务器
+scp docs/deployment/Caddyfile user@server:/etc/caddy/
+scp docs/deployment/fix-caddy-permissions.sh user@server:~/
+ssh user@server './fix-caddy-permissions.sh && sudo systemctl reload caddy'

- Bun 在包管理方面比 npm 快得多
- 锁定文件是 `bun.lockb` 而不是 `package-lock.json`
- 使用 `bun add` 而不是 `npm install` 来添加包
- 在 `.bunfig.toml` 中配置 bun 特定设置
+# 2. 推送代码自动部署
+git push origin main
+```

-## 项目当前状态
+## 🔧 全局配置

- **Frontend**: 完全功能性的摄影作品集应用，包含完整的 UI 组件库
- **Backend**: 空目录，预留给未来的 API 开发
- **Admin**: 空目录，预留给未来的管理后台开发
- **UI**: 组件备份目录，非活跃开发状态
+### Git Hooks (Pre-commit)
+项目配置了 pre-commit hooks，会在提交前自动运行：
+- ESLint 代码检查
+- TypeScript 类型检查  
+- Prettier 代码格式化

-## 已知问题和解决方案
+配置文件：`lint-staged.config.js`

-### 水合错误修复
- **问题**: React hydration mismatch 错误，由 next-themes 引起
- **解决方案**: 在 `components/theme-provider.tsx` 中使用 `mounted` 状态，防止服务端/客户端渲染不匹配
+### 环境要求
+- **Node.js**: 18+ 
+- **Bun**: 最新版本 (包管理器)
+- **Git**: 2.0+

-### 开发环境配置
- 构建时忽略 TypeScript 和 ESLint 错误（适用于开发环境）
- 图像未优化设置，便于开发调试
- 端口自动检测（如果 3000 被占用，会尝试 3001、3002 等）
- 使用 Prettier 进行代码格式化
- 支持通过 `make format` 统一代码风格
+## 🌐 访问地址

-## 文件锁定和包管理
- 使用 `bun.lockb` 而非 `package-lock.json` 作为锁定文件
- 项目名称：`my-v0-project`（可能需要更新为更合适的名称）
- 所有包管理操作都应通过 Makefile 命令执行，确保使用 bun
+### 生产环境
+- **网站**: https://photography.iriver.top
+- **部署**: 自动部署到 `/home/gitea/www/photography/`
+
+### 开发环境
+- **本地**: http://localhost:3000
+- **Mock API**: http://localhost:3001
+
+## 📋 常用命令
+
+### 项目级命令
+```bash
+# 前端开发
+cd frontend && make dev
+
+# 代码检查  
+cd frontend && make lint
+
+# 构建项目
+cd frontend && make build
+
+# 部署准备
+cd frontend && make deploy-prep
+```
+
+### Git 工作流
+```bash
+# 开发流程
+git checkout -b feature/new-feature
+# 开发...
+git add .
+git commit -m "feat: 新功能描述"  # pre-commit hooks 自动运行
+git push origin feature/new-feature
+
+# 部署流程  
+git checkout main
+git merge feature/new-feature
+git push origin main  # 触发自动部署
+```
+
+## 🔍 问题排查
+
+### 模块特定问题
+- **前端问题**: 查看 `frontend/CLAUDE.md`
+- **部署问题**: 查看 `docs/deployment/CLAUDE.md`  
+- **CI/CD 问题**: 查看 `.gitea/workflows/CLAUDE.md`
+
+### 通用问题
+```bash
+# 检查项目状态
+cd frontend && make status
+
+# 查看构建日志
+cd frontend && make build
+
+# 重置环境
+cd frontend && make clean && make install
+```
+
+## 📈 项目状态
+
+### 已完成功能
+- ✅ 前端应用 (Next.js 15)
+- ✅ CI/CD 自动部署
+- ✅ Web 服务器配置 (Caddy)
+- ✅ 代码质量控制 (ESLint + Prettier + TypeScript)
+- ✅ Pre-commit hooks
+
+### 计划中功能
+- 📋 管理后台
+- 📋 后端 API
+- 📋 多环境部署
+- 📋 性能监控
+
+## 🎨 模块协调原则
+
+### 何时修改模块 CLAUDE.md
+1. **前端模块** (`frontend/CLAUDE.md`): 组件、样式、前端逻辑变更时
+2. **部署模块** (`docs/deployment/CLAUDE.md`): 服务器、配置、部署流程变更时
+3. **CI/CD 模块** (`.gitea/workflows/CLAUDE.md`): 工作流、构建流程变更时
+4. **根目录** (`CLAUDE.md`): 项目架构、模块关系变更时
+
+### 模块间通信
+- 前端构建产物 → 部署模块使用
+- CI/CD 协调 → 所有模块的构建和部署
+- 配置变更 → 相关模块的 CLAUDE.md 同步更新
+
+## 🔄 最佳实践
+
+### 开发流程
+1. 确定工作模块，切换到对应目录
+2. 阅读模块的 CLAUDE.md 了解具体指导
+3. 完成开发和测试
+4. 更新相关模块的 CLAUDE.md (如有必要)
+5. 提交代码触发自动部署
+
+### 文档维护
+- 每个模块的 CLAUDE.md 保持独立和聚焦
+- 模块间的依赖关系在根目录 CLAUDE.md 中说明
+- 重要的全局配置统一在根目录管理
+
+### 上下文优化
+- Claude 工作时只需关注单个模块的 CLAUDE.md
+- 减少上下文长度，提高处理效率
+- 模块化降低复杂性，提高开发效率