# Documentation Module - CLAUDE.md

本文件为 Claude Code 在文档模块中工作时提供指导。

## 🎯 模块概览

文档模块负责维护项目的技术文档、API 文档和架构设计文档，确保项目的可理解性和可维护性。

### 主要职责
- 📚 API 接口文档
- 🏗️ 架构设计文档
- 🚀 部署运维文档
- 📖 开发者指南
- 📋 变更日志

## 📁 模块结构

```
docs/
├── CLAUDE.md                    # 📋 当前文件 - API 文档和接口设计指导
├── api/                         # 📚 API 接口文档
│   ├── openapi.yaml            # OpenAPI 3.0 规范
│   ├── swagger.json            # Swagger JSON 格式
│   ├── postman/                # Postman 集合
│   │   ├── photography.json    # API 测试集合
│   │   └── environment.json    # 环境变量
│   └── examples/               # 请求响应示例
│       ├── user_examples.md    # 用户接口示例
│       ├── photo_examples.md   # 照片接口示例
│       └── auth_examples.md    # 认证接口示例
├── architecture/               # 🏗️ 架构设计文档
│   ├── overview.md             # 系统架构概览
│   ├── database_design.md      # 数据库设计
│   ├── api_design.md          # API 设计原则
│   ├── security.md            # 安全架构
│   └── performance.md         # 性能优化
├── development/                # 👨‍💻 开发文档
│   ├── getting_started.md      # 快速开始
│   ├── coding_standards.md     # 编码规范
│   ├── testing_guide.md        # 测试指南
│   ├── debugging.md           # 调试指南
│   └── contribution.md        # 贡献指南
├── deployment/                 # 🚀 部署文档
│   ├── local_deployment.md     # 本地部署
│   ├── docker_deployment.md    # Docker 部署
│   ├── production_deployment.md # 生产环境部署
│   ├── monitoring.md          # 监控配置
│   └── troubleshooting.md     # 故障排查
├── guides/                     # 📖 使用指南
│   ├── user_management.md      # 用户管理
│   ├── photo_management.md     # 照片管理
│   ├── authentication.md      # 认证授权
│   └── file_upload.md         # 文件上传
├── changelog/                  # 📋 变更日志
│   ├── CHANGELOG.md           # 版本变更记录
│   └── migration_guides/      # 迁移指南
│       ├── v1_to_v2.md        # 版本迁移
│       └── breaking_changes.md # 破坏性变更
└── templates/                  # 📄 文档模板
    ├── api_template.md         # API 文档模板
    ├── guide_template.md       # 指南模板
    └── adr_template.md         # 架构决策记录模板
```

## 📚 API 文档

