photography/CLAUDE.md

# Photography Portfolio Project - CLAUDE.md

此文件为 Claude Code 在此项目中工作时提供指导。本项目采用模块化结构，每个模块有独立的 CLAUDE.md 文件。

## 🎯 项目概览

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

### 主要特性
- 📸 响应式照片画廊和时间轴视图
- 🌙 深色/浅色主题切换
- 📱 移动端优化
- ⚡ 静态生成，极快加载速度
- 🔒 自动 HTTPS (Let's Encrypt)
- 🚀 CI/CD 自动部署

### 技术栈
- **前端**: Next.js 15, React 19, TypeScript, Tailwind CSS
- **组件**: Radix UI + shadcn/ui
- **部署**: Caddy + 静态文件
- **CI/CD**: Gitea Actions

## 📁 项目结构

```
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 组件备份
```

## 🎯 模块化工作指南

### 根据工作内容选择模块

#### 🎨 前端开发
```bash
# 切换到前端模块
cd frontend/
# 参考 frontend/CLAUDE.md
```
**适用场景**: UI 组件开发、样式调整、前端功能实现、React/Next.js 相关工作

#### 🚀 部署配置
```bash  
# 切换到部署模块
cd docs/deployment/
# 参考 docs/deployment/CLAUDE.md
```
**适用场景**: 服务器配置、Caddy 设置、权限问题、域名配置、SSL 证书

#### ⚙️ CI/CD 流程
```bash
# 切换到 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     # 安装依赖 + 启动开发服务器
```

### 部署设置（首次）
```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'

# 2. 推送代码自动部署
git push origin main
```

## 🔧 全局配置

### Git Hooks (Pre-commit)
项目配置了 pre-commit hooks，会在提交前自动运行：
- ESLint 代码检查
- TypeScript 类型检查  
- Prettier 代码格式化

配置文件：`lint-staged.config.js`

### 环境要求
- **Node.js**: 18+ 
- **Bun**: 最新版本 (包管理器)
- **Git**: 2.0+

## 🌐 访问地址

### 生产环境
- **网站**: 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
- 减少上下文长度，提高处理效率
- 模块化降低复杂性，提高开发效率