feat: 重构项目为模块化结构，拆分 CLAUDE.md 文档
All checks were successful
Deploy Frontend / deploy (push) Successful in 2m38s
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 工作时只需关注单个模块的文档，大幅提升处理效率！
This commit is contained in:
xujiang
244
.gitea/workflows/CLAUDE.md
Normal file
244
.gitea/workflows/CLAUDE.md
Normal file
@ -0,0 +1,244 @@
|
|||||||
|
# CI/CD Module - CLAUDE.md
|
||||||
|
|
||||||
|
此文件为 Claude Code 在 CI/CD 模块中工作时提供指导。
|
||||||
|
|
||||||
|
## 模块说明
|
||||||
|
这是摄影作品集项目的 CI/CD 配置模块，使用 Gitea Actions 实现自动化部署。
|
||||||
|
|
||||||
|
## 工作流程
|
||||||
|
|
||||||
|
### 主要流程文件
|
||||||
|
- **`deploy-frontend.yml`** - 前端项目自动部署工作流
|
||||||
|
|
||||||
|
### 触发条件
|
||||||
|
```yaml
|
||||||
|
on:
|
||||||
|
push:
|
||||||
|
branches: [ main ]
|
||||||
|
paths: [ 'frontend/**' ]
|
||||||
|
pull_request:
|
||||||
|
branches: [ main ]
|
||||||
|
paths: [ 'frontend/**' ]
|
||||||
|
```
|
||||||
|
|
||||||
|
## 部署流程
|
||||||
|
|
||||||
|
### 自动化步骤
|
||||||
|
1. **代码检出** - `actions/checkout@v4`
|
||||||
|
2. **环境设置** - 配置 Bun 运行环境
|
||||||
|
3. **依赖安装** - `bun install`
|
||||||
|
4. **类型检查** - `bun run type-check`
|
||||||
|
5. **代码检查** - `bun run lint`
|
||||||
|
6. **项目构建** - `bun run build`
|
||||||
|
7. **服务器部署** - rsync 同步到服务器
|
||||||
|
8. **权限设置** - 确保文件权限正确
|
||||||
|
|
||||||
|
### 详细执行流程
|
||||||
|
```bash
|
||||||
|
# 1. 环境准备
|
||||||
|
- Checkout code (actions/checkout@v4)
|
||||||
|
- Setup Bun (oven-sh/setup-bun@v1)
|
||||||
|
|
||||||
|
# 2. 依赖和检查
|
||||||
|
cd frontend
|
||||||
|
bun install
|
||||||
|
bun run type-check
|
||||||
|
bun run lint
|
||||||
|
|
||||||
|
# 3. 构建
|
||||||
|
bun run build # 生成 frontend/out/ 目录
|
||||||
|
|
||||||
|
# 4. 部署
|
||||||
|
# 创建服务器目录
|
||||||
|
ssh gitea@server "mkdir -p ~/www/photography"
|
||||||
|
|
||||||
|
# 上传文件
|
||||||
|
rsync -avz frontend/out/ gitea@server:~/www/photography/
|
||||||
|
|
||||||
|
# 设置权限
|
||||||
|
ssh gitea@server "chmod -R 755 ~/www/photography"
|
||||||
|
```
|
||||||
|
|
||||||
|
## 服务器配置
|
||||||
|
|
||||||
|
### SSH 连接配置
|
||||||
|
使用密码认证连接到阿里云服务器：
|
||||||
|
```bash
|
||||||
|
export SSHPASS=${{ secrets.ALIYUN_PWD }}
|
||||||
|
sshpass -e ssh -o StrictHostKeyChecking=no ${{ secrets.ALIYUN_USER_NAME }}@${{ secrets.ALIYUN_IP }}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 必需的 Secrets
|
||||||
|
在 Gitea 仓库设置中配置：
|
||||||
|
- **`ALIYUN_IP`** - 服务器 IP 地址
|
||||||
|
- **`ALIYUN_USER_NAME`** - SSH 用户名 (gitea)
|
||||||
|
- **`ALIYUN_PWD`** - SSH 密码
|
||||||
|
|
||||||
|
### 部署目标
|
||||||
|
- **服务器路径**: `/home/gitea/www/photography/`
|
||||||
|
- **Web 服务**: Caddy (通过 photography.iriver.top 访问)
|
||||||
|
- **文件权限**: 755 (目录和文件)
|
||||||
|
|
||||||
|
## 构建配置
|
||||||
|
|
||||||
|
### Node.js 环境
|
||||||
|
- **运行环境**: ubuntu-latest
|
||||||
|
- **包管理器**: Bun (最新版本)
|
||||||
|
- **构建工具**: Next.js 15
|
||||||
|
|
||||||
|
### 构建产物
|
||||||
|
- **输出目录**: `frontend/out/`
|
||||||
|
- **文件类型**: 静态 HTML/CSS/JS/图片
|
||||||
|
- **构建模式**: 静态导出 (`output: 'export'`)
|
||||||
|
|
||||||
|
## 质量检查
|
||||||
|
|
||||||
|
### 代码质量门禁
|
||||||
|
```bash
|
||||||
|
# TypeScript 类型检查
|
||||||
|
bun run type-check
|
||||||
|
|
||||||
|
# ESLint 代码检查
|
||||||
|
bun run lint
|
||||||
|
|
||||||
|
# 构建验证
|
||||||
|
bun run build
|
||||||
|
```
|
||||||
|
|
||||||
|
### 检查失败处理
|
||||||
|
- 任何步骤失败都会终止部署
|
||||||
|
- 失败时发送通知消息
|
||||||
|
- 日志详细记录错误信息
|
||||||
|
|
||||||
|
## 部署策略
|
||||||
|
|
||||||
|
### 部署方式
|
||||||
|
- **增量部署**: rsync --delete 确保目标目录与源目录同步
|
||||||
|
- **原子性**: 先构建成功再部署，避免部分文件更新
|
||||||
|
- **回滚**: Git 版本控制，可快速回滚到之前版本
|
||||||
|
|
||||||
|
### 安全措施
|
||||||
|
- 使用 SSH 密钥或密码认证
|
||||||
|
- 禁用主机密钥检查（CI/CD 环境）
|
||||||
|
- 限制部署用户权限
|
||||||
|
|
||||||
|
## 监控和通知
|
||||||
|
|
||||||
|
### 部署状态
|
||||||
|
```yaml
|
||||||
|
- name: Notify success
|
||||||
|
if: success()
|
||||||
|
run: echo "✅ 前端项目部署成功！"
|
||||||
|
|
||||||
|
- name: Notify failure
|
||||||
|
if: failure()
|
||||||
|
run: echo "❌ 前端项目部署失败！"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 部署信息
|
||||||
|
- **部署路径**: `~/www/photography/`
|
||||||
|
- **访问地址**: `https://photography.iriver.top`
|
||||||
|
- **部署时间**: 自动记录
|
||||||
|
- **构建日志**: 完整保留
|
||||||
|
|
||||||
|
## 故障排除
|
||||||
|
|
||||||
|
### 常见部署错误
|
||||||
|
|
||||||
|
#### 1. SSH 连接失败
|
||||||
|
```bash
|
||||||
|
# 检查网络连接
|
||||||
|
ping ${{ secrets.ALIYUN_IP }}
|
||||||
|
|
||||||
|
# 验证 SSH 凭据
|
||||||
|
ssh gitea@${{ secrets.ALIYUN_IP }} "echo 'SSH 连接测试'"
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 2. 权限错误
|
||||||
|
```bash
|
||||||
|
# 检查目标目录权限
|
||||||
|
ssh gitea@server "ls -la ~/www/"
|
||||||
|
|
||||||
|
# 修复权限问题
|
||||||
|
ssh gitea@server "chmod -R 755 ~/www/photography"
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 3. 构建失败
|
||||||
|
```bash
|
||||||
|
# 本地测试构建
|
||||||
|
cd frontend
|
||||||
|
bun install
|
||||||
|
bun run build
|
||||||
|
|
||||||
|
# 检查构建输出
|
||||||
|
ls -la frontend/out/
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 4. rsync 同步失败
|
||||||
|
```bash
|
||||||
|
# 测试 rsync 连接
|
||||||
|
rsync --dry-run -avz frontend/out/ gitea@server:~/www/photography/
|
||||||
|
|
||||||
|
# 检查磁盘空间
|
||||||
|
ssh gitea@server "df -h"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 调试技巧
|
||||||
|
```bash
|
||||||
|
# 查看工作流日志
|
||||||
|
- 在 Gitea Actions 页面查看详细日志
|
||||||
|
- 每个步骤都有独立的日志输出
|
||||||
|
- 失败时会高亮错误信息
|
||||||
|
|
||||||
|
# 本地复现问题
|
||||||
|
- 使用相同的命令在本地测试
|
||||||
|
- 检查环境变量和依赖版本
|
||||||
|
- 验证构建产物正确性
|
||||||
|
```
|
||||||
|
|
||||||
|
## 性能优化
|
||||||
|
|
||||||
|
### 构建优化
|
||||||
|
- 使用 Bun 替代 npm (更快的包管理)
|
||||||
|
- 并行执行类型检查和代码检查
|
||||||
|
- 缓存 node_modules (计划中)
|
||||||
|
|
||||||
|
### 部署优化
|
||||||
|
- rsync 增量同步，只传输变更文件
|
||||||
|
- gzip 压缩传输内容
|
||||||
|
- 并行上传多个文件 (计划中)
|
||||||
|
|
||||||
|
## 扩展计划
|
||||||
|
|
||||||
|
### 多环境部署
|
||||||
|
- **开发环境**: dev.photography.iriver.top
|
||||||
|
- **预发布环境**: staging.photography.iriver.top
|
||||||
|
- **生产环境**: photography.iriver.top
|
||||||
|
|
||||||
|
### 高级功能
|
||||||
|
- **蓝绿部署**: 零停机时间部署
|
||||||
|
- **自动回滚**: 部署失败时自动回滚
|
||||||
|
- **性能测试**: 自动化性能基准测试
|
||||||
|
- **安全扫描**: 静态代码安全分析
|
||||||
|
|
||||||
|
### 通知集成
|
||||||
|
- 钉钉/企微通知
|
||||||
|
- 邮件通知
|
||||||
|
- Slack 集成
|
||||||
|
|
||||||
|
## 最佳实践
|
||||||
|
|
||||||
|
### 提交规范
|
||||||
|
- 遵循 Conventional Commits 规范
|
||||||
|
- 包含清晰的提交信息
|
||||||
|
- 关联 Issue 和 PR
|
||||||
|
|
||||||
|
### 分支策略
|
||||||
|
- **main**: 生产环境分支
|
||||||
|
- **develop**: 开发环境分支 (计划)
|
||||||
|
- **feature/***: 功能分支
|
||||||
|
|
||||||
|
### 代码质量
|
||||||
|
- 强制通过所有质量检查
|
||||||
|
- Pre-commit hooks 本地验证
|
||||||
|
- 自动化测试覆盖 (计划)
|
||||||
425
CLAUDE.md
425
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
|
- ⚡ 静态生成，极快加载速度
|
||||||
# 或者
|
- 🔒 自动 HTTPS (Let's Encrypt)
|
||||||
cd frontend && export PATH="$HOME/.bun/bin:$PATH" && bun run dev
|
- 🚀 CI/CD 自动部署
|
||||||
```
|
|
||||||
|
|
||||||
构建生产版本:
|
|
||||||
```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 # 项目指导文件
|
|
||||||
```
|
|
||||||
|
|
||||||
### 技术栈
|
### 技术栈
|
||||||
- **主目录**: `frontend/` - 包含 Next.js 应用
|
- **前端**: Next.js 15, React 19, TypeScript, Tailwind CSS
|
||||||
- **包管理器**: bun (比 npm/yarn 更快)
|
- **组件**: Radix UI + shadcn/ui
|
||||||
- **框架**: Next.js 15 配合 React 19, TypeScript 和 Tailwind CSS
|
- **部署**: Caddy + 静态文件
|
||||||
- **组件库**: Radix UI 组件配合 shadcn/ui
|
- **CI/CD**: Gitea Actions
|
||||||
- **数据获取**: TanStack Query (React Query) v5 配合 Axios
|
|
||||||
- **状态管理**: React hooks (useState, useEffect) 用于本地状态
|
|
||||||
- **样式**: Tailwind CSS 配合自定义主题配置
|
|
||||||
- **图像**: Next.js Image 组件，启用未优化设置
|
|
||||||
- **表单**: React Hook Form 配合 Zod 验证
|
|
||||||
- **主题**: next-themes 提供深色模式支持
|
|
||||||
|
|
||||||
## 关键组件
|
## 📁 项目结构
|
||||||
|
|
||||||
- `app/page.tsx` - 主应用，包含照片画廊、时间轴、关于和联系页面
|
```
|
||||||
- `components/photo-gallery.tsx` - 基于网格的照片画廊，带悬停效果
|
photography/
|
||||||
- `components/navigation.tsx` - 粘性导航，带移动菜单
|
├── CLAUDE.md # 🔍 当前文件 - 项目总览
|
||||||
- `components/photo-modal.tsx` - 照片详情模态框，带导航
|
├── lint-staged.config.js # Pre-commit 配置
|
||||||
- `components/timeline-view.tsx` - 基于时间轴的照片展示
|
├── frontend/ # 🎨 前端模块
|
||||||
- `components/timeline-stats.tsx` - 时间轴统计信息
|
│ ├── CLAUDE.md # 前端开发指导
|
||||||
- `components/filter-bar.tsx` - 照片分类过滤
|
│ ├── app/, components/, lib/ # Next.js 应用
|
||||||
- `components/about-view.tsx` - 关于页面组件
|
│ ├── package.json, Makefile # 构建工具
|
||||||
- `components/contact-view.tsx` - 联系页面组件
|
│ └── out/ # 静态导出目录
|
||||||
- `components/theme-provider.tsx` - 主题提供者（深色模式支持）
|
├── docs/ # 📚 文档模块
|
||||||
- `components/providers/query-provider.tsx` - TanStack Query 提供者
|
│ └── deployment/ # 🚀 部署模块
|
||||||
- `components/loading-spinner.tsx` - 加载动画组件
|
│ ├── CLAUDE.md # 部署配置指导
|
||||||
- `components/ui/` - 来自 shadcn/ui 的可重用 UI 组件
|
│ ├── Caddyfile # Web 服务器配置
|
||||||
- `lib/api.ts` - 使用 axios 的 API 配置
|
│ ├── fix-caddy-permissions.sh # 权限修复脚本
|
||||||
- `lib/queries.ts` - 用于数据获取的 TanStack Query hooks
|
│ └── caddy-setup.md # 部署文档
|
||||||
- `lib/utils.ts` - 工具函数
|
├── .gitea/workflows/ # ⚙️ CI/CD 模块
|
||||||
- `hooks/use-mobile.tsx` - 移动端检测钩子
|
│ ├── CLAUDE.md # CI/CD 配置指导
|
||||||
- `hooks/use-toast.ts` - 通知钩子
|
│ └── deploy-frontend.yml # 自动部署工作流
|
||||||
|
├── admin/ # 📋 管理后台 (预留)
|
||||||
## 数据结构
|
├── backend/ # 🔧 后端 API (预留)
|
||||||
|
└── ui/ # 🎨 UI 组件备份
|
||||||
从 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
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 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
|
```bash
|
||||||
cd frontend && node mock-api.js
|
# 切换到前端模块
|
||||||
|
cd frontend/
|
||||||
|
# 参考 frontend/CLAUDE.md
|
||||||
```
|
```
|
||||||
|
**适用场景**: UI 组件开发、样式调整、前端功能实现、React/Next.js 相关工作
|
||||||
|
|
||||||
## 环境变量
|
#### 🚀 部署配置
|
||||||
|
```bash
|
||||||
`.env.local` 中需要的环境变量：
|
# 切换到部署模块
|
||||||
```
|
cd docs/deployment/
|
||||||
NEXT_PUBLIC_API_URL=http://localhost:3001/api
|
# 参考 docs/deployment/CLAUDE.md
|
||||||
```
|
```
|
||||||
|
**适用场景**: 服务器配置、Caddy 设置、权限问题、域名配置、SSL 证书
|
||||||
|
|
||||||
## 配置说明
|
#### ⚙️ CI/CD 流程
|
||||||
|
|
||||||
### 关键配置文件
|
|
||||||
- **`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 配置
|
|
||||||
|
|
||||||
### 快速开始工作流程
|
|
||||||
```bash
|
```bash
|
||||||
cd frontend
|
# 切换到 CI/CD 模块
|
||||||
make quick # 安装依赖并启动开发服务器
|
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 快得多
|
# 2. 推送代码自动部署
|
||||||
- 锁定文件是 `bun.lockb` 而不是 `package-lock.json`
|
git push origin main
|
||||||
- 使用 `bun add` 而不是 `npm install` 来添加包
|
```
|
||||||
- 在 `.bunfig.toml` 中配置 bun 特定设置
|
|
||||||
|
|
||||||
## 项目当前状态
|
## 🔧 全局配置
|
||||||
|
|
||||||
- **Frontend**: 完全功能性的摄影作品集应用，包含完整的 UI 组件库
|
### Git Hooks (Pre-commit)
|
||||||
- **Backend**: 空目录，预留给未来的 API 开发
|
项目配置了 pre-commit hooks，会在提交前自动运行：
|
||||||
- **Admin**: 空目录，预留给未来的管理后台开发
|
- ESLint 代码检查
|
||||||
- **UI**: 组件备份目录，非活跃开发状态
|
- TypeScript 类型检查
|
||||||
|
- Prettier 代码格式化
|
||||||
|
|
||||||
## 已知问题和解决方案
|
配置文件：`lint-staged.config.js`
|
||||||
|
|
||||||
### 水合错误修复
|
### 环境要求
|
||||||
- **问题**: React hydration mismatch 错误，由 next-themes 引起
|
- **Node.js**: 18+
|
||||||
- **解决方案**: 在 `components/theme-provider.tsx` 中使用 `mounted` 状态，防止服务端/客户端渲染不匹配
|
- **Bun**: 最新版本 (包管理器)
|
||||||
|
- **Git**: 2.0+
|
||||||
|
|
||||||
### 开发环境配置
|
## 🌐 访问地址
|
||||||
- 构建时忽略 TypeScript 和 ESLint 错误（适用于开发环境）
|
|
||||||
- 图像未优化设置，便于开发调试
|
|
||||||
- 端口自动检测（如果 3000 被占用，会尝试 3001、3002 等）
|
|
||||||
- 使用 Prettier 进行代码格式化
|
|
||||||
- 支持通过 `make format` 统一代码风格
|
|
||||||
|
|
||||||
## 文件锁定和包管理
|
### 生产环境
|
||||||
- 使用 `bun.lockb` 而非 `package-lock.json` 作为锁定文件
|
- **网站**: https://photography.iriver.top
|
||||||
- 项目名称：`my-v0-project`（可能需要更新为更合适的名称）
|
- **部署**: 自动部署到 `/home/gitea/www/photography/`
|
||||||
- 所有包管理操作都应通过 Makefile 命令执行，确保使用 bun
|
|
||||||
|
### 开发环境
|
||||||
|
- **本地**: 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
|
||||||
|
- 减少上下文长度，提高处理效率
|
||||||
|
- 模块化降低复杂性，提高开发效率
|
||||||
226
docs/deployment/CLAUDE.md
Normal file
226
docs/deployment/CLAUDE.md
Normal file
@ -0,0 +1,226 @@
|
|||||||
|
# Deployment Module - CLAUDE.md
|
||||||
|
|
||||||
|
此文件为 Claude Code 在部署模块中工作时提供指导。
|
||||||
|
|
||||||
|
## 模块说明
|
||||||
|
这是摄影作品集项目的部署配置模块，包含 Web 服务器配置、权限脚本和部署文档。
|
||||||
|
|
||||||
|
## 部署架构
|
||||||
|
|
||||||
|
### 当前部署方案
|
||||||
|
- **前端**: 静态文件部署到 `/home/gitea/www/photography/`
|
||||||
|
- **Web 服务器**: Caddy (自动 HTTPS + Let's Encrypt)
|
||||||
|
- **域名**: https://photography.iriver.top
|
||||||
|
- **CI/CD**: Gitea Actions 自动部署
|
||||||
|
|
||||||
|
## 文件说明
|
||||||
|
|
||||||
|
### 配置文件
|
||||||
|
- **`Caddyfile`** - Caddy Web 服务器配置文件
|
||||||
|
- **`fix-caddy-permissions.sh`** - Caddy 权限修复脚本
|
||||||
|
|
||||||
|
### 文档
|
||||||
|
- **`caddy-setup.md`** - Caddy 服务器配置和部署指南
|
||||||
|
- **`README.md`** - 部署文档概览
|
||||||
|
|
||||||
|
## 部署流程
|
||||||
|
|
||||||
|
### 自动部署（推荐）
|
||||||
|
```bash
|
||||||
|
# 1. 推送代码触发 CI/CD
|
||||||
|
git push origin main
|
||||||
|
|
||||||
|
# CI/CD 会自动执行：
|
||||||
|
# - 安装依赖 (bun install)
|
||||||
|
# - 类型检查 (bun run type-check)
|
||||||
|
# - 代码检查 (bun run lint)
|
||||||
|
# - 构建项目 (bun run build)
|
||||||
|
# - 部署到服务器 (rsync 到 ~/www/photography/)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 手动部署
|
||||||
|
```bash
|
||||||
|
# 1. 构建前端项目
|
||||||
|
cd frontend && make build
|
||||||
|
|
||||||
|
# 2. 上传静态文件
|
||||||
|
rsync -avz frontend/out/ user@server:~/www/photography/
|
||||||
|
|
||||||
|
# 3. 设置权限
|
||||||
|
ssh user@server 'chmod -R 755 ~/www/photography'
|
||||||
|
```
|
||||||
|
|
||||||
|
## Caddy 配置
|
||||||
|
|
||||||
|
### 主要功能
|
||||||
|
- **自动 HTTPS**: Let's Encrypt 证书自动获取和续期
|
||||||
|
- **静态文件服务**: 直接提供 HTML/CSS/JS/图片
|
||||||
|
- **Gzip 压缩**: 减少传输大小
|
||||||
|
- **缓存控制**: 静态资源长期缓存，HTML 短期缓存
|
||||||
|
- **安全头**: XSS 保护、防点击劫持等
|
||||||
|
- **错误处理**: 404 重定向到 404.html
|
||||||
|
|
||||||
|
### 配置特点
|
||||||
|
```bash
|
||||||
|
# 域名
|
||||||
|
photography.iriver.top
|
||||||
|
|
||||||
|
# 根目录
|
||||||
|
root * /home/gitea/www/photography
|
||||||
|
|
||||||
|
# 安全和性能优化
|
||||||
|
encode gzip
|
||||||
|
header Cache-Control "public, max-age=31536000" @static
|
||||||
|
header X-Frame-Options "SAMEORIGIN"
|
||||||
|
```
|
||||||
|
|
||||||
|
## 服务器配置
|
||||||
|
|
||||||
|
### 初次配置（仅需一次）
|
||||||
|
```bash
|
||||||
|
# 1. 上传 Caddy 配置
|
||||||
|
scp docs/deployment/Caddyfile user@server:/etc/caddy/Caddyfile
|
||||||
|
|
||||||
|
# 2. 修复权限问题
|
||||||
|
scp docs/deployment/fix-caddy-permissions.sh user@server:~/
|
||||||
|
ssh user@server './fix-caddy-permissions.sh'
|
||||||
|
|
||||||
|
# 3. 重新加载 Caddy
|
||||||
|
ssh user@server 'sudo systemctl reload caddy'
|
||||||
|
|
||||||
|
# 4. 验证状态
|
||||||
|
ssh user@server 'sudo systemctl status caddy'
|
||||||
|
```
|
||||||
|
|
||||||
|
### 权限修复脚本功能
|
||||||
|
`fix-caddy-permissions.sh` 脚本会：
|
||||||
|
- 设置 `/home/gitea` 目录权限为 755
|
||||||
|
- 设置 `/home/gitea/www` 权限为 755
|
||||||
|
- 设置 `/home/gitea/www/photography` 权限为 755
|
||||||
|
- 确保 caddy 用户可以访问所有必要文件
|
||||||
|
|
||||||
|
## 故障排除
|
||||||
|
|
||||||
|
### 常见问题
|
||||||
|
|
||||||
|
#### 1. Permission denied 错误
|
||||||
|
```bash
|
||||||
|
# 检查权限
|
||||||
|
ls -la /home/gitea/www/photography
|
||||||
|
|
||||||
|
# 运行修复脚本
|
||||||
|
./fix-caddy-permissions.sh
|
||||||
|
|
||||||
|
# 验证 caddy 用户访问
|
||||||
|
sudo -u caddy ls -la /home/gitea/www/photography
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 2. 404 Not Found 错误
|
||||||
|
```bash
|
||||||
|
# 检查文件是否存在
|
||||||
|
ls -la /home/gitea/www/photography/index.html
|
||||||
|
|
||||||
|
# 检查 Caddy 配置
|
||||||
|
sudo caddy validate --config /etc/caddy/Caddyfile
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 3. SSL 证书问题
|
||||||
|
```bash
|
||||||
|
# 检查域名 DNS 记录
|
||||||
|
dig photography.iriver.top
|
||||||
|
|
||||||
|
# 查看 Caddy 日志
|
||||||
|
sudo journalctl -u caddy -f
|
||||||
|
```
|
||||||
|
|
||||||
|
### 日志查看
|
||||||
|
```bash
|
||||||
|
# 系统日志
|
||||||
|
sudo journalctl -u caddy -f
|
||||||
|
|
||||||
|
# Caddy 访问日志
|
||||||
|
sudo tail -f /var/log/caddy/photography.log
|
||||||
|
```
|
||||||
|
|
||||||
|
## 安全配置
|
||||||
|
|
||||||
|
### SSL/TLS
|
||||||
|
- 自动获取 Let's Encrypt 证书
|
||||||
|
- 强制 HTTPS 重定向
|
||||||
|
- HSTS 头启用（max-age=31536000）
|
||||||
|
|
||||||
|
### 安全头
|
||||||
|
- `X-Frame-Options: SAMEORIGIN` - 防止点击劫持
|
||||||
|
- `X-Content-Type-Options: nosniff` - 防止 MIME 嗅探
|
||||||
|
- `X-XSS-Protection: 1; mode=block` - XSS 保护
|
||||||
|
|
||||||
|
### 访问控制
|
||||||
|
- 静态文件直接服务，无需特殊权限
|
||||||
|
- 目录浏览禁用
|
||||||
|
- 隐藏服务器版本信息
|
||||||
|
|
||||||
|
## 性能优化
|
||||||
|
|
||||||
|
### 缓存策略
|
||||||
|
```bash
|
||||||
|
# 静态资源（1年缓存）
|
||||||
|
*.css, *.js, *.png, *.jpg, *.woff2
|
||||||
|
Cache-Control: public, max-age=31536000, immutable
|
||||||
|
|
||||||
|
# HTML 文件（1小时缓存）
|
||||||
|
*.html
|
||||||
|
Cache-Control: public, max-age=3600
|
||||||
|
```
|
||||||
|
|
||||||
|
### 压缩
|
||||||
|
- Gzip 压缩所有文本文件
|
||||||
|
- 自动内容编码协商
|
||||||
|
|
||||||
|
### 日志轮转
|
||||||
|
- 日志文件大小：10MB 轮转
|
||||||
|
- 保留文件数：5个
|
||||||
|
- JSON 格式便于分析
|
||||||
|
|
||||||
|
## 监控
|
||||||
|
|
||||||
|
### 健康检查
|
||||||
|
```bash
|
||||||
|
# 检查服务状态
|
||||||
|
sudo systemctl status caddy
|
||||||
|
|
||||||
|
# 检查端口监听
|
||||||
|
sudo netstat -tulpn | grep :443
|
||||||
|
|
||||||
|
# 测试 HTTPS 连接
|
||||||
|
curl -I https://photography.iriver.top
|
||||||
|
```
|
||||||
|
|
||||||
|
### 性能监控
|
||||||
|
- 访问日志分析
|
||||||
|
- 响应时间监控
|
||||||
|
- 错误率统计
|
||||||
|
|
||||||
|
## 备份策略
|
||||||
|
|
||||||
|
### 配置备份
|
||||||
|
- Caddyfile 版本控制（Git）
|
||||||
|
- 自动配置备份到 S3/对象存储
|
||||||
|
|
||||||
|
### 数据备份
|
||||||
|
- 静态文件通过 CI/CD 自动同步
|
||||||
|
- 日志文件定期归档
|
||||||
|
|
||||||
|
## 扩展计划
|
||||||
|
|
||||||
|
### 支持的部署平台
|
||||||
|
- ✅ **Caddy + Static Files** (当前)
|
||||||
|
- 📋 Vercel (计划)
|
||||||
|
- 📋 Netlify (计划)
|
||||||
|
- 📋 Docker (计划)
|
||||||
|
- 📋 Kubernetes (长期计划)
|
||||||
|
|
||||||
|
### 功能扩展
|
||||||
|
- CDN 集成
|
||||||
|
- 多区域部署
|
||||||
|
- 蓝绿部署
|
||||||
|
- 自动回滚机制
|
||||||
226
frontend/CLAUDE.md
Normal file
226
frontend/CLAUDE.md
Normal file
@ -0,0 +1,226 @@
|
|||||||
|
# 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 进行样式管理
|
||||||
|
- 配置了自动代码格式化和类型检查
|
||||||
@ -11,4 +11,9 @@ module.exports = {
|
|||||||
'frontend/**/*.{ts,tsx,js,jsx,json,css,md}': [
|
'frontend/**/*.{ts,tsx,js,jsx,json,css,md}': [
|
||||||
'cd frontend && export PATH="$HOME/.bun/bin:$PATH" && bun run format',
|
'cd frontend && export PATH="$HOME/.bun/bin:$PATH" && bun run format',
|
||||||
],
|
],
|
||||||
|
|
||||||
|
// 当项目结构发生变化时，自动更新 CLAUDE.md 文档
|
||||||
|
'{frontend/**,docs/deployment/**,.gitea/workflows/**,CLAUDE.md}': [
|
||||||
|
'./scripts/update-claude-docs.sh',
|
||||||
|
],
|
||||||
};
|
};
|
||||||
67
scripts/README.md
Normal file
67
scripts/README.md
Normal file
@ -0,0 +1,67 @@
|
|||||||
|
# 项目脚本
|
||||||
|
|
||||||
|
本目录包含项目维护和自动化脚本。
|
||||||
|
|
||||||
|
## 脚本说明
|
||||||
|
|
||||||
|
### update-claude-docs.sh
|
||||||
|
**用途**: 自动更新各模块的 CLAUDE.md 文档时间戳
|
||||||
|
|
||||||
|
**功能**:
|
||||||
|
- 检测项目文件变更
|
||||||
|
- 自动更新相关模块的 CLAUDE.md 最后更新时间
|
||||||
|
- 验证所有 CLAUDE.md 文件完整性
|
||||||
|
|
||||||
|
**使用方法**:
|
||||||
|
```bash
|
||||||
|
# 手动运行
|
||||||
|
./scripts/update-claude-docs.sh
|
||||||
|
|
||||||
|
# 自动运行 (通过 pre-commit hooks)
|
||||||
|
git commit -m "update: 修改前端组件" # 自动触发
|
||||||
|
```
|
||||||
|
|
||||||
|
**触发条件**:
|
||||||
|
- `frontend/` 目录变更 → 更新 `frontend/CLAUDE.md`
|
||||||
|
- `docs/deployment/` 目录变更 → 更新 `docs/deployment/CLAUDE.md`
|
||||||
|
- `.gitea/workflows/` 目录变更 → 更新 `.gitea/workflows/CLAUDE.md`
|
||||||
|
- `CLAUDE.md` 变更 → 更新根目录时间戳
|
||||||
|
|
||||||
|
## 自动化集成
|
||||||
|
|
||||||
|
### Pre-commit Hooks
|
||||||
|
脚本已集成到 pre-commit hooks 中，会在以下情况自动运行：
|
||||||
|
- 提交涉及模块文件变更时
|
||||||
|
- 自动更新时间戳并包含在本次提交中
|
||||||
|
|
||||||
|
### 配置文件
|
||||||
|
- **lint-staged.config.js** - 配置自动触发规则
|
||||||
|
- **package.json** - 项目脚本配置
|
||||||
|
|
||||||
|
## 最佳实践
|
||||||
|
|
||||||
|
### 开发流程
|
||||||
|
1. 正常开发和修改文件
|
||||||
|
2. 使用 `git add` 添加变更
|
||||||
|
3. 使用 `git commit` 提交（自动触发脚本）
|
||||||
|
4. 脚本自动更新相关 CLAUDE.md 文档
|
||||||
|
5. 时间戳更新会包含在提交中
|
||||||
|
|
||||||
|
### 手动维护
|
||||||
|
如果需要手动更新文档：
|
||||||
|
```bash
|
||||||
|
# 运行脚本
|
||||||
|
./scripts/update-claude-docs.sh
|
||||||
|
|
||||||
|
# 提交更新
|
||||||
|
git add .
|
||||||
|
git commit -m "docs: 更新 CLAUDE.md 文档"
|
||||||
|
```
|
||||||
|
|
||||||
|
## 扩展计划
|
||||||
|
|
||||||
|
### 未来功能
|
||||||
|
- 自动生成模块依赖图
|
||||||
|
- 检查 CLAUDE.md 文档格式
|
||||||
|
- 自动同步配置变更
|
||||||
|
- 生成变更日志
|
||||||
151
scripts/update-claude-docs.sh
Executable file
151
scripts/update-claude-docs.sh
Executable file
@ -0,0 +1,151 @@
|
|||||||
|
#!/bin/bash
|
||||||
|
|
||||||
|
# 自动更新 CLAUDE.md 文档脚本
|
||||||
|
# 当项目结构发生变化时，自动同步更新相关模块的 CLAUDE.md
|
||||||
|
|
||||||
|
set -e
|
||||||
|
|
||||||
|
echo "📝 开始更新 CLAUDE.md 文档..."
|
||||||
|
|
||||||
|
# 定义颜色输出
|
||||||
|
RED='\033[0;31m'
|
||||||
|
GREEN='\033[0;32m'
|
||||||
|
YELLOW='\033[1;33m'
|
||||||
|
NC='\033[0m' # No Color
|
||||||
|
|
||||||
|
# 检查是否在项目根目录
|
||||||
|
if [ ! -f "CLAUDE.md" ]; then
|
||||||
|
echo -e "${RED}❌ 请在项目根目录运行此脚本${NC}"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# 获取当前日期
|
||||||
|
CURRENT_DATE=$(date +"%Y-%m-%d %H:%M:%S")
|
||||||
|
|
||||||
|
# 更新根目录 CLAUDE.md 的最后更新时间
|
||||||
|
update_root_claude_md() {
|
||||||
|
echo -e "${YELLOW}📋 更新根目录 CLAUDE.md...${NC}"
|
||||||
|
|
||||||
|
# 在文件末尾添加更新时间（如果不存在）
|
||||||
|
if ! grep -q "最后更新时间" CLAUDE.md; then
|
||||||
|
echo "" >> CLAUDE.md
|
||||||
|
echo "---" >> CLAUDE.md
|
||||||
|
echo "**最后更新时间**: $CURRENT_DATE" >> CLAUDE.md
|
||||||
|
else
|
||||||
|
# 更新现有的时间戳
|
||||||
|
sed -i.bak "s/\*\*最后更新时间\*\*:.*/\*\*最后更新时间\*\*: $CURRENT_DATE/" CLAUDE.md
|
||||||
|
rm CLAUDE.md.bak
|
||||||
|
fi
|
||||||
|
}
|
||||||
|
|
||||||
|
# 检查前端模块变更
|
||||||
|
check_frontend_changes() {
|
||||||
|
echo -e "${YELLOW}🎨 检查前端模块变更...${NC}"
|
||||||
|
|
||||||
|
# 检查前端相关文件是否变更
|
||||||
|
if git diff --name-only HEAD~1 2>/dev/null | grep -E "^frontend/" > /dev/null; then
|
||||||
|
echo -e "${GREEN}✅ 检测到前端模块变更${NC}"
|
||||||
|
|
||||||
|
# 更新前端 CLAUDE.md 的时间戳
|
||||||
|
if [ -f "frontend/CLAUDE.md" ]; then
|
||||||
|
if ! grep -q "最后更新时间" frontend/CLAUDE.md; then
|
||||||
|
echo "" >> frontend/CLAUDE.md
|
||||||
|
echo "---" >> frontend/CLAUDE.md
|
||||||
|
echo "**最后更新时间**: $CURRENT_DATE" >> frontend/CLAUDE.md
|
||||||
|
else
|
||||||
|
sed -i.bak "s/\*\*最后更新时间\*\*:.*/\*\*最后更新时间\*\*: $CURRENT_DATE/" frontend/CLAUDE.md
|
||||||
|
rm frontend/CLAUDE.md.bak
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
}
|
||||||
|
|
||||||
|
# 检查部署模块变更
|
||||||
|
check_deployment_changes() {
|
||||||
|
echo -e "${YELLOW}🚀 检查部署模块变更...${NC}"
|
||||||
|
|
||||||
|
# 检查部署相关文件是否变更
|
||||||
|
if git diff --name-only HEAD~1 2>/dev/null | grep -E "^docs/deployment/|^\.gitea/workflows/" > /dev/null; then
|
||||||
|
echo -e "${GREEN}✅ 检测到部署模块变更${NC}"
|
||||||
|
|
||||||
|
# 更新部署 CLAUDE.md 的时间戳
|
||||||
|
if [ -f "docs/deployment/CLAUDE.md" ]; then
|
||||||
|
if ! grep -q "最后更新时间" docs/deployment/CLAUDE.md; then
|
||||||
|
echo "" >> docs/deployment/CLAUDE.md
|
||||||
|
echo "---" >> docs/deployment/CLAUDE.md
|
||||||
|
echo "**最后更新时间**: $CURRENT_DATE" >> docs/deployment/CLAUDE.md
|
||||||
|
else
|
||||||
|
sed -i.bak "s/\*\*最后更新时间\*\*:.*/\*\*最后更新时间\*\*: $CURRENT_DATE/" docs/deployment/CLAUDE.md
|
||||||
|
rm docs/deployment/CLAUDE.md.bak
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
}
|
||||||
|
|
||||||
|
# 检查 CI/CD 模块变更
|
||||||
|
check_cicd_changes() {
|
||||||
|
echo -e "${YELLOW}⚙️ 检查 CI/CD 模块变更...${NC}"
|
||||||
|
|
||||||
|
# 检查 CI/CD 相关文件是否变更
|
||||||
|
if git diff --name-only HEAD~1 2>/dev/null | grep -E "^\.gitea/workflows/" > /dev/null; then
|
||||||
|
echo -e "${GREEN}✅ 检测到 CI/CD 模块变更${NC}"
|
||||||
|
|
||||||
|
# 更新 CI/CD CLAUDE.md 的时间戳
|
||||||
|
if [ -f ".gitea/workflows/CLAUDE.md" ]; then
|
||||||
|
if ! grep -q "最后更新时间" .gitea/workflows/CLAUDE.md; then
|
||||||
|
echo "" >> .gitea/workflows/CLAUDE.md
|
||||||
|
echo "---" >> .gitea/workflows/CLAUDE.md
|
||||||
|
echo "**最后更新时间**: $CURRENT_DATE" >> .gitea/workflows/CLAUDE.md
|
||||||
|
else
|
||||||
|
sed -i.bak "s/\*\*最后更新时间\*\*:.*/\*\*最后更新时间\*\*: $CURRENT_DATE/" .gitea/workflows/CLAUDE.md
|
||||||
|
rm .gitea/workflows/CLAUDE.md.bak
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
}
|
||||||
|
|
||||||
|
# 验证所有 CLAUDE.md 文件存在
|
||||||
|
validate_claude_files() {
|
||||||
|
echo -e "${YELLOW}🔍 验证 CLAUDE.md 文件...${NC}"
|
||||||
|
|
||||||
|
local files=(
|
||||||
|
"CLAUDE.md"
|
||||||
|
"frontend/CLAUDE.md"
|
||||||
|
"docs/deployment/CLAUDE.md"
|
||||||
|
".gitea/workflows/CLAUDE.md"
|
||||||
|
)
|
||||||
|
|
||||||
|
for file in "${files[@]}"; do
|
||||||
|
if [ -f "$file" ]; then
|
||||||
|
echo -e "${GREEN}✅ $file 存在${NC}"
|
||||||
|
else
|
||||||
|
echo -e "${RED}❌ $file 不存在${NC}"
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
}
|
||||||
|
|
||||||
|
# 主函数
|
||||||
|
main() {
|
||||||
|
echo -e "${GREEN}🚀 CLAUDE.md 文档更新工具${NC}"
|
||||||
|
echo "================================================"
|
||||||
|
|
||||||
|
# 验证文件
|
||||||
|
validate_claude_files
|
||||||
|
|
||||||
|
# 更新根目录
|
||||||
|
update_root_claude_md
|
||||||
|
|
||||||
|
# 检查各模块变更
|
||||||
|
check_frontend_changes
|
||||||
|
check_deployment_changes
|
||||||
|
check_cicd_changes
|
||||||
|
|
||||||
|
echo "================================================"
|
||||||
|
echo -e "${GREEN}✅ CLAUDE.md 文档更新完成！${NC}"
|
||||||
|
echo -e "${YELLOW}💡 提示: 记得提交更新的文档${NC}"
|
||||||
|
}
|
||||||
|
|
||||||
|
# 如果是通过命令行直接运行
|
||||||
|
if [ "${BASH_SOURCE[0]}" == "${0}" ]; then
|
||||||
|
main "$@"
|
||||||
|
fi
|
||||||
Reference in New Issue
Block a user