### OpenAPI 3.0 规范
```yaml
# api/openapi.yaml - OpenAPI 3.0 规范
openapi: 3.0.3
info:
  title: Photography Portfolio API
  description: 摄影作品集 REST API
  version: 1.0.0
  contact:
    name: API Support
    email: support@photography.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.photography.com/v1
    description: 生产环境
  - url: https://staging-api.photography.com/v1
    description: 测试环境
  - url: http://localhost:8080/api/v1
    description: 开发环境

paths:
  /users:
    get:
      summary: 获取用户列表
      description: 获取系统中的用户列表，支持分页和过滤
      operationId: listUsers
      tags:
        - Users
      parameters:
        - name: page
          in: query
          description: 页码
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          description: 每页数量
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: sort
          in: query
          description: 排序字段
          required: false
          schema:
            type: string
            enum: [id, username, email, created_at]
            default: created_at
        - name: order
          in: query
          description: 排序方向
          required: false
          schema:
            type: string
            enum: [asc, desc]
            default: desc
      responses:
        '200':
          description: 成功获取用户列表
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
        
    post:
      summary: 创建用户
      description: 创建新用户账户
      operationId: createUser
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: 用户创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '409':
          description: 用户已存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /users/{id}:
    get:
      summary: 获取用户详情
      description: 根据用户ID获取用户详细信息
      operationId: getUserById
      tags:
        - Users
      parameters:
        - name: id
          in: path
          description: 用户ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: 成功获取用户信息
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '404':
          description: 用户不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: 用户ID
          example: 1
        username:
          type: string
          description: 用户名
          example: "john_doe"
        email:
          type: string
          format: email
          description: 邮箱地址
          example: "john@example.com"
        first_name:
          type: string
          description: 名字
          example: "John"
        last_name:
          type: string
          description: 姓氏
          example: "Doe"
        avatar:
          type: string
          format: uri
          description: 头像URL
          example: "https://example.com/avatars/john.jpg"
        role:
          type: string
          enum: [admin, editor, user]
          description: 用户角色
          example: "user"
        status:
          type: string
          enum: [active, inactive, banned]
          description: 用户状态
          example: "active"
        created_at:
          type: string
          format: date-time
          description: 创建时间
          example: "2024-01-01T00:00:00Z"
        updated_at:
          type: string
          format: date-time
          description: 更新时间
          example: "2024-01-01T00:00:00Z"
      required:
        - id
        - username
        - email
        - role
        - status
        - created_at
        - updated_at

    CreateUserRequest:
      type: object
      properties:
        username:
          type: string
          minLength: 3
          maxLength: 50
          pattern: '^[a-zA-Z0-9_-]+$'
          description: 用户名
          example: "john_doe"
        email:
          type: string
          format: email
          description: 邮箱地址
          example: "john@example.com"
        password:
          type: string
          minLength: 8
          description: 密码
          example: "SecurePassword123!"
        first_name:
          type: string
          maxLength: 50
          description: 名字
          example: "John"
        last_name:
          type: string
          maxLength: 50
          description: 姓氏
          example: "Doe"
      required:
        - username
        - email
        - password

    UserResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/User'
        message:
          type: string
          example: "User retrieved successfully"
        timestamp:
          type: integer
          format: int64
          example: 1704067200
        request_id:
          type: string
          example: "req_123456789"

    UserListResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
        pagination:
          $ref: '#/components/schemas/Pagination'
        message:
          type: string
          example: "Users retrieved successfully"
        timestamp:
          type: integer
          format: int64
          example: 1704067200
        request_id:
          type: string
          example: "req_123456789"

    Pagination:
      type: object
      properties:
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 20
        total:
          type: integer
          format: int64
          example: 100
        total_pages:
          type: integer
          example: 5
        has_next:
          type: boolean
          example: true
        has_prev:
          type: boolean
          example: false

    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          $ref: '#/components/schemas/Error'
        timestamp:
          type: integer
          format: int64
          example: 1704067200
        request_id:
          type: string
          example: "req_123456789"

    Error:
      type: object
      properties:
        code:
          type: string
          example: "USER_NOT_FOUND"
        message:
          type: string
          example: "User not found"
        details:
          type: string
          example: "User with ID 123 does not exist"

    ValidationErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: "VALIDATION_ERROR"
            message:
              type: string
              example: "Validation failed"
            details:
              type: array
              items:
                $ref: '#/components/schemas/ValidationError'
        timestamp:
          type: integer
          format: int64
          example: 1704067200
        request_id:
          type: string
          example: "req_123456789"

    ValidationError:
      type: object
      properties:
        field:
          type: string
          example: "email"
        value:
          type: string
          example: "invalid-email"
        tag:
          type: string
          example: "email"
        message:
          type: string
          example: "email must be a valid email address"

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT Bearer token

  parameters:
    PageParam:
      name: page
      in: query
      description: 页码
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1

    LimitParam:
      name: limit
      in: query
      description: 每页数量
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20

    SortParam:
      name: sort
      in: query
      description: 排序字段
      required: false
      schema:
        type: string
        default: "created_at"

    OrderParam:
      name: order
      in: query
      description: 排序方向
      required: false
      schema:
        type: string
        enum: [asc, desc]
        default: "desc"

tags:
  - name: Users
    description: 用户管理接口
  - name: Photos
    description: 照片管理接口
  - name: Authentication
    description: 认证授权接口
  - name: Categories
    description: 分类管理接口
  - name: Tags
    description: 标签管理接口
```

