feat: 重构CLAUDE.md文档体系，实现模块化轻量级设计

- 重构根目录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>
2025-07-16 13:16:01 +08:00
parent 28eef98a0b
commit 386666660f
94 changed files with 492 additions and 20878 deletions
--- a/backend/CLAUDE.md
+++ b/backend/CLAUDE.md
@ -1,245 +1,73 @@
-# Backend API Service - CLAUDE.md
+# Backend API - 开发指南

-本文件为 Claude Code 在后端 API 服务模块中工作时提供指导。
-
-## 🎯 模块概览
-
-这是一个基于 Go + go-zero 框架的 REST API 后端服务，利用 go-zero 生态工具快速开发，采用 go-zero 推荐的项目架构。
-
-### 主要特性
- 🏗️ go-zero 标准架构 (API → Logic → Model)
- 🚀 代码自动生成 (通过 .api 文件和 goctl 工具)
- 📊 多数据库支持 (PostgreSQL/SQLite 通过配置切换 + Redis)
- 🔐 JWT 认证 + 中间件系统
- 📁 文件上传和存储管理
- 🔗 链路追踪和监控
- 🛡️ 熔断、限流、负载均衡
- 📚 API 文档自动生成
-
-### 技术栈
- **语言**: Go 1.23+
- **框架**: go-zero v1.8.0+
- **数据库**: PostgreSQL/SQLite (通过配置切换) + Redis (缓存)
- **ORM**: GORM v1.30.0 (统一数据访问)
- **认证**: JWT (内置 JWT 支持)
- **日志**: go-zero 内置日志系统
- **配置**: go-zero 配置系统
- **工具**: goctl (代码生成工具)
- **容器化**: Docker + Docker Compose
-
-## 📁 go-zero 项目结构 (标准版)
-```
-backend/
-├── CLAUDE.md                          # 📋 当前文件 - 后端总览
-├── go.mod                             # Go 模块文件
-├── go.sum                             # 依赖锁定文件
-├── Makefile                           # 构建脚本
-├── cmd/                               # 🚀 应用入口目录
-│   ├── api/                           # API 服务入口
-│   │   └── main.go                    # API 服务主函数
-│   ├── rpc/                           # RPC 服务入口 (未来扩展)
-│   │   └── main.go                    # RPC 服务主函数
-│   └── job/                           # 任务服务入口 (未来扩展)
-│       └── main.go                    # 任务服务主函数
-├── api/                               # 🌐 API 定义目录
-│   ├── CLAUDE.md                      # API 模块开发指导
-│   └── desc/                          # 📝 API 定义文件目录
-│       ├── photography.api            # 📋 主 API 文件 (导入其他模块)
-│       ├── user.api                   # 用户接口定义
-│       ├── photo.api                  # 照片接口定义
-│       ├── category.api               # 分类接口定义
-│       ├── auth.api                   # 认证接口定义
-│       └── common.api                 # 公共类型定义
-├── etc/                               # ⚙️ 配置文件目录
-│   ├── photographyapi-api.yaml        # API 服务配置
-│   ├── photography-dev.yaml           # 开发环境配置
-│   ├── photography-prod.yaml          # 生产环境配置
-│   ├── photographyrpc.yaml            # RPC 服务配置 (未来)
-│   └── photographyjob.yaml            # 任务服务配置 (未来)
-├── internal/                          # 📦 内部模块 (goctl 自动生成)
-│   ├── config/                        # 配置结构
-│   │   └── config.go                  # 配置定义
-│   ├── handler/                       # 🎯 处理器 (goctl 自动生成)
-│   ├── logic/                         # 🧠 业务逻辑 (goctl 自动生成)
-│   ├── svc/                           # 🔧 服务上下文
-│   │   └── servicecontext.go          # 服务上下文定义
-│   ├── types/                         # 📦 类型定义 (goctl 自动生成)
-│   │   └── types.go                   # 请求/响应类型
-│   ├── middleware/                    # 🛡️ 中间件
-│   │   ├── auth.go                    # 认证中间件
-│   │   ├── cors.go                    # CORS 中间件
-│   │   └── logger.go                  # 日志中间件
-│   └── model/                         # 📊 数据模型模块 (内部)
-│       ├── CLAUDE.md                  # 数据模型开发指导
-│       ├── sql/                       # SQL 定义文件
-│       │   ├── user.sql               # 用户表结构
-│       │   ├── photo.sql              # 照片表结构
-│       │   └── category.sql           # 分类表结构
-│       ├── user.go                    # 用户模型 (goctl 自动生成)
-│       ├── photo.go                   # 照片模型 (goctl 自动生成)
-│       ├── category.go                # 分类模型 (goctl 自动生成)
-│       └── vars.go                    # 模型变量定义
-├── pkg/                               # 📦 可导出包 (业务解耦)
-│   ├── CLAUDE.md                      # 公共包开发指导
-│   ├── errorx/                        # 错误处理包
-│   │   └── errorx.go                  # 统一错误定义
-│   ├── response/                      # 响应处理包
-│   │   └── response.go                # 统一响应格式
-│   ├── utils/                         # 通用工具包
-│   │   ├── jwt/                       # JWT 工具
-│   │   │   └── jwt.go                 # JWT 实现
-│   │   ├── hash/                      # 哈希工具
-│   │   │   └── hash.go                # 哈希实现
-│   │   ├── file/                      # 文件处理工具
-│   │   │   └── file.go                # 文件处理实现
-│   │   └── database/                  # 数据库工具
-│   │       └── database.go            # 数据库连接工厂
-│   └── constants/                     # 常量定义包
-│       └── constants.go               # 全局常量定义
-├── configs/                           # 📋 静态配置文件目录
-│   ├── sql/                           # SQL 初始化文件
-│   │   ├── init.sql                   # 数据库初始化
-│   │   └── seed.sql                   # 种子数据
-│   └── docker/                        # Docker 相关配置
-│       ├── Dockerfile                 # Docker 镜像定义
-│       ├── docker-compose.yml         # 本地开发环境
-│       └── docker-compose.prod.yml    # 生产环境配置
-├── scripts/                           # 🛠️ 脚本目录
-│   ├── build.sh                       # 构建脚本
-│   ├── deploy.sh                      # 部署脚本
-│   └── gen-code.sh                    # 代码生成脚本
-├── deploy/                            # 🚀 部署配置
-│   ├── k8s/                           # Kubernetes 配置
-│   └── systemd/                       # Systemd 配置
-└── tests/                             # 🧪 测试模块 (简化)
-    ├── CLAUDE.md                      # 测试开发指导
-    ├── api_test.go                    # API 集成测试
-    └── benchmark_test.go              # 性能测试
-```
+> 🔧 Go + go-zero 后端API服务

 ## 🚀 快速开始

