photography/backend/docs/API_DOCUMENTATION.md

# Photography Portfolio API Documentation

## 📋 API 概览

Photography Portfolio API 是一个基于 go-zero 框架的 RESTful API 服务，提供完整的摄影作品集管理功能。

### 基本信息

- **API 版本**: v1.0.0
- **基础URL**: `https://api.photography.iriver.top/api/v1`
- **开发环境**: `http://localhost:8080/api/v1`
- **认证方式**: JWT Bearer Token
- **数据格式**: JSON
- **字符编码**: UTF-8

### 响应格式

所有 API 响应都遵循统一的格式：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    // 实际数据
  }
}
```

### 状态码

| HTTP状态码 | 业务码 | 说明 |
|-----------|-------|------|
| 200 | 200 | 请求成功 |
| 400 | 400 | 请求参数错误 |
| 401 | 401 | 未授权 |
| 403 | 403 | 权限不足 |
| 404 | 404 | 资源不存在 |
| 500 | 500 | 服务器内部错误 |

### 错误响应

```json
{
  "code": 400,
  "message": "参数验证失败",
  "data": null
}
```

## 🔐 认证接口

### 用户注册

**接口地址**: `POST /auth/register`

**请求参数**:
```json
{
  "username": "string",    // 用户名，3-20个字符
  "email": "string",       // 邮箱地址
  "password": "string"     // 密码，6-20个字符
}
```

**响应示例**:
```json
{
  "code": 200,
  "message": "注册成功",
  "data": {
    "user": {
      "id": 1,
      "username": "johndoe",
      "email": "john@example.com",
      "avatar": "",
      "status": 1,
      "created_at": "2024-01-10T10:30:00Z"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

**cURL 示例**:
```bash
curl -X POST "http://localhost:8080/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "johndoe",
    "email": "john@example.com",
    "password": "password123"
  }'
```

### 用户登录

**接口地址**: `POST /auth/login`

**请求参数**:
```json
{
  "username": "string",    // 用户名或邮箱
  "password": "string"     // 密码
}
```

**响应示例**:
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "user": {
      "id": 1,
      "username": "johndoe",
      "email": "john@example.com",
      "avatar": "/uploads/avatars/1.jpg",
      "status": 1
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_at": "2024-01-11T10:30:00Z"
  }
}
```

**cURL 示例**:
```bash
curl -X POST "http://localhost:8080/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "johndoe",
    "password": "password123"
  }'
```

## 👥 用户管理接口

### 获取用户列表

**接口地址**: `GET /users`

**请求头**: `Authorization: Bearer <token>`

**查询参数**:
- `page`: 页码，默认 1
- `limit`: 每页数量，默认 10，最大 100
- `status`: 用户状态，可选值 0(禁用) 1(正常)
- `keyword`: 搜索关键词

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "users": [
      {
        "id": 1,
        "username": "johndoe",
        "email": "john@example.com",
        "avatar": "/uploads/avatars/1.jpg",
        "status": 1,
        "created_at": "2024-01-10T10:30:00Z",
        "updated_at": "2024-01-10T10:30:00Z"
      }
    ],
    "total": 50,
    "page": 1,
    "limit": 10,
    "pages": 5
  }
}
```

**cURL 示例**:
```bash
curl -X GET "http://localhost:8080/api/v1/users?page=1&limit=10" \
  -H "Authorization: Bearer <your-token>"
```

### 获取用户详情

**接口地址**: `GET /users/{id}`

**请求头**: `Authorization: Bearer <token>`

**路径参数**:
- `id`: 用户ID

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "username": "johndoe",
    "email": "john@example.com",
    "avatar": "/uploads/avatars/1.jpg",
    "status": 1,
    "created_at": "2024-01-10T10:30:00Z",
    "updated_at": "2024-01-10T10:30:00Z"
  }
}
```

### 创建用户

**接口地址**: `POST /users`

**请求头**: `Authorization: Bearer <token>`

**请求参数**:
```json
{
  "username": "string",    // 用户名，必填
  "email": "string",       // 邮箱，必填
  "password": "string",    // 密码，必填
  "avatar": "string",      // 头像URL，可选
  "status": 1              // 状态，可选，默认1
}
```

### 更新用户

**接口地址**: `PUT /users/{id}`

**请求头**: `Authorization: Bearer <token>`

**请求参数**:
```json
{
  "username": "string",    // 用户名，可选
  "email": "string",       // 邮箱，可选
  "avatar": "string",      // 头像URL，可选
  "status": 1              // 状态，可选
}
```

### 删除用户

**接口地址**: `DELETE /users/{id}`

**请求头**: `Authorization: Bearer <token>`

**响应示例**:
```json
{
  "code": 200,
  "message": "用户删除成功",
  "data": null
}
```

### 上传用户头像

**接口地址**: `POST /users/{id}/avatar`

**请求头**: `Authorization: Bearer <token>`

**请求格式**: `multipart/form-data`

**表单字段**:
- `file`: 图片文件（必填）

**响应示例**:
```json
{
  "code": 200,
  "message": "头像上传成功",
  "data": {
    "avatar_url": "/uploads/avatars/1_1704875400.jpg"
  }
}
```

**cURL 示例**:
```bash
curl -X POST "http://localhost:8080/api/v1/users/1/avatar" \
  -H "Authorization: Bearer <your-token>" \
  -F "file=@avatar.jpg"