## 🏗️ 架构设计

### 系统架构概览
```markdown
# architecture/overview.md - 系统架构概览

## 整体架构

Photography Portfolio 采用现代化的微服务架构，基于 Go 语言开发，使用 Clean Architecture 设计模式。

### 架构层次

```
┌─────────────────────────────────────────────────────────────┐
│                    Frontend Layer                           │
│  Next.js + React + TypeScript + Tailwind CSS              │
└─────────────────────────────────────────────────────────────┘
                              │
                              │ HTTP/HTTPS
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     API Gateway                            │
│               Caddy + Load Balancer                        │
└─────────────────────────────────────────────────────────────┘
                              │
                              │ HTTP
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   Backend Services                         │
│                                                             │
│  ┌─────────────────┐ ┌─────────────────┐ ┌───────────────┐ │
│  │   User Service  │ │  Photo Service  │ │  Auth Service │ │
│  │   (Go + Gin)    │ │   (Go + Gin)    │ │  (Go + Gin)   │ │
│  └─────────────────┘ └─────────────────┘ └───────────────┘ │
│                                                             │
└─────────────────────────────────────────────────────────────┘
                              │
                              │ SQL/NoSQL
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   Data Layer                               │
│                                                             │
│  ┌─────────────────┐ ┌─────────────────┐ ┌───────────────┐ │
│  │   PostgreSQL    │ │      Redis      │ │  File Storage │ │
│  │   (主数据库)     │ │     (缓存)       │ │  (S3/Local)   │ │
│  └─────────────────┘ └─────────────────┘ └───────────────┘ │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### 核心设计原则

1. **单一职责原则**: 每个服务只负责一个业务领域
2. **依赖倒置原则**: 高层模块不依赖低层模块，都依赖抽象
3. **接口隔离原则**: 使用接口定义契约，便于测试和替换
4. **开闭原则**: 对扩展开放，对修改封闭
5. **最小知识原则**: 模块间耦合度最小化

### 技术栈选择

#### 后端技术栈
- **语言**: Go 1.23+ (性能优异，并发支持)
- **框架**: Gin (轻量级，高性能 HTTP 框架)
- **数据库**: PostgreSQL (关系型数据，事务支持)
- **缓存**: Redis (高性能内存缓存)
- **ORM**: GORM (功能丰富，性能优良)
- **认证**: JWT (无状态，扩展性好)
- **日志**: Uber Zap (结构化，高性能)
- **配置**: Viper (灵活的配置管理)

#### 部署技术栈
- **容器化**: Docker + Docker Compose
- **Web 服务器**: Caddy (自动 HTTPS，配置简单)
- **CI/CD**: Gitea Actions (自动化部署)
- **监控**: Prometheus + Grafana (可观测性)

### 数据流向

1. **请求流程**:
   Frontend → API Gateway → Backend Service → Repository → Database

2. **响应流程**:
   Database → Repository → Service → Handler → API Gateway → Frontend

3. **认证流程**:
   Client → Auth Service → JWT Token → Protected Resources

4. **文件上传流程**:
   Client → Upload Handler → Storage Service → File System/S3
```

### 数据库设计
```markdown
# architecture/database_design.md - 数据库设计

## 数据库选择

### PostgreSQL (主数据库)
- **优势**: ACID 事务支持，丰富的数据类型，成熟的生态
- **用途**: 用户数据、照片元数据、分类标签等结构化数据
- **版本**: PostgreSQL 14+

### Redis (缓存数据库)
- **优势**: 高性能内存存储，丰富的数据结构
- **用途**: 会话缓存、频繁查询数据缓存、限流计数器
- **版本**: Redis 6+

## 表结构设计