-### 环境准备
 ```bash
-# 1. 安装 Go 1.23+ 
-go version
+# 1. 进入目录
+cd backend/

-# 2. 安装 goctl 工具
-go install github.com/zeromicro/go-zero/tools/goctl@latest
-
-# 3. 验证安装
-goctl --version
+# 2. 启动服务
+make run          # 本地开发
+make docker-run   # Docker运行
 ```

-### 项目初始化
-```bash
-# 1. 创建项目目录
-mkdir photography-backend && cd photography-backend
-
-# 2. 初始化 Go 模块
-go mod init photography-backend
-
-# 3. 创建 API 定义文件
-mkdir -p api/desc
-```
-
-### 快速开发流程
-```bash
-# 1. 定义 API 接口 (api/desc/photography.api)
-# 2. 生成 API 服务代码
-goctl api go -api api/desc/photography.api -dir ./
-
-# 3. 定义数据库表结构 (internal/model/sql/*.sql)
-# 4. 生成数据模型代码
-goctl model mysql ddl -src internal/model/sql/user.sql -dir internal/model/
-
-# 5. 启动开发服务器
-go run cmd/api/main.go -f etc/photographyapi-api.yaml
-```
-
-### 多模块扩展
-当项目需要拆分为多个服务时，可以在 cmd 目录下添加不同的服务入口：
-
-```bash
-# API 服务 (HTTP 接口)
-go run cmd/api/main.go -f etc/photographyapi-api.yaml
-
-# RPC 服务 (内部调用)
-go run cmd/rpc/main.go -f etc/photographyrpc.yaml
-
-# 任务服务 (定时任务/队列处理)
-go run cmd/job/main.go -f etc/photographyjob.yaml
-```
-
-### 服务职责划分
- **API 服务**: 对外提供 HTTP 接口，处理用户请求
- **RPC 服务**: 内部服务间通信，提供核心业务逻辑
- **任务服务**: 异步任务处理，如图片处理、邮件发送等
-
-### 开发模式
- **快速开发**: 使用 SQLite 进行本地开发，无需额外数据库
- **生产模式**: 使用 PostgreSQL + Redis，完整的生产环境配置
- **测试模式**: 使用内存数据库，用于单元测试和集成测试
-
-## 🗄️ 数据库迁移系统
-
-### 迁移系统架构
-
-项目采用自定义的数据库迁移系统，提供完整的版本控制和回滚机制：
+## 📁 核心目录

 ```
-pkg/migration/
-├── migration.go      # 迁移管理器核心逻辑
-├── migrations.go     # 所有迁移定义
-└── README.md        # 迁移开发指南
-
-cmd/migrate/
-└── main.go          # 命令行迁移工具
-
-scripts/
-├── production-migrate.sh    # 生产环境迁移脚本
-└── init-production-db.sh   # 生产环境初始化脚本
-
-docs/
-└── DATABASE_MIGRATION.md   # 完整迁移文档
+backend/
+├── cmd/api/main.go        # 服务入口
+├── api/desc/             # API定义文件
+├── internal/             # 业务代码
+│   ├── handler/          # 请求处理器
+│   ├── logic/           # 业务逻辑
+│   ├── model/           # 数据模型
+│   └── middleware/      # 中间件
+├── etc/                 # 配置文件
+├── tests/               # 测试文件
+└── pkg/                 # 公共库
 ```

