whale-town-end/docs/api/api-documentation.md

# 用户认证API接口文档

## 概述

本文档描述了像素游戏服务器的用户认证相关API接口，包括登录、注册、密码找回等功能。

**基础URL**: `http://localhost:3000`  
**API文档地址**: `http://localhost:3000/api-docs`

## 通用响应格式

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

```json
{
  "success": boolean,
  "data": object | null,
  "message": string,
  "error_code": string | null
}
```

### 字段说明

- `success`: 请求是否成功
- `data`: 响应数据（成功时返回）
- `message`: 响应消息
- `error_code`: 错误代码（失败时返回）

## 接口列表

### 1. 用户登录

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

**功能描述**: 用户登录，支持用户名、邮箱或手机号登录

#### 请求参数

```json
{
  "identifier": "testuser",
  "password": "password123"
}
```

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| identifier | string | 是 | 登录标识符，支持用户名、邮箱或手机号 |
| password | string | 是 | 用户密码 |

#### 响应示例

**成功响应** (200):
```json
{
  "success": true,
  "data": {
    "user": {
      "id": "1",
      "username": "testuser",
      "nickname": "测试用户",
      "email": "test@example.com",
      "phone": "+8613800138000",
      "avatar_url": "https://example.com/avatar.jpg",
      "role": 1,
      "created_at": "2025-12-17T10:00:00.000Z"
    },
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "is_new_user": false,
    "message": "登录成功"
  },
  "message": "登录成功"
}
```

**失败响应** (401):
```json
{
  "success": false,
  "message": "用户名或密码错误",
  "error_code": "LOGIN_FAILED"
}
```

### 2. 用户注册

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

**功能描述**: 创建新用户账户

#### 请求参数

```json
{
  "username": "testuser",
  "password": "password123",
  "nickname": "测试用户",
  "email": "test@example.com",
  "phone": "+8613800138000"
}
```

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| username | string | 是 | 用户名，只能包含字母、数字和下划线，长度1-50字符 |
| password | string | 是 | 密码，必须包含字母和数字，长度8-128字符 |
| nickname | string | 是 | 用户昵称，长度1-50字符 |
| email | string | 否 | 邮箱地址 |
| phone | string | 否 | 手机号码 |

#### 响应示例

**成功响应** (201):
```json
{
  "success": true,
  "data": {
    "user": {
      "id": "2",
      "username": "testuser",
      "nickname": "测试用户",
      "email": "test@example.com",
      "phone": "+8613800138000",
      "avatar_url": null,
      "role": 1,
      "created_at": "2025-12-17T10:00:00.000Z"
    },
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "is_new_user": true,
    "message": "注册成功"
  },
  "message": "注册成功"
}
```

**失败响应** (409):
```json
{
  "success": false,
  "message": "用户名已存在",
  "error_code": "REGISTER_FAILED"
}
```

### 3. GitHub OAuth登录

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

**功能描述**: 使用GitHub账户登录或注册

#### 请求参数

```json
{
  "github_id": "12345678",
  "username": "octocat",
  "nickname": "The Octocat",
  "email": "octocat@github.com",
  "avatar_url": "https://github.com/images/error/octocat_happy.gif"
}
```

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| github_id | string | 是 | GitHub用户ID |
| username | string | 是 | GitHub用户名 |
| nickname | string | 是 | GitHub显示名称 |
| email | string | 否 | GitHub邮箱地址 |
| avatar_url | string | 否 | GitHub头像URL |

#### 响应示例

**成功响应** (200):
```json
{
  "success": true,
  "data": {
    "user": {
      "id": "3",
      "username": "octocat",
      "nickname": "The Octocat",
      "email": "octocat@github.com",
      "phone": null,
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "role": 1,
      "created_at": "2025-12-17T10:00:00.000Z"
    },
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "is_new_user": true,
    "message": "GitHub账户绑定成功"
  },
  "message": "GitHub账户绑定成功"
}
```

### 4. 发送密码重置验证码

**接口地址**: `POST /auth/forgot-password`

**功能描述**: 向用户邮箱或手机发送密码重置验证码

#### 请求参数

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

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| identifier | string | 是 | 邮箱或手机号 |