### 用户表 (users)
```sql
CREATE TABLE users (
    id BIGSERIAL PRIMARY KEY,
    username VARCHAR(50) UNIQUE NOT NULL,
    email VARCHAR(100) UNIQUE NOT NULL,
    password VARCHAR(255) NOT NULL,
    first_name VARCHAR(50),
    last_name VARCHAR(50),
    avatar VARCHAR(255),
    bio TEXT,
    role VARCHAR(20) DEFAULT 'user',
    status VARCHAR(20) DEFAULT 'active',
    last_login_at TIMESTAMP,
    email_verified_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    deleted_at TIMESTAMP
);

-- 索引
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_username ON users(username);
CREATE INDEX idx_users_status ON users(status);
CREATE INDEX idx_users_created_at ON users(created_at);
```

### 照片表 (photos)
```sql
CREATE TABLE photos (
    id BIGSERIAL PRIMARY KEY,
    user_id BIGINT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    title VARCHAR(255) NOT NULL,
    description TEXT,
    filename VARCHAR(255) NOT NULL,
    file_path VARCHAR(500) NOT NULL,
    file_size BIGINT NOT NULL,
    mime_type VARCHAR(100) NOT NULL,
    width INTEGER DEFAULT 0,
    height INTEGER DEFAULT 0,
    exif_data TEXT,
    taken_at TIMESTAMP,
    location VARCHAR(255),
    camera VARCHAR(100),
    lens VARCHAR(100),
    status VARCHAR(20) DEFAULT 'active',
    view_count INTEGER DEFAULT 0,
    download_count INTEGER DEFAULT 0,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    deleted_at TIMESTAMP
);

-- 索引
CREATE INDEX idx_photos_user_id ON photos(user_id);
CREATE INDEX idx_photos_status ON photos(status);
CREATE INDEX idx_photos_created_at ON photos(created_at);
CREATE INDEX idx_photos_taken_at ON photos(taken_at);
```

## 关系设计

### 实体关系图
```
Users ||--o{ Photos : owns
Photos }o--o{ Categories : categorized_by
Photos }o--o{ Tags : tagged_with
Users ||--o{ Albums : creates
Albums }o--o{ Photos : contains
```

### 外键约束
- 所有外键使用 CASCADE 删除策略
- 确保数据一致性和完整性
- 使用索引优化查询性能

## 查询优化

### 索引策略
1. **主键索引**: 自动创建
2. **外键索引**: 手动创建，优化关联查询
3. **查询索引**: 根据常用查询条件创建
4. **复合索引**: 针对多字段查询优化

### 查询优化技巧
1. **避免 N+1 查询**: 使用预加载
2. **分页查询**: 使用 LIMIT 和 OFFSET
3. **条件筛选**: 在数据库层面过滤数据
4. **结果缓存**: 缓存频繁查询的结果
```

## 📖 开发指南

### 快速开始
```markdown
# development/getting_started.md - 快速开始

## 环境要求

### 必需软件
- Go 1.23+
- PostgreSQL 14+
- Redis 6+
- Docker & Docker Compose
- Git

### 推荐工具
- GoLand 或 VS Code
- Postman 或 Insomnia
- DBeaver (数据库管理)
- Redis Desktop Manager

## 本地开发环境设置

### 1. 克隆项目
```bash
git clone <repository-url>
cd photography-backend
```

### 2. 安装依赖
```bash
go mod download
```

### 3. 配置环境
```bash
# 复制配置文件
cp configs/config.dev.yaml.example configs/config.dev.yaml

# 修改数据库配置
vim configs/config.dev.yaml
```

### 4. 启动服务
```bash
# 开发模式 (SQLite)
make dev

# 完整模式 (PostgreSQL + Redis)
make dev-full

# Mock 模式 (无数据库)
make dev-simple
```

### 5. 验证安装
```bash
# 检查服务状态
curl http://localhost:8080/health

# 预期响应
{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00Z",
  "version": "1.0.0"
}
```

