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
• 管理后台: React + TypeScript + Vite (使用 Bun)
• 组件: 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/                         # 📋 管理后台模块
│   └── CLAUDE.md                 # 管理后台开发指导
├── backend/                       # 🔧 后端 API 模块
│   └── CLAUDE.md                 # 后端开发指导
├── ui/                           # 🎨 UI 备份模块
│   └── CLAUDE.md                 # UI 备份模块管理
└── scripts/                      # 🛠️ 工具脚本
    └── README.md                 # 脚本说明

🎯 模块化工作指南

根据工作内容选择模块

🎨 前端开发

# 切换到前端模块
cd frontend/
# 参考 frontend/CLAUDE.md

适用场景: UI 组件开发、样式调整、前端功能实现、React/Next.js 相关工作

🚀 部署配置

# 切换到部署模块
cd docs/deployment/
# 参考 docs/deployment/CLAUDE.md

适用场景: 服务器配置、Caddy 设置、权限问题、域名配置、SSL 证书

⚙️ CI/CD 流程

# 切换到 CI/CD 模块  
cd .gitea/workflows/
# 参考 .gitea/workflows/CLAUDE.md

适用场景: 自动部署、构建流程、环境配置、工作流优化

📋 管理后台开发

# 切换到管理后台模块
cd admin/
# 参考 admin/CLAUDE.md

适用场景: 管理界面开发、用户管理、内容管理、权限控制

🔧 后端 API 开发

# 切换到后端模块
cd backend/
# 参考 backend/CLAUDE.md

适用场景: API 接口开发、数据库设计、认证服务、文件存储

🎨 UI 备份和实验

# 切换到 UI 备份模块
cd ui/
# 参考 ui/CLAUDE.md

适用场景: 组件备份、A/B 测试、实验性功能、版本对比

📚 文档和架构

# 在根目录工作
# 参考当前 CLAUDE.md

适用场景: 项目架构、文档更新、模块协调、整体规划

🚀 快速开始

开发环境设置

# 1. 克隆项目
git clone <repository>
cd photography

# 2. 前端开发
cd frontend/
make setup     # 初始化环境
make quick     # 安装依赖 + 启动开发服务器

部署设置（首次）

# 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

📋 常用命令

项目级命令

# 前端开发
cd frontend && make dev

# 管理后台开发 (使用 Bun)
cd admin && make quick      # 快速启动 (推荐)
cd admin && make dev        # 开发服务器

# 代码检查  
cd frontend && make lint
cd admin && make lint

# 构建项目
cd frontend && make build
cd admin && make build

# 部署准备
cd frontend && make deploy-prep
cd admin && make deploy-prep

Git 工作流

# 开发流程
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
• 管理后台问题: 查看 admin/CLAUDE.md
• 后端问题: 查看 backend/CLAUDE.md
• UI 备份问题: 查看 ui/CLAUDE.md

通用问题

# 检查项目状态
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 (架构设计完成)
• 📋 UI 备份系统 (已实现)

计划中功能

• 📋 多环境部署
• 📋 性能监控
• 📋 AI 功能集成
• 📋 数据分析系统

🎨 模块协调原则

何时修改模块 CLAUDE.md

1. 前端模块 (frontend/CLAUDE.md): 组件、样式、前端逻辑变更时
2. 部署模块 (docs/deployment/CLAUDE.md): 服务器、配置、部署流程变更时
3. CI/CD 模块 (.gitea/workflows/CLAUDE.md): 工作流、构建流程变更时
4. 管理后台模块 (admin/CLAUDE.md): 后台功能、权限管理变更时
5. 后端模块 (backend/CLAUDE.md): API 接口、数据库架构变更时
6. UI 备份模块 (ui/CLAUDE.md): 组件备份、实验功能变更时
7. 根目录 (CLAUDE.md): 项目架构、模块关系变更时

模块间通信

• 前端 ↔ 后端: API 接口调用和数据交换
• 管理后台 ↔ 后端: 管理接口和数据操作
• UI 备份 ↔ 前端: 组件同步和实验功能验证
• 前端构建产物 → 部署模块: 静态文件部署
• CI/CD 协调 → 所有模块: 构建和部署流程
• 配置变更 → 相关模块: CLAUDE.md 同步更新

🔄 最佳实践

开发流程

1. 确定工作模块，切换到对应目录
2. 阅读模块的 CLAUDE.md 了解具体指导
3. 完成开发和测试
4. 更新相关模块的 CLAUDE.md (如有必要)
5. 提交代码触发自动部署

文档维护

• 模块独立: 每个模块的 CLAUDE.md 保持独立和聚焦
• 架构统一: 模块间的依赖关系在根目录 CLAUDE.md 中说明
• 配置集中: 重要的全局配置统一在根目录管理
• 及时更新: 功能变更后立即更新对应的 CLAUDE.md
• 一致性: 保持各模块文档的格式和风格一致

上下文优化

• 聚焦开发: Claude 工作时只需关注单个模块的 CLAUDE.md
• 减少负载: 避免加载无关模块的文档，减少上下文长度
• 提高效率: 模块化降低复杂性，提高开发效率
• 避免幻觉: 精确的模块指导减少 AI 产生错误信息的可能性
• 快速定位: 问题出现时能快速定位到相关模块和文档

📋 模块 CLAUDE.md 文件列表

核心模块

• ✅ 根目录 (CLAUDE.md) - 项目总览和模块协调
• ✅ 前端模块 (frontend/CLAUDE.md) - 前端开发指导
• ✅ 部署模块 (docs/deployment/CLAUDE.md) - 部署配置指导
• ✅ CI/CD 模块 (.gitea/workflows/CLAUDE.md) - 自动化部署指导

新增模块

• ✅ 管理后台模块 (admin/CLAUDE.md) - 管理界面开发指导
• ✅ 后端模块 (backend/CLAUDE.md) - API 服务开发指导
• ✅ UI 备份模块 (ui/CLAUDE.md) - 组件备份和实验指导

辅助模块

• ✅ 工具脚本 (scripts/README.md) - 自动化脚本说明

🎯 使用建议

选择正确的模块

1. 明确任务类型: 根据要解决的问题选择对应的模块
2. 切换工作目录: 进入相应的模块目录进行开发
3. 参考模块文档: 仔细阅读模块的 CLAUDE.md 文件
4. 遵循模块规范: 按照模块的开发规范和流程进行工作

跨模块协作

1. 理解依赖关系: 了解模块间的依赖和数据流向
2. 协调接口变更: 涉及多个模块时，确保接口一致性
3. 同步更新文档: 跨模块变更时，同步更新相关文档
4. 测试集成功能: 确保模块间的集成功能正常工作