```

## 📸 照片管理接口

### 获取照片列表

**接口地址**: `GET /photos`

**查询参数**:
- `page`: 页码，默认 1
- `limit`: 每页数量，默认 10
- `category_id`: 分类ID
- `user_id`: 用户ID
- `status`: 照片状态
- `keyword`: 搜索关键词
- `sort`: 排序方式，可选值：`created_at_desc`、`created_at_asc`、`title_asc`、`title_desc`

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "photos": [
      {
        "id": 1,
        "title": "美丽的日落",
        "description": "在海边拍摄的日落景色",
        "file_path": "/uploads/photos/sunset.jpg",
        "thumbnail_path": "/uploads/photos/thumbs/sunset_thumb.jpg",
        "file_size": 2048576,
        "mime_type": "image/jpeg",
        "width": 1920,
        "height": 1080,
        "category_id": 1,
        "category_name": "风景",
        "user_id": 1,
        "username": "johndoe",
        "status": 1,
        "view_count": 150,
        "like_count": 25,
        "created_at": "2024-01-10T10:30:00Z",
        "updated_at": "2024-01-10T10:30:00Z"
      }
    ],
    "total": 100,
    "page": 1,
    "limit": 10,
    "pages": 10
  }
}
```

### 获取照片详情

**接口地址**: `GET /photos/{id}`

**路径参数**:
- `id`: 照片ID

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "title": "美丽的日落",
    "description": "在海边拍摄的日落景色",
    "file_path": "/uploads/photos/sunset.jpg",
    "thumbnail_path": "/uploads/photos/thumbs/sunset_thumb.jpg",
    "file_size": 2048576,
    "mime_type": "image/jpeg",
    "width": 1920,
    "height": 1080,
    "category": {
      "id": 1,
      "name": "风景",
      "description": "自然风光和城市景观"
    },
    "user": {
      "id": 1,
      "username": "johndoe",
      "avatar": "/uploads/avatars/1.jpg"
    },
    "tags": [
      {
        "id": 1,
        "name": "精选",
        "color": "#ff4444"
      }
    ],
    "status": 1,
    "view_count": 150,
    "like_count": 25,
    "created_at": "2024-01-10T10:30:00Z",
    "updated_at": "2024-01-10T10:30:00Z"
  }
}
```

### 上传照片

**接口地址**: `POST /photos`

**请求头**: `Authorization: Bearer <token>`

**请求格式**: `multipart/form-data`

**表单字段**:
- `file`: 图片文件（必填）
- `title`: 照片标题（必填）
- `description`: 照片描述（可选）
- `category_id`: 分类ID（可选）
- `tags`: 标签ID列表，逗号分隔（可选）

**响应示例**:
```json
{
  "code": 200,
  "message": "照片上传成功",
  "data": {
    "id": 1,
    "title": "美丽的日落",
    "description": "在海边拍摄的日落景色",
    "file_path": "/uploads/photos/sunset_1704875400.jpg",
    "thumbnail_path": "/uploads/photos/thumbs/sunset_1704875400_thumb.jpg",
    "file_size": 2048576,
    "mime_type": "image/jpeg",
    "width": 1920,
    "height": 1080,
    "category_id": 1,
    "user_id": 1,
    "status": 1,
    "created_at": "2024-01-10T10:30:00Z"
  }
}
```

**cURL 示例**:
```bash
curl -X POST "http://localhost:8080/api/v1/photos" \
  -H "Authorization: Bearer <your-token>" \
  -F "file=@sunset.jpg" \
  -F "title=美丽的日落" \
  -F "description=在海边拍摄的日落景色" \
  -F "category_id=1"
