# 爱鉴花Java后端API接口文档

## 1. 概述
本文档定义了爱鉴花项目Java后端的所有API接口规范，包括请求方式、参数、响应格式和错误处理等。

## 2. 基础信息

- **Base URL**: `http://localhost:3200`
- **认证方式**: Bearer Token (JWT)
- **响应格式**: JSON
- **字符编码**: UTF-8

## 3. 公共请求头

| 头部名称 | 是否必须 | 说明 |
|---------|---------|------|
| Authorization | 是 | Bearer Token，格式为 `Bearer <token>` |
| Content-Type | 否 | 请求体类型，上传文件时为 `multipart/form-data` |

## 4. 公共响应格式

## 3. 公共响应格式

### 成功响应
```json
{
  "code": 200,
  "message": "成功",
  "data": {}
}
```

### 分页响应
```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "list": [],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 0,
      "pages": 0
    }
  }
}
```

### 错误响应
```json
{
  "code": 400,
  "message": "参数错误",
  "data": null
}
```

## 4. 认证接口

### 用户登录
**POST** `/api/v1/auth/login`

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| username | string | 是 | 用户名 |
| password | string | 是 | 密码 |

**请求示例**:
```json
{
  "username": "admin",
  "password": "admin123"
}
```

**响应示例**:
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "user_id": 1,
    "username": "admin",
    "phone": "13800138000",
    "email": "admin@example.com",
    "user_type": "admin",
    "avatar_url": "/uploads/avatar.jpg",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

### 用户注册
**POST** `/api/v1/auth/register`

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| username | string | 是 | 用户名 |
| password | string | 是 | 密码 |
| phone | string | 是 | 手机号 |
| email | string | 否 | 邮箱 |
| user_type | string | 否 | 用户类型，默认为"user" |

**请求示例**:
```json
{
  "username": "newuser",
  "password": "password123",
  "phone": "13800138001",
  "email": "newuser@example.com"
}
```

**响应示例**:
```json
{
  "code": 201,
  "message": "注册成功",
  "data": {
    "user_id": 2,
    "username": "newuser",
    "phone": "13800138001",
    "email": "newuser@example.com",
    "user_type": "user",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

### 获取当前用户信息
**GET** `/api/v1/auth/me`

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

**响应示例**:
```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "user_id": 1,
    "username": "admin",
    "phone": "13800138000",
    "email": "admin@example.com",
    "user_type": "admin",
    "avatar_url": "/uploads/avatar.jpg",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

## 5. 用户接口

### 获取当前用户信息
**GET** `/users/me`

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

**响应示例**:
```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}
```

### 更新用户信息
**PUT** `/users/me`

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

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| email | string | 否 | 邮箱 |
| nickname | string | 否 | 昵称 |

**响应示例**:
```json
{
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": 1,
    "username": "admin",
    "email": "newemail@example.com",
    "nickname": "管理员"
  }
}
```

## 6. 文件上传接口

### 上传文件
**POST** `/api/v1/upload`

**请求头**:
```
Authorization: Bearer <token>
Content-Type: multipart/form-data
```

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| file | file | 是 | 文件 |
| type | string | 是 | 文件类型(image, document等) |

**请求示例**:
```bash
curl -X POST "http://localhost:3200/api/v1/upload" \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/image.jpg" \
  -F "type=image"
```

**响应示例**:
```json
{
  "code": 200,
  "message": "上传成功",
  "data": {
    "id": 1,
    "url": "/uploads/2024/01/15/abc123.jpg",
    "filename": "abc123.jpg",
    "original_name": "image.jpg",
    "type": "image",
    "size": 102400,
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 获取上传文件列表
**GET** `/api/v1/upload`

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

**查询参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | int | 否 | 页码，默认1 |
| size | int | 否 | 每页数量，默认10 |
| type | string | 否 | 文件类型筛选 |

**请求示例**:
```bash
curl -X GET "http://localhost:3200/api/v1/upload?page=1&size=10&type=image" \
  -H "Authorization: Bearer <token>"
```

**响应示例**:
```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "list": [
      {
        "id": 1,
        "url": "/uploads/2024/01/15/abc123.jpg",
        "filename": "abc123.jpg",
        "original_name": "image.jpg",
        "type": "image",
        "size": 102400,
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 10,
      "total": 1
    }
  }
}
```

### 删除上传文件
**DELETE** `/api/v1/upload/{id}`

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

**路径参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | int | 是 | 文件ID |

**请求示例**:
```bash
curl -X DELETE "http://localhost:3200/api/v1/upload/1" \
  -H "Authorization: Bearer <token>"
```

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

## 7. 健康检查接口

### 服务健康检查
**GET** `/health`

**响应示例**:
```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "status": "UP",
    "timestamp": "2024-01-15T10:30:00Z",
    "service": "aijianhua-backend"
  }
}
```

## 8. 错误码规范

| 错误码 | 错误信息 | 说明 |
|--------|----------|------|
| 200 | 成功 | 请求成功 |
| 201 | 创建成功 | 资源创建成功 |
| 400 | 参数错误 | 请求参数验证失败 |
| 401 | 未授权 | 需要登录认证 |
| 403 | 禁止访问 | 权限不足 |
| 404 | 资源不存在 | 请求的资源不存在 |
| 409 | 资源冲突 | 资源已存在或状态冲突 |
| 422 | 数据验证失败 | 请求数据格式正确但业务验证失败 |
| 500 | 服务器内部错误 | 服务器内部处理错误 |
| 503 | 服务不可用 | 服务暂时不可用 |

## 9. 安全要求

1. 所有敏感接口必须使用HTTPS
2. JWT token有效期7天
3. 密码使用bcrypt加密存储
4. 文件上传限制10MB
5. 支持CORS跨域访问
6. 请求频率限制（每分钟最多100次）
7. 敏感操作需要二次验证

## 10. 版本历史

- v1.0.0 (2024-03-15): 初始版本发布
- v1.1.0 (2024-03-16): 
  - 完善认证接口文档
  - 完善文件上传接口文档
  - 添加健康检查接口文档
  - 补充错误码规范
  - 增强安全要求说明

---
*本文档最后更新: 2024-03-15*