- 重构根目录CLAUDE.md为项目总览(60行精简版) - 细化backend模块CLAUDE.md为开发指南 - 新增各子模块CLAUDE.md文件: - api/desc/ - API定义模块 - internal/handler/ - 请求处理器 - internal/logic/ - 业务逻辑层 - internal/model/ - 数据模型层 - internal/middleware/ - 中间件层 - internal/svc/ - 服务上下文 - configs/ - 配置目录 - deploy/ - 部署配置 - pkg/ - 公共库 - scripts/ - 工具脚本 - configs/sql/ - SQL脚本 - 修复PostgreSQL SSL配置参数 - 清理旧的backend-old目录 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
336
CLAUDE.md
336
CLAUDE.md
@ -1,314 +1,62 @@
|
||||
# Photography Portfolio Project - CLAUDE.md
|
||||
# Photography Portfolio - 项目总览
|
||||
|
||||
此文件为 Claude Code 在此项目中工作时提供指导。本项目采用模块化结构,每个模块有独立的 CLAUDE.md 文件,所有给我看的提示都要用中文。
|
||||
> 📍 这是一个模块化摄影作品集项目,所有模块都有独立的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 # 脚本说明
|
||||
├── frontend/ # 🎨 前端Next.js应用
|
||||
├── admin/ # 📋 管理后台
|
||||
├── backend/ # 🔧 Go后端API
|
||||
├── docs/deployment/ # 🚀 部署配置
|
||||
├── .gitea/workflows/ # ⚙️ CI/CD流程
|
||||
├── ui/ # 🎨 UI备份
|
||||
└── scripts/ # 🛠️ 工具脚本
|
||||
```
|
||||
|
||||
## 🎯 模块化工作指南
|
||||
|
||||
### 根据工作内容选择模块
|
||||
|
||||
#### 🎨 前端开发
|
||||
```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
|
||||
# 切换到管理后台模块
|
||||
cd admin/
|
||||
# 参考 admin/CLAUDE.md
|
||||
```
|
||||
**适用场景**: 管理界面开发、用户管理、内容管理、权限控制
|
||||
|
||||
#### 🔧 后端 API 开发
|
||||
```bash
|
||||
# 切换到后端模块
|
||||
cd backend/
|
||||
# 参考 backend/CLAUDE.md
|
||||
```
|
||||
**适用场景**: API 接口开发、数据库设计、认证服务、文件存储
|
||||
|
||||
#### 🎨 UI 备份和实验
|
||||
```bash
|
||||
# 切换到 UI 备份模块
|
||||
cd ui/
|
||||
# 参考 ui/CLAUDE.md
|
||||
```
|
||||
**适用场景**: 组件备份、A/B 测试、实验性功能、版本对比
|
||||
|
||||
#### 📚 文档和架构
|
||||
```bash
|
||||
# 在根目录工作
|
||||
# 参考当前 CLAUDE.md
|
||||
```
|
||||
**适用场景**: 项目架构、文档更新、模块协调、整体规划
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 开发环境设置
|
||||
### 选择工作模块
|
||||
```bash
|
||||
# 1. 克隆项目
|
||||
git clone <repository>
|
||||
cd photography
|
||||
# 进入对应模块目录后,查看模块CLAUDE.md
|
||||
|
||||
# 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 && cat CLAUDE.md
|
||||
|
||||
# 后端开发
|
||||
cd backend && cat CLAUDE.md
|
||||
|
||||
# 部署配置
|
||||
cd docs/deployment && cat CLAUDE.md
|
||||
```
|
||||
|
||||
### 常用命令
|
||||
```bash
|
||||
# 前端
|
||||
cd frontend && make dev
|
||||
|
||||
# 管理后台开发 (使用 Bun)
|
||||
cd admin && make quick # 快速启动 (推荐)
|
||||
cd admin && make dev # 开发服务器
|
||||
# 后端
|
||||
cd backend && make run
|
||||
|
||||
# 代码检查
|
||||
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
|
||||
# 部署
|
||||
cd docs/deployment && ./deploy.sh
|
||||
```
|
||||
|
||||
### 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/` | Next.js前端 | `frontend/CLAUDE.md` |
|
||||
| `admin/` | 管理后台 | `admin/CLAUDE.md` |
|
||||
| `backend/` | Go API服务 | `backend/CLAUDE.md` |
|
||||
| `docs/deployment/` | 服务器部署 | `docs/deployment/CLAUDE.md` |
|
||||
|
||||
## 🔍 问题排查
|
||||
## 🔗 项目地址
|
||||
- **网站**: https://photography.iriver.top
|
||||
- **仓库**: Gitea自动部署
|
||||
|
||||
### 模块特定问题
|
||||
- **前端问题**: 查看 `frontend/CLAUDE.md`
|
||||
- **部署问题**: 查看 `docs/deployment/CLAUDE.md`
|
||||
- **CI/CD 问题**: 查看 `.gitea/workflows/CLAUDE.md`
|
||||
- **管理后台问题**: 查看 `admin/CLAUDE.md`
|
||||
- **后端问题**: 查看 `backend/CLAUDE.md`
|
||||
- **UI 备份问题**: 查看 `ui/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 (架构设计完成)
|
||||
- 📋 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. **测试集成功能**: 确保模块间的集成功能正常工作
|
||||
## 🎯 工作原则
|
||||
1. **模块化**: 每个目录独立工作
|
||||
2. **轻量级**: 只关注当前模块
|
||||
3. **文档化**: 每个模块都有专属指导
|
||||
Reference in New Issue
Block a user