-### 快速迁移命令
+## ⚙️ 配置文件

-```bash
-# 开发环境
-make migrate-status          # 查看迁移状态
-make migrate-up              # 运行所有迁移
-make migrate-down STEPS=1    # 回滚1步迁移
-make migrate-create NAME=xxx # 创建新迁移
-make db-backup              # 创建备份
-make db-restore BACKUP=file # 恢复备份
-
-# 生产环境
-./scripts/production-migrate.sh status    # 查看状态
-./scripts/production-migrate.sh migrate   # 执行迁移
-./scripts/production-migrate.sh -d migrate # 预览模式
-./scripts/init-production-db.sh           # 全新初始化
+### 本地开发 (`etc/photographyapi-api.yaml`)
+```yaml
+Database:
+  driver: sqlite
+  file_path: ./data/photography.db
 ```

-### 迁移开发流程
+### 生产环境 (`etc/photography-api.yaml`)
+```yaml
+Database:
+  driver: postgres
+  host: postgres_db
+  port: 5432
+  ssl_mode: disable
+```

-1. **创建迁移**: `make migrate-create NAME="add_user_field"`
-2. **编辑迁移**: 在 `pkg/migration/migrations.go` 中添加迁移定义
-3. **测试迁移**: `make migrate-up` 和 `make migrate-down STEPS=1`
-4. **部署生产**: `./scripts/production-migrate.sh migrate`
+## 🛠️ 常用命令

-### 特性
+| 命令 | 用途 |
+|---|---|
+| `make run` | 启动开发服务器 |
+| `make build` | 构建二进制 |
+| `make docker-build` | 构建Docker镜像 |
+| `make migrate-up` | 运行数据库迁移 |
+| `make test` | 运行测试 |

- ✅ **版本控制**: 时间戳版本号，确保迁移顺序
- ✅ **回滚支持**: 每个迁移都支持安全回滚
- ✅ **自动备份**: 生产环境迁移前自动备份
- ✅ **SQLite 优化**: 针对 SQLite 限制的特殊处理
- ✅ **事务安全**: 每个迁移在事务中执行
- ✅ **状态跟踪**: 完整的迁移状态记录
- ✅ **预览模式**: 支持预览迁移而不实际执行
- ✅ **日志记录**: 详细的迁移日志和错误追踪
+## 🔗 API文档
+- 定义文件: `api/desc/` 目录
+- 在线测试: 启动后访问 http://localhost:8080

-详细使用方法请参考: [数据库迁移文档](docs/DATABASE_MIGRATION.md)
+## 🗄️ 数据库
+- **开发**: SQLite (无需安装)
+- **生产**: PostgreSQL
+- **迁移**: 自动迁移系统

-本 CLAUDE.md 文件为后端开发提供了全面的指导，遵循 go-zero 框架的最佳实践。
+## 📋 开发流程
+1. 修改API定义 → `api/desc/`
+2. 生成代码 → `make generate`
+3. 实现逻辑 → `internal/logic/`
+4. 运行测试 → `make test`
--- a/backend/api/desc/CLAUDE.md
+++ b/backend/api/desc/CLAUDE.md
@ -0,0 +1,37 @@
+# API定义模块
+
+## 📋 文件结构
+```
+api/desc/
+├── photography.api      # 主API文件(聚合)
+├── auth.api            # 认证接口
+├── photo.api           # 照片接口
+├── category.api        # 分类接口
+├── user.api            # 用户接口
+└── frontend/           # 前端专用接口
+    ├── auth.api        # 前端认证
+    └── public.api      # 公开接口
+```
+
+## 🚀 开发流程
+1. **新增接口**: 编辑对应.api文件
+2. **生成代码**: `make generate-api`
+3. **实现逻辑**: 在internal/logic/对应目录
+
+## 🎯 文件作用
+| 文件 | 用途 | 对应功能 |
+|---|---|---|
+| `auth.api` | 登录/注册 | JWT认证 |
+| `photo.api` | 照片CRUD | 上传/管理 |
+| `category.api` | 分类管理 | 相册分类 |
+| `frontend/auth.api` | 前端登录 | 用户认证 |
+| `frontend/public.api` | 公开接口 | 无需认证 |
+
+## ⚙️ 生成命令
+```bash
+# 生成所有API代码
+goctl api go -api api/desc/photography.api -dir ./
+
+# 生成单个模块
+goctl api go -api api/desc/photo.api -dir ./internal/handler/photo
+```
--- a/backend/configs/CLAUDE.md
+++ b/backend/configs/CLAUDE.md
@ -0,0 +1,24 @@
+# 配置目录
+
+## 📁 目录结构
+```
+configs/
+├── sql/           # 数据库脚本
+│   ├── init.sql   # 初始化表结构
+│   └── seed.sql   # 测试数据
+└── docker/        # Docker配置
+    ├── Dockerfile
+    └── docker-compose.*.yml
+```
+
+## 🎯 用途说明
+- **sql/**: 数据库初始化相关
+- **docker/**: 容器化配置
+
+## 🚀 快速使用
+```bash
+# 运行SQL脚本
+cd configs/sql
+make init-db    # 初始化数据库
+make seed-data  # 插入测试数据
+```
--- a/backend/configs/sql/CLAUDE.md
+++ b/backend/configs/sql/CLAUDE.md
@ -0,0 +1,18 @@
+# SQL配置目录
+
+## 📋 目录内容
+- `init.sql` - 数据库初始化脚本
+- `seed.sql` - 测试数据插入脚本
+
+## 🚀 使用方法
+```bash
+# 初始化数据库
+psql -U photography -d photography -f init.sql
+
+# 插入测试数据
+psql -U photography -d photography -f seed.sql
+```
+
+## 🎯 文件作用
+- **init.sql**: 创建初始表结构
+- **seed.sql**: 插入默认分类和测试照片数据
--- a/backend/deploy/CLAUDE.md
+++ b/backend/deploy/CLAUDE.md
@ -0,0 +1,32 @@
+# 部署配置目录
+
+## 📁 目录结构
+```
+deploy/
+├── k8s/           # Kubernetes配置
+└── systemd/       # Systemd服务配置
+```
+
+## 🎯 部署方式选择
+| 方式 | 目录 | 适用场景 |
+|---|---|---|
+| **Docker** | 根目录docker-compose.yml | 本地开发/测试 |
+| **K8s** | deploy/k8s/ | 云原生部署 |
+| **Systemd** | deploy/systemd/ | 裸机部署 |
+
+## 🚀 快速部署
+```bash
+# 查看部署文档
+cd docs/deployment/
+cat CLAUDE.md
+
+# 使用Docker部署
+docker-compose up -d
+
+# 使用Systemd部署
+sudo systemctl start photography-api
+```
+
+## ⚙️ 配置文件
+- **k8s/**: Kubernetes YAML文件
+- **systemd/**: 系统服务配置模板
--- a/backend/etc/photography-api.yaml
+++ b/backend/etc/photography-api.yaml
@ -11,7 +11,7 @@ Database:
  Username: photography
  Password: fc34ewdc.d3we-s
  Charset: utf8mb4
-  SSLMode: disable
+  ssl_mode: disable
  MaxOpenConns: 100
  MaxIdleConns: 10

--- a/backend/internal/handler/CLAUDE.md
+++ b/backend/internal/handler/CLAUDE.md
@ -0,0 +1,40 @@
+# Handler层 - 请求处理器
+
+## 📋 目录结构
+```
+internal/handler/
+├── auth/           # 认证处理器
+├── category/       # 分类处理器
+├── photo/         # 照片处理器
+├── user/          # 用户处理器
+├── health/        # 健康检查
+└── routes.go      # 路由注册
+```
+
+## 🎯 处理器职责
+- **接收请求**: HTTP请求入口
+- **参数验证**: 请求参数校验
+- **调用逻辑**: 调用logic层处理
+- **返回响应**: 格式化响应
+
+## 🚀 开发流程
+1. **新增处理器**: 在对应目录创建handler文件
+2. **注册路由**: 在routes.go中添加路由
+3. **绑定逻辑**: 调用对应的logic层方法
+
+## 📊 代码模板
+```go
+// 示例处理器结构
+func (h *CreatePhotoHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+    // 1. 解析请求参数
+    // 2. 调用logic层
+    // 3. 返回响应
+}
+```
+
+## 🔗 对应关系
+| Handler | Logic | Model |
+|---|---|---|
+| `auth/` | `logic/auth/` | `model/user/` |
+| `photo/` | `logic/photo/` | `model/photo/` |
+| `category/` | `logic/category/` | `model/category/` |
--- a/backend/internal/logic/CLAUDE.md
+++ b/backend/internal/logic/CLAUDE.md
@ -0,0 +1,43 @@
+# Logic层 - 业务逻辑
+
+## 📋 目录结构
+```
+internal/logic/
+├── auth/           # 认证逻辑
+├── category/       # 分类业务逻辑
+├── photo/         # 照片业务逻辑
+├── user/          # 用户业务逻辑
+└── health/        # 健康检查逻辑
+```
+
+## 🎯 逻辑层职责
+- **业务处理**: 核心业务逻辑实现
+- **数据验证**: 业务规则验证
+- **事务管理**: 数据库事务控制
+- **错误处理**: 业务异常处理
+
+## 🚀 开发流程
+1. **实现接口**: 根据API定义实现逻辑
+2. **调用模型**: 使用model层操作数据
+3. **处理异常**: 返回标准化错误
+
+## 📊 代码结构
+```go
+// 业务逻辑模板
+func (l *CreatePhotoLogic) CreatePhoto(req types.CreatePhotoRequest) (*types.Photo, error) {
+    // 1. 业务验证
+    // 2. 数据操作
+    // 3. 返回结果
+}
+```
+
+## 🔗 层级关系
+```
+Handler → Logic → Model → Database
+```
+
+## 🎯 最佳实践
+- **单一职责**: 每个logic方法只做一件事
+- **错误处理**: 使用pkg/errorx定义错误
+- **日志记录**: 关键操作添加日志
+- **事务边界**: 复杂操作使用事务
--- a/backend/internal/middleware/CLAUDE.md
+++ b/backend/internal/middleware/CLAUDE.md
@ -0,0 +1,46 @@
+# Middleware层 - 中间件
+
+## 📋 文件结构
+```
+internal/middleware/
+├── auth.go           # JWT认证中间件
+├── cors.go           # 跨域处理中间件
+├── logger.go         # 日志中间件
+├── error.go          # 错误处理中间件
+└── middleware.go     # 中间件管理器
+```
+
+## 🎯 中间件职责
+- **认证授权**: JWT令牌验证
+- **跨域处理**: CORS配置
+- **日志记录**: 请求日志
+- **错误处理**: 统一错误响应
+- **限流熔断**: 请求限流
+
+## 🚀 中间件顺序
+```
+请求 → Logger → CORS → Auth → RateLimit → Handler
+```
+
+## 📊 配置参数
+| 中间件 | 配置项 | 默认值 |
+|---|---|---|
+| **CORS** | 允许域名 | localhost:3000 |
+| **Logger** | 日志级别 | info |
+| **Auth** | 过期时间 | 24小时 |
+
+## 🎯 使用方式
+```go
+// 在路由中使用
+r.Use(middleware.Cors())
+r.Use(middleware.Logger())
+r.Use(middleware.Auth())
+```
+
+## 🔄 扩展中间件
+1. **新增文件**: 创建新的中间件文件
+2. **注册使用**: 在routes.go中添加
+3. **配置参数**: 在配置文件中设置
+
+## ⚙️ 配置位置
+- 配置项: `etc/photography-api.yaml` -> `middleware` 部分
--- a/backend/internal/model/CLAUDE.md
+++ b/backend/internal/model/CLAUDE.md
@ -0,0 +1,49 @@
+# Model层 - 数据模型
+
+## 📋 目录结构
+```
+internal/model/
+├── user.go           # 用户模型
+├── photo.go          # 照片模型
+├── category.go       # 分类模型
+├── vars.go           # 模型变量
+├── sql/              # SQL定义文件
+│   ├── user.sql      # 用户表结构
+│   ├── photo.sql     # 照片表结构
+│   └── category.sql  # 分类表结构
+└── *_gen.go          # 自动生成代码
+```
+
+## 🎯 模型职责
+- **数据定义**: 数据库表结构
+- **CRUD操作**: 基础数据操作
+- **关联关系**: 表间关系定义
+- **验证规则**: 数据验证
+
+## 🚀 开发流程
+1. **定义SQL**: 在sql/目录创建表结构
+2. **生成模型**: `make generate-model`
+3. **扩展方法**: 在对应模型文件添加自定义方法
+
+## 📊 表结构关系
+```
+User 1:N Photo (用户拥有多张照片)
+Category 1:N Photo (分类包含多张照片)
+```
+
+## 🎯 文件说明
+| 文件 | 用途 | 修改频率 |
+|---|---|---|
+| `user.sql` | 用户表定义 | 低 |
+| `photo.sql` | 照片表定义 | 中 |
+| `category.sql` | 分类表定义 | 低 |
+| `*_gen.go` | 自动生成代码 | 不修改 |
+
+## 🔄 生成命令
+```bash
+# 生成所有模型
+make generate-model
+
+# 生成单个模型
+goctl model mysql ddl -src sql/user.sql -dir ./internal/model/
+```
--- a/backend/internal/svc/CLAUDE.md
+++ b/backend/internal/svc/CLAUDE.md
@ -0,0 +1,39 @@
+# Service Context - 服务上下文
+
+## 📁 文件结构
+```
+internal/svc/
+└── servicecontext.go    # 服务上下文定义
+```
+
+## 🎯 核心职责
+- **服务初始化**: 集中管理所有服务依赖
+- **依赖注入**: 为handler提供所需组件
+- **生命周期**: 管理服务生命周期
+
+## 🔧 组件管理
+```go
+type ServiceContext struct {
+    Config        config.Config     // 配置
+    DB            *gorm.DB         // 数据库连接
+    UserModel     model.UserModel   // 用户模型
+    PhotoModel    model.PhotoModel  // 照片模型
+    CategoryModel model.CategoryModel // 分类模型
+    Middleware    *middleware.MiddlewareManager // 中间件管理
+}
+```
+
+## 🚀 初始化流程
+```
+启动服务 → 加载配置 → 初始化数据库 → 创建模型 → 注册中间件 → 启动HTTP服务
+```
+
+## 📋 扩展方式
+1. **新增模型**: 在ServiceContext中添加新字段
+2. **初始化**: 在NewServiceContext中初始化
+3. **使用**: 在handler中通过svc访问
+
+## 🎯 设计模式
+- **单例模式**: 整个服务生命周期只创建一次
+- **依赖注入**: 通过构造函数传递依赖
+- **门面模式**: 为上层提供统一的访问接口
--- a/backend/pkg/CLAUDE.md
+++ b/backend/pkg/CLAUDE.md
@ -0,0 +1,34 @@
+# 公共库目录
+
+## 📦 包结构
+```
+pkg/
+├── constants/    # 全局常量
+├── errorx/       # 错误处理
+├── response/     # 响应格式
+└── utils/        # 工具集合
+    ├── jwt/      # JWT工具
+    ├── hash/     # 哈希工具
+    ├── file/     # 文件处理
+    └── database/ # 数据库工具
+```
+
+## 🎯 设计原则
+- **可复用**: 项目间共享的通用功能
+- **无依赖**: 不依赖内部业务代码
+- **易测试**: 独立可测试的单元
+
+## 🚀 快速使用
+```go
+// 使用错误处理
+import "photography-backend/pkg/errorx"
+err := errorx.New(errorx.CodeInvalidArgument)
+
+// 使用JWT工具
+import "photography-backend/pkg/utils/jwt"
+token, err := jwt.GenerateToken(userID)
+
+// 使用响应格式
+import "photography-backend/pkg/response"
+response.Success(c, data)
+```
--- a/backend/scripts/CLAUDE.md
+++ b/backend/scripts/CLAUDE.md
@ -0,0 +1,34 @@
+# 脚本目录
+
+## 🛠️ 脚本列表
+```
+scripts/
+├── init-production-db.sh    # 生产数据库初始化
+├── production-db-setup.sh   # 数据库配置
+├── production-migrate.sh    # 生产环境迁移
+└── test-migration.sh        # 测试迁移
+```
+
+## 🎯 脚本用途
+| 脚本 | 用途 |
+|---|---|
+| `init-production-db.sh` | 首次部署数据库 |
+| `production-migrate.sh` | 执行数据库迁移 |
+| `test-migration.sh` | 本地测试迁移 |
+
+## 🚀 使用方式
+```bash
+# 生产环境初始化
+./scripts/init-production-db.sh
+
+# 执行迁移
+./scripts/production-migrate.sh up
+
+# 测试迁移
+./scripts/test-migration.sh
+```
+
+## ⚠️ 注意事项
+- 生产脚本需要数据库连接权限
+- 迁移前建议备份数据
+- 本地测试使用SQLite