# API 接口文档

Base URL: `http://localhost:8080/api/v1`

在线文档: http://localhost:8080/swagger-ui/index.html

## 通用说明

### 响应格式

所有接口统一返回 `RestBean`：

```json
{
  "status": 200,
  "message": "success",
  "data": {}
}
```

### 认证方式

需要认证的接口在请求头中携带 JWT Token：

```
Authorization: Bearer <token>
```

登录/注册接口会返回 Token。

---

## 用户接口

### 注册

`POST /api/v1/user/register`

**公开接口**，无需认证。

请求体：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| username | String | 是 | 用户名，2-50 位 |
| password | String | 是 | 密码，6-64 位 |
| email | String | 否 | 邮箱 |

请求示例：

```json
{
  "username": "testuser",
  "password": "123456",
  "email": "test@example.com"
}
```

响应示例：

```json
{
  "status": 200,
  "message": "success",
  "data": "eyJhbGciOiJIUzUxMiJ9..."
}
```

---

### 登录

`POST /api/v1/user/login`

**公开接口**，无需认证。

请求体：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| username | String | 是 | 用户名 |
| password | String | 是 | 密码 |

请求示例：

```json
{
  "username": "testuser",
  "password": "123456"
}
```

响应示例：

```json
{
  "status": 200,
  "message": "success",
  "data": "eyJhbGciOiJIUzUxMiJ9..."
}
```

---

### 获取用户信息

`GET /api/v1/user/info`

**需要认证**。

请求头：

```
Authorization: Bearer <token>
```

响应示例：

```json
{
  "status": 200,
  "message": "success",
  "data": {
    "id": 1,
    "username": "testuser",
    "email": "test@example.com",
    "status": 1,
    "role": "USER",
    "createdAt": "2026-03-31 08:00:00",
    "updatedAt": "2026-03-31 08:00:00"
  }
}
```

---

### 发送密码找回验证码

`POST /api/v1/user/password-reset/request`

**公开接口**，无需认证。

请求体：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| email | String | 是 | 已注册的邮箱 |

请求示例：

```json
{
  "email": "test@example.com"
}
```

频率限制：
- 两次请求间隔至少 60 秒
- 同一邮箱 1 小时内最多 5 次

---

### 验证码重置密码

`POST /api/v1/user/password-reset/confirm`

**公开接口**，无需认证。

请求体：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| email | String | 是 | 邮箱 |
| code | String | 是 | 6 位数字验证码 |
| newPassword | String | 是 | 新密码，6-64 位 |

请求示例：

```json
{
  "email": "test@example.com",
  "code": "123456",
  "newPassword": "newpass123"
}
```

验证码限制：
- 有效期 10 分钟
- 最多尝试 5 次

---

### 用户列表（管理员）

`GET /api/v1/user/list`

**需要认证 + ADMIN 角色**。

请求参数：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | Integer | 否 | 页码，默认 1 |
| size | Integer | 否 | 每页条数，默认 10 |
| keyword | String | 否 | 搜索关键词（用户名/邮箱） |
| role | String | 否 | 角色筛选（USER/ADMIN） |
| status | Integer | 否 | 状态筛选（1=正常 0=禁用） |

响应示例：

```json
{
  "status": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "id": 1,
        "username": "admin",
        "email": "admin@example.com",
        "status": 1,
        "role": "ADMIN",
        "createdAt": "2026-03-31 08:00:00",
        "updatedAt": "2026-03-31 08:00:00"
      }
    ],
    "total": 1,
    "page": 1,
    "size": 10
  }
}
```

---

### 更新用户状态（管理员）

`PUT /api/v1/user/{userId}/status`

**需要认证 + ADMIN 角色**。

路径参数：

| 参数 | 类型 | 说明 |
|------|------|------|
| userId | Long | 用户 ID |

请求体：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| status | Integer | 是 | 1=启用，0=禁用 |

请求示例：

```json
{
  "status": 0
}
```

> 不允许修改自己的状态。

---

### 更新用户角色（管理员）

`PUT /api/v1/user/{userId}/role`

**需要认证 + ADMIN 角色**。

路径参数：

| 参数 | 类型 | 说明 |
|------|------|------|
| userId | Long | 用户 ID |

请求体：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| role | String | 是 | 角色名称：USER 或 ADMIN |

请求示例：

```json
{
  "role": "ADMIN"
}
```

> 不允许修改自己的角色。

---

## 错误码

| 错误码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 参数错误 / 请求格式错误 |
| 403 | 权限不足 / 账号被禁用 |
| 404 | 数据不存在 |
| 500 | 系统异常 |

业务错误码：

| 错误码 | 说明 |
|--------|------|
| 1001 | 用户不存在 |
| 1002 | 密码错误 |
| 1003 | 账号已被锁定 |