```

### 更新照片

**接口地址**: `PUT /photos/{id}`

**请求头**: `Authorization: Bearer <token>`

**请求参数**:
```json
{
  "title": "string",        // 照片标题，可选
  "description": "string",  // 照片描述，可选
  "category_id": 1,         // 分类ID，可选
  "status": 1               // 状态，可选
}
```

### 删除照片

**接口地址**: `DELETE /photos/{id}`

**请求头**: `Authorization: Bearer <token>`

**响应示例**:
```json
{
  "code": 200,
  "message": "照片删除成功",
  "data": null
}
```

## 📂 分类管理接口

### 获取分类列表

**接口地址**: `GET /categories`

**查询参数**:
- `parent_id`: 父分类ID，获取子分类
- `is_active`: 是否激活，可选值 0、1
- `with_count`: 是否包含照片数量统计，默认 false

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "name": "风景",
      "description": "自然风光和城市景观",
      "parent_id": null,
      "sort_order": 1,
      "is_active": 1,
      "photo_count": 25,
      "children": [
        {
          "id": 2,
          "name": "海景",
          "description": "海洋和海滩景色",
          "parent_id": 1,
          "sort_order": 1,
          "is_active": 1,
          "photo_count": 10
        }
      ],
      "created_at": "2024-01-10T10:30:00Z",
      "updated_at": "2024-01-10T10:30:00Z"
    }
  ]
}
```

### 获取分类详情

**接口地址**: `GET /categories/{id}`

**路径参数**:
- `id`: 分类ID

### 创建分类

**接口地址**: `POST /categories`

**请求头**: `Authorization: Bearer <token>`

**请求参数**:
```json
{
  "name": "string",         // 分类名称，必填
  "description": "string",  // 分类描述，可选
  "parent_id": 1,           // 父分类ID，可选
  "sort_order": 1,          // 排序序号，可选
  "is_active": 1            // 是否激活，可选
}
```

### 更新分类

**接口地址**: `PUT /categories/{id}`

**请求头**: `Authorization: Bearer <token>`

**请求参数**:
```json
{
  "name": "string",         // 分类名称，可选
  "description": "string",  // 分类描述，可选
  "parent_id": 1,           // 父分类ID，可选
  "sort_order": 1,          // 排序序号，可选
  "is_active": 1            // 是否激活，可选
}
```

### 删除分类

**接口地址**: `DELETE /categories/{id}`

**请求头**: `Authorization: Bearer <token>`

**响应示例**:
```json
{
  "code": 200,
  "message": "分类删除成功",
  "data": null
}
```

## 🏷️ 标签管理接口

### 获取标签列表

**接口地址**: `GET /tags`

**查询参数**:
- `is_active`: 是否激活
- `keyword`: 搜索关键词

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "name": "精选",
      "color": "#ff4444",
      "description": "精选优质作品",
      "is_active": 1,
      "photo_count": 15,
      "created_at": "2024-01-10T10:30:00Z",
      "updated_at": "2024-01-10T10:30:00Z"
    }
  ]
}
```

### 创建标签

**接口地址**: `POST /tags`

**请求头**: `Authorization: Bearer <token>`

**请求参数**:
```json
{
  "name": "string",         // 标签名称，必填
  "color": "#ff4444",       // 标签颜色，可选
  "description": "string",  // 标签描述，可选
  "is_active": 1            // 是否激活，可选
}
```

## 🏥 健康检查接口

### 健康检查

**接口地址**: `GET /health`

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "status": "ok",
    "timestamp": "2024-01-10T10:30:00Z",
    "version": "v1.0.0",
    "uptime": "2h30m15s",
    "database": "connected",
    "redis": "connected"
  }
}
```

## 📊 统计接口

### 获取仪表盘统计

**接口地址**: `GET /dashboard/stats`

**请求头**: `Authorization: Bearer <token>`

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "users": {
      "total": 150,
      "active": 142,
      "new_today": 5
    },
    "photos": {
      "total": 2500,
      "published": 2350,
      "new_today": 25,
      "total_views": 150000,
      "total_likes": 8500
    },
    "categories": {
      "total": 12,
      "active": 10
    },
    "tags": {
      "total": 25,
      "active": 22
    },
    "storage": {
      "used": "15.5GB",
      "total": "100GB",
      "usage_percent": 15.5
    }
  }
}
```

## 🔧 文件服务接口

### 静态文件访问

**接口地址**: `GET /uploads/{path}`

**路径参数**:
- `path`: 文件相对路径

**示例**:
- 照片原图: `GET /uploads/photos/sunset_1704875400.jpg`
- 缩略图: `GET /uploads/photos/thumbs/sunset_1704875400_thumb.jpg`
- 用户头像: `GET /uploads/avatars/1_1704875400.jpg`

## 📝 开发指南

### 环境配置

1. **开发环境**:
   ```bash
   # 设置环境变量
   export ENV=development
   export DATABASE_HOST=localhost
   export DATABASE_PORT=5432
   export JWT_SECRET=your-jwt-secret
   
   # 启动服务
   go run cmd/api/main.go -f etc/photography-api.yaml
   ```

2. **生产环境**:
   ```bash
   # 使用 Docker Compose
   docker-compose -f configs/docker/docker-compose.prod.yml up -d
   ```

### 认证流程

1. 用户注册或登录获取 JWT Token
2. 在请求头中添加 `Authorization: Bearer <token>`
3. 服务器验证 Token 并提取用户信息
4. 权限检查通过后执行业务逻辑

### 错误处理

API 遵循统一的错误处理机制：

```json
{
  "code": 400,
  "message": "参数验证失败: 用户名不能为空",
  "data": null
}
```

常见错误码：
- `401`: 未登录或 Token 无效
- `403`: 权限不足
- `400`: 参数错误
- `404`: 资源不存在
- `500`: 服务器错误

### 性能优化

1. **分页查询**: 大数据量接口支持分页，减少单次传输数据量
2. **字段过滤**: 支持 `fields` 参数指定返回字段
3. **缓存机制**: 热点数据使用 Redis 缓存
4. **数据库优化**: 合理使用索引，避免N+1查询

### 安全考虑

1. **输入验证**: 所有用户输入都进行严格验证
2. **SQL注入防护**: 使用参数化查询
3. **文件上传安全**: 文件类型和大小限制
4. **Rate Limiting**: 接口频率限制
5. **CORS配置**: 跨域请求控制

## 📚 SDK 和工具

### JavaScript/TypeScript SDK

```typescript
import { PhotographyAPI } from 'photography-api-sdk';

const api = new PhotographyAPI({
  baseURL: 'https://api.photography.iriver.top/api/v1',
  token: 'your-jwt-token'
});

// 获取照片列表
const photos = await api.photos.list({
  page: 1,
  limit: 10,
  category_id: 1
});

// 上传照片
const photo = await api.photos.upload({
  file: fileBlob,
  title: '美丽的日落',
  description: '在海边拍摄的日落景色',
  category_id: 1
});
```

### Postman Collection

项目提供完整的 Postman Collection，包含所有接口的示例请求：

```bash
# 导入 Postman Collection
curl -o photography-api.postman_collection.json \
  https://raw.githubusercontent.com/photography/api-docs/main/postman/collection.json
```

### OpenAPI 规范

API 提供标准的 OpenAPI 3.0 规范文档：

- **Swagger UI**: `https://api.photography.iriver.top/swagger`
- **OpenAPI JSON**: `https://api.photography.iriver.top/api/openapi.json`

## 🚀 部署说明

### Docker 部署

```bash
# 拉取镜像
docker pull photography/api:latest

# 运行容器
docker run -d \
  --name photography-api \
  -p 8080:8080 \
  -e DATABASE_HOST=your-db-host \
  -e DATABASE_PASSWORD=your-db-password \
  -e JWT_SECRET=your-jwt-secret \
  photography/api:latest
```

### Kubernetes 部署

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: photography-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: photography-api
  template:
    metadata:
      labels:
        app: photography-api
    spec:
      containers:
      - name: api
        image: photography/api:latest
        ports:
        - containerPort: 8080
        env:
        - name: DATABASE_HOST
          value: "postgres-service"
        - name: JWT_SECRET
          valueFrom:
            secretKeyRef:
              name: api-secrets
              key: jwt-secret
```

## 📞 支持

- **技术文档**: https://docs.photography.iriver.top
- **GitHub Issues**: https://github.com/photography/api/issues
- **邮箱支持**: api-support@photography.com

---

*最后更新: 2024-01-10*