From 9e381c783de2eeffc6c31294cf21c97aa347d53a Mon Sep 17 00:00:00 2001
From: xujiang <xujiang@boohee.com>
Date: Wed, 9 Jul 2025 10:54:08 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E9=87=8D=E6=9E=84=E9=A1=B9=E7=9B=AE?=
 =?UTF-8?q?=E4=B8=BA=E6=A8=A1=E5=9D=97=E5=8C=96=E7=BB=93=E6=9E=84=EF=BC=8C?=
 =?UTF-8?q?=E6=8B=86=E5=88=86=20CLAUDE.md=20=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## 📁 模块化重构

### 新增模块 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 工作时只需关注单个模块的文档，大幅提升处理效率！
---
 .gitea/workflows/CLAUDE.md            | 244 +++++++++++++++
 CLAUDE.md                             | 425 ++++++++++++--------------
 docs/deployment/CLAUDE.md             | 226 ++++++++++++++
 docs/{ => 原始 prd}/UI设计需求文档.md |   0
 docs/{ => 原始 prd}/前端开发文档.md   |   0
 docs/{ => 原始 prd}/后端开发文档.md   |   0
 docs/{ => 原始 prd}/测试需求文档.md   |   0
 frontend/CLAUDE.md                    | 226 ++++++++++++++
 lint-staged.config.js                 |   5 +
 scripts/README.md                     |  67 ++++
 scripts/update-claude-docs.sh         | 151 +++++++++
 11 files changed, 1122 insertions(+), 222 deletions(-)
 create mode 100644 .gitea/workflows/CLAUDE.md
 create mode 100644 docs/deployment/CLAUDE.md
 rename docs/{ => 原始 prd}/UI设计需求文档.md (100%)
 rename docs/{ => 原始 prd}/前端开发文档.md (100%)
 rename docs/{ => 原始 prd}/后端开发文档.md (100%)
 rename docs/{ => 原始 prd}/测试需求文档.md (100%)
 create mode 100644 frontend/CLAUDE.md
 create mode 100644 scripts/README.md
 create mode 100755 scripts/update-claude-docs.sh

diff --git a/.gitea/workflows/CLAUDE.md b/.gitea/workflows/CLAUDE.md
new file mode 100644
index 0000000..f8c86cc
--- /dev/null
+++ b/.gitea/workflows/CLAUDE.md
@@ -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 本地验证
+- 自动化测试覆盖 (计划)
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
index 8160357..a0576e0 100644
--- 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
\ No newline at end of file
+### 生产环境
+- **网站**: 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
+- 减少上下文长度，提高处理效率
+- 模块化降低复杂性，提高开发效率
\ No newline at end of file
diff --git a/docs/deployment/CLAUDE.md b/docs/deployment/CLAUDE.md
new file mode 100644
index 0000000..321d3a4
--- /dev/null
+++ b/docs/deployment/CLAUDE.md
@@ -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 集成
+- 多区域部署
+- 蓝绿部署
+- 自动回滚机制
\ No newline at end of file
diff --git a/docs/UI设计需求文档.md b/docs/原始 prd/UI设计需求文档.md
similarity index 100%
rename from docs/UI设计需求文档.md
rename to docs/原始 prd/UI设计需求文档.md
diff --git a/docs/前端开发文档.md b/docs/原始 prd/前端开发文档.md
similarity index 100%
rename from docs/前端开发文档.md
rename to docs/原始 prd/前端开发文档.md
diff --git a/docs/后端开发文档.md b/docs/原始 prd/后端开发文档.md
similarity index 100%
rename from docs/后端开发文档.md
rename to docs/原始 prd/后端开发文档.md
diff --git a/docs/测试需求文档.md b/docs/原始 prd/测试需求文档.md
similarity index 100%
rename from docs/测试需求文档.md
rename to docs/原始 prd/测试需求文档.md
diff --git a/frontend/CLAUDE.md b/frontend/CLAUDE.md
new file mode 100644
index 0000000..97c7dc2
--- /dev/null
+++ b/frontend/CLAUDE.md
@@ -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 进行样式管理
+- 配置了自动代码格式化和类型检查
\ No newline at end of file
diff --git a/lint-staged.config.js b/lint-staged.config.js
index 3675573..8f2ca18 100644
--- a/lint-staged.config.js
+++ b/lint-staged.config.js
@@ -11,4 +11,9 @@ module.exports = {
   'frontend/**/*.{ts,tsx,js,jsx,json,css,md}': [
     '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',
+  ],
 };
\ No newline at end of file
diff --git a/scripts/README.md b/scripts/README.md
new file mode 100644
index 0000000..996b9ef
--- /dev/null
+++ b/scripts/README.md
@@ -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 文档格式
+- 自动同步配置变更
+- 生成变更日志
\ No newline at end of file
diff --git a/scripts/update-claude-docs.sh b/scripts/update-claude-docs.sh
new file mode 100755
index 0000000..fa0f1d0
--- /dev/null
+++ b/scripts/update-claude-docs.sh
@@ -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
\ No newline at end of file