## 开发流程

### 1. 功能开发
1. 创建功能分支: `git checkout -b feature/new-feature`
2. 编写代码和测试
3. 运行测试: `make test`
4. 代码检查: `make lint`
5. 提交代码: `git commit -m "feat: add new feature"`

### 2. 测试验证
```bash
# 运行单元测试
make test-unit

# 运行集成测试
make test-integration

# 运行所有测试
make test

# 查看测试覆盖率
make test-coverage
```

### 3. 提交代码
```bash
# 格式化代码
make fmt

# 代码检查
make lint

# 构建项目
make build

# 提交到远程
git push origin feature/new-feature
```
```

## 📋 变更日志

### 版本管理
```markdown
# changelog/CHANGELOG.md - 版本变更记录

# 变更日志

本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/) 规范。

## [未发布]

### 新增
- 新功能开发中...

### 修改
- 改进功能...

### 修复
- 修复问题...

### 删除
- 移除废弃功能...

## [1.2.0] - 2024-01-15

### 新增
- 添加照片批量上传功能
- 支持照片 EXIF 信息提取
- 新增照片搜索 API
- 添加用户头像上传功能
- 支持照片分类管理
- 新增 API 限流中间件

### 修改
- 优化照片列表查询性能
- 改进错误处理机制
- 更新 API 响应格式
- 优化数据库查询索引
- 改进日志记录格式

### 修复
- 修复文件上传大小限制问题
- 解决并发操作的数据竞争问题
- 修复 JWT Token 过期处理
- 解决照片删除时的缓存清理问题
- 修复分页查询的边界条件

### 安全
- 加强文件上传安全验证
- 改进密码强度要求
- 添加请求频率限制
- 优化 SQL 注入防护

## [1.1.0] - 2024-01-01

### 新增
- 用户注册和登录功能
- JWT 认证机制
- 用户权限管理
- 照片上传和管理
- RESTful API 接口
- 数据库迁移系统

### 修改
- 重构代码架构
- 优化性能表现
- 改进错误处理

## [1.0.0] - 2023-12-01

### 新增
- 项目初始版本
- 基础框架搭建
- 核心功能实现
```

## 🛠️ 文档维护

### 文档编写规范
1. **Markdown 格式**: 使用标准 Markdown 语法
2. **结构清晰**: 合理使用标题层级
3. **代码示例**: 提供完整可运行的示例
4. **版本同步**: 文档与代码版本保持同步
5. **定期更新**: 定期检查和更新文档内容

### 文档生成工具
```bash
# 生成 API 文档
make docs-api

# 生成 Swagger UI
make docs-swagger

# 生成完整文档站点
make docs-build

# 启动文档服务器
make docs-serve
```

### 文档发布流程
1. **编写文档**: 按照模板编写文档
2. **本地预览**: 使用工具预览效果
3. **代码审查**: 提交 PR 进行审查
4. **自动部署**: 合并后自动发布到文档站点

## 💡 最佳实践

### API 文档编写
1. **完整性**: 包含所有接口的详细说明
2. **示例丰富**: 提供请求和响应示例
3. **错误说明**: 详细说明各种错误情况
4. **版本控制**: 明确 API 版本兼容性
5. **交互式**: 支持在线测试功能

### 架构文档维护
1. **及时更新**: 架构变更后立即更新文档
2. **图文并茂**: 使用图表说明复杂概念
3. **决策记录**: 记录重要的架构决策过程
4. **影响分析**: 说明变更对系统的影响
5. **迁移指南**: 提供版本迁移的详细步骤

### 开发文档规范
1. **步骤详细**: 提供详细的操作步骤
2. **环境说明**: 明确开发环境要求
3. **故障排查**: 包含常见问题的解决方案
4. **最佳实践**: 分享开发经验和技巧
5. **持续改进**: 根据反馈不断完善文档

本模块确保项目文档的完整性和准确性，为开发者和用户提供清晰的指导。