#### 响应示例

**成功响应** (200):
```json
{
  "success": true,
  "data": {
    "verification_code": "123456"
  },
  "message": "验证码已发送，请查收"
}
```

**注意**: 实际应用中不应返回验证码，这里仅用于演示。

### 5. 重置密码

**接口地址**: `POST /auth/reset-password`

**功能描述**: 使用验证码重置用户密码

#### 请求参数

```json
{
  "identifier": "test@example.com",
  "verification_code": "123456",
  "new_password": "newpassword123"
}
```

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| identifier | string | 是 | 邮箱或手机号 |
| verification_code | string | 是 | 6位数字验证码 |
| new_password | string | 是 | 新密码，必须包含字母和数字，长度8-128字符 |

#### 响应示例

**成功响应** (200):
```json
{
  "success": true,
  "message": "密码重置成功"
}
```

### 6. 修改密码

**接口地址**: `PUT /auth/change-password`

**功能描述**: 用户修改自己的密码（需要提供旧密码）

#### 请求参数

```json
{
  "user_id": "1",
  "old_password": "oldpassword123",
  "new_password": "newpassword123"
}
```

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| user_id | string | 是 | 用户ID（实际应用中应从JWT令牌中获取） |
| old_password | string | 是 | 当前密码 |
| new_password | string | 是 | 新密码，必须包含字母和数字，长度8-128字符 |

#### 响应示例

**成功响应** (200):
```json
{
  "success": true,
  "message": "密码修改成功"
}
```

## 错误代码说明

| 错误代码 | 说明 |
|----------|------|
| LOGIN_FAILED | 登录失败 |
| REGISTER_FAILED | 注册失败 |
| GITHUB_OAUTH_FAILED | GitHub OAuth失败 |
| SEND_CODE_FAILED | 发送验证码失败 |
| RESET_PASSWORD_FAILED | 重置密码失败 |
| CHANGE_PASSWORD_FAILED | 修改密码失败 |

## 数据验证规则

### 用户名规则
- 长度：1-50字符
- 格式：只能包含字母、数字和下划线
- 正则表达式：`^[a-zA-Z0-9_]+$`

### 密码规则
- 长度：8-128字符
- 格式：必须包含字母和数字
- 正则表达式：`^(?=.*[a-zA-Z])(?=.*\d)`

### 验证码规则
- 长度：6位数字
- 正则表达式：`^\d{6}$`

## 使用示例

### JavaScript/TypeScript 示例

```typescript
// 用户登录
const loginResponse = await fetch('http://localhost:3000/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    identifier: 'testuser',
    password: 'password123'
  })
});

const loginData = await loginResponse.json();
if (loginData.success) {
  const token = loginData.data.access_token;
  // 保存token用于后续请求
  localStorage.setItem('token', token);
}

// 用户注册
const registerResponse = await fetch('http://localhost:3000/auth/register', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    username: 'newuser',
    password: 'password123',
    nickname: '新用户',
    email: 'newuser@example.com'
  })
});

const registerData = await registerResponse.json();
```

### cURL 示例

```bash
# 用户登录
curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "testuser",
    "password": "password123"
  }'

# 用户注册
curl -X POST http://localhost:3000/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "password": "password123",
    "nickname": "新用户",
    "email": "newuser@example.com"
  }'

# 发送密码重置验证码
curl -X POST http://localhost:3000/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "test@example.com"
  }'

# 重置密码
curl -X POST http://localhost:3000/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "test@example.com",
    "verification_code": "123456",
    "new_password": "newpassword123"
  }'
```

## 注意事项

1. **安全性**: 实际应用中应使用HTTPS协议
2. **令牌**: 示例中的access_token是简单的Base64编码，实际应用中应使用JWT
3. **验证码**: 实际应用中不应在响应中返回验证码
4. **用户ID**: 修改密码接口中的user_id应从JWT令牌中获取，而不是从请求体中传递
5. **错误处理**: 建议在客户端实现适当的错误处理和用户提示
6. **限流**: 建议对登录、注册等接口实施限流策略

## 更新日志

- **v1.0.0** (2025-12-17): 初始版本，包含基础的用户认证功能