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

# Pixel Game Server API接口文档

## 概述

本文档描述了像素游戏服务器的完整API接口，包括用户认证、管理员后台、应用状态等功能。

**基础URL**: `http://localhost:3000`  
**API文档地址**: `http://localhost:3000/api-docs`  
**项目名称**: Pixel Game Server  
**版本**: 1.0.0

## 通用响应格式

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

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

### 字段说明

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

## 接口分类

### 1. 应用状态接口 (App)
- `GET /` - 获取应用状态

### 2. 用户认证接口 (Auth)
- `POST /auth/login` - 用户登录
- `POST /auth/register` - 用户注册
- `POST /auth/github` - GitHub OAuth登录
- `POST /auth/forgot-password` - 发送密码重置验证码
- `POST /auth/reset-password` - 重置密码
- `PUT /auth/change-password` - 修改密码
- `POST /auth/send-email-verification` - 发送邮箱验证码
- `POST /auth/verify-email` - 验证邮箱验证码
- `POST /auth/resend-email-verification` - 重新发送邮箱验证码
- `POST /auth/debug-verification-code` - 调试验证码信息（开发环境）

### 3. 管理员接口 (Admin)
- `POST /admin/auth/login` - 管理员登录
- `GET /admin/users` - 获取用户列表
- `GET /admin/users/:id` - 获取用户详情
- `POST /admin/users/:id/reset-password` - 重置用户密码
- `GET /admin/logs/runtime` - 获取运行日志
- `GET /admin/logs/archive` - 下载日志压缩包

## 接口列表

### 应用状态接口

#### 1. 获取应用状态

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

**功能描述**: 返回应用的基本运行状态信息，用于健康检查和监控

#### 请求参数

无

#### 响应示例

**成功响应** (200):
```json
{
  "service": "Pixel Game Server",
  "version": "1.0.0",
  "status": "running",
  "timestamp": "2025-12-23T10:00:00.000Z",
  "uptime": 3600,
  "environment": "development",
  "storage_mode": "memory"
}
```

| 字段名 | 类型 | 说明 |
|--------|------|------|
| service | string | 服务名称 |
| version | string | 服务版本 |
| status | string | 运行状态 (running/starting/stopping/error) |
| timestamp | string | 当前时间戳 |
| uptime | number | 运行时间（秒） |
| environment | string | 运行环境 (development/production/test) |
| storage_mode | string | 存储模式 (database/memory) |

### 用户认证接口

#### 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": "密码修改成功"
}
```

#### 7. 发送邮箱验证码

**接口地址**: `POST /auth/send-email-verification`

**功能描述**: 向指定邮箱发送验证码，用于注册时的邮箱验证

#### 请求参数

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

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| email | string | 是 | 邮箱地址 |

#### 响应示例

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

**测试模式响应** (206):
```json
{
  "success": false,
  "data": {
    "verification_code": "059174",
    "is_test_mode": true
  },
  "message": "⚠️ 测试模式：验证码已生成但未真实发送。请在控制台查看验证码，或配置邮件服务以启用真实发送。",
  "error_code": "TEST_MODE_ONLY"
}
```

#### 8. 验证邮箱验证码

**接口地址**: `POST /auth/verify-email`

**功能描述**: 使用验证码验证邮箱

#### 请求参数

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

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| email | string | 是 | 邮箱地址 |
| verification_code | string | 是 | 6位数字验证码 |

#### 响应示例

**成功响应** (200):
```json
{
  "success": true,
  "message": "邮箱验证成功"
}
```

#### 9. 重新发送邮箱验证码

**接口地址**: `POST /auth/resend-email-verification`

**功能描述**: 重新向指定邮箱发送验证码

#### 请求参数

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

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| email | string | 是 | 邮箱地址 |

#### 响应示例

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

#### 10. 调试验证码信息

**接口地址**: `POST /auth/debug-verification-code`

**功能描述**: 获取验证码的详细调试信息（仅开发环境使用）

#### 请求参数

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

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| email | string | 是 | 邮箱地址 |

#### 响应示例

**成功响应** (200):
```json
{
  "success": true,
  "data": {
    "email": "test@example.com",
    "verification_code": "123456",
    "expires_at": "2025-12-23T10:15:00.000Z",
    "created_at": "2025-12-23T10:00:00.000Z"
  },
  "message": "调试信息获取成功"
}
```

### 管理员接口

**注意**：所有管理员接口都需要在 Header 中携带 `Authorization: Bearer <token>`，且用户角色必须为管理员 (role=9)。

#### 1. 管理员登录

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

**功能描述**: 管理员登录，仅允许 role=9 的账户登录后台

#### 请求参数

```json
{
  "identifier": "admin",
  "password": "Admin123456"
}
```

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| identifier | string | 是 | 登录标识符（用户名/邮箱/手机号） |
| password | string | 是 | 密码 |

#### 响应示例

**成功响应** (200):
```json
{
  "success": true,
  "data": {
    "admin": {
      "id": "1",
      "username": "admin",
      "nickname": "管理员",
      "role": 9
    },
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_at": 1766102400000
  },
  "message": "管理员登录成功"
}
```

#### 2. 获取用户列表

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

**功能描述**: 分页获取所有注册用户列表

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| limit | number | 否 | 每页数量，默认100 |
| offset | number | 否 | 偏移量，默认0 |

#### 响应示例

**成功响应** (200):
```json
{
  "success": true,
  "data": {
    "users": [
      {
        "id": "1",
        "username": "user1",
        "nickname": "小明",
        "email": "user1@example.com",
        "email_verified": false,
        "phone": "+8613800138000",
        "avatar_url": "https://example.com/avatar.png",
        "role": 1,
        "created_at": "2025-12-19T00:00:00.000Z",
        "updated_at": "2025-12-19T00:00:00.000Z"
      }
    ],
    "limit": 100,
    "offset": 0
  },
  "message": "用户列表获取成功"
}
```

#### 3. 获取用户详情

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

**功能描述**: 获取指定用户的详细信息

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | string | 是 | 用户ID（路径参数） |

#### 响应示例

**成功响应** (200):
```json
{
  "success": true,
  "data": {
    "user": {
      "id": "1",
      "username": "user1",
      "nickname": "小明",
      "email": "user1@example.com",
      "email_verified": false,
      "phone": "+8613800138000",
      "avatar_url": "https://example.com/avatar.png",
      "role": 1,
      "created_at": "2025-12-19T00:00:00.000Z",
      "updated_at": "2025-12-19T00:00:00.000Z"
    }
  },
  "message": "用户信息获取成功"
}
```

#### 4. 重置用户密码

**接口地址**: `POST /admin/users/:id/reset-password`

**功能描述**: 管理员强制重置指定用户的密码

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | string | 是 | 用户ID（路径参数） |
| new_password | string | 是 | 新密码（至少8位，包含字母和数字） |

```json
{
  "new_password": "NewPass1234"
}
```

#### 响应示例

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

#### 5. 获取运行日志

**接口地址**: `GET /admin/logs/runtime`

**功能描述**: 从 logs/ 目录读取最近的日志行

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| lines | number | 否 | 返回行数，默认200，最大2000 |

#### 响应示例

**成功响应** (200):
```json
{
  "success": true,
  "data": {
    "file": "dev.log",
    "updated_at": "2025-12-19T19:10:15.000Z",
    "lines": [
      "[2025-12-19 19:10:15] INFO: Server started",
      "[2025-12-19 19:10:16] INFO: Database connected"
    ]
  },
  "message": "运行日志获取成功"
}
```

#### 6. 下载日志压缩包

**接口地址**: `GET /admin/logs/archive`

**功能描述**: 将 logs/ 目录打包为 tar.gz 并下载

#### 请求参数

无

#### 响应示例

**成功响应** (200):
- Content-Type: `application/gzip`
- Content-Disposition: `attachment; filename="logs-2025-12-23T10-00-00-000Z.tar.gz"`
- 返回二进制流（tar.gz 文件）

## 错误代码说明

| 错误代码 | 说明 |
|----------|------|
| LOGIN_FAILED | 登录失败 |
| REGISTER_FAILED | 注册失败 |
| GITHUB_OAUTH_FAILED | GitHub OAuth失败 |
| SEND_CODE_FAILED | 发送验证码失败 |
| RESET_PASSWORD_FAILED | 重置密码失败 |
| CHANGE_PASSWORD_FAILED | 修改密码失败 |
| TEST_MODE_ONLY | 测试模式（验证码未真实发送） |
| ADMIN_LOGIN_FAILED | 管理员登录失败 |
| ADMIN_USERS_FAILED | 获取用户列表失败 |
| ADMIN_OPERATION_FAILED | 管理员操作失败 |

## 数据验证规则

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

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

### 验证码规则
- 长度：6位数字
- 正则表达式：`^\d{6}$`
- 有效期：通常为5-15分钟

### 邮箱规则
- 格式：符合标准邮箱格式
- 验证：支持邮箱验证码验证

### 管理员权限
- 角色：role=9 为管理员
- 认证：需要 JWT Token
- 权限：可管理所有用户数据

## 使用示例

### JavaScript/TypeScript 示例

```typescript
// 获取应用状态
const statusResponse = await fetch('http://localhost:3000/');
const statusData = await statusResponse.json();
console.log('服务状态:', statusData.status);

// 用户登录
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);
}

// 用户注册（带邮箱验证）
// 1. 先发送邮箱验证码
const sendCodeResponse = await fetch('http://localhost:3000/auth/send-email-verification', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'newuser@example.com'
  })
});

// 2. 用户输入验证码后进行注册
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',
    email_verification_code: '123456'
  })
});

// 管理员登录
const adminLoginResponse = await fetch('http://localhost:3000/admin/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    identifier: 'admin',
    password: 'Admin123456'
  })
});

const adminData = await adminLoginResponse.json();
if (adminData.success) {
  const adminToken = adminData.data.access_token;
  
  // 获取用户列表
  const usersResponse = await fetch('http://localhost:3000/admin/users?limit=10&offset=0', {
    headers: {
      'Authorization': `Bearer ${adminToken}`
    }
  });
  
  const usersData = await usersResponse.json();
  console.log('用户列表:', usersData.data.users);
}
```

### cURL 示例

```bash
# 获取应用状态
curl -X GET http://localhost:3000/

# 用户登录
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/send-email-verification \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com"
  }'

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

# 管理员登录
curl -X POST http://localhost:3000/admin/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "admin",
    "password": "Admin123456"
  }'

# 获取用户列表（需要管理员Token）
curl -X GET "http://localhost:3000/admin/users?limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

# 重置用户密码
curl -X POST http://localhost:3000/admin/users/1/reset-password \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -d '{
    "new_password": "NewPass1234"
  }'

# 获取运行日志
curl -X GET "http://localhost:3000/admin/logs/runtime?lines=100" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

# 下载日志压缩包
curl -X GET http://localhost:3000/admin/logs/archive \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -o logs.tar.gz
```

## 注意事项

1. **安全性**: 实际应用中应使用HTTPS协议
2. **令牌**: 示例中的access_token是JWT格式，需要妥善保存
3. **验证码**: 
   - 实际应用中不应在响应中返回验证码
   - 测试模式下会在控制台显示验证码
   - 验证码有效期通常为5-15分钟
4. **用户ID**: 修改密码接口中的user_id应从JWT令牌中获取，而不是从请求体中传递
5. **错误处理**: 建议在客户端实现适当的错误处理和用户提示
6. **限流**: 建议对登录、注册等接口实施限流策略
7. **管理员权限**: 
   - 管理员接口需要 role=9 的用户权限
   - 需要在请求头中携带有效的JWT Token
   - Token格式：`Authorization: Bearer <token>`
8. **存储模式**:
   - 数据库模式：数据持久化存储在MySQL
   - 内存模式：数据存储在内存中，重启后丢失
9. **邮箱验证**:
   - 注册时如果提供邮箱，需要先获取验证码
   - 支持重新发送验证码功能
   - 调试接口仅用于开发环境

## 更新日志

- **v1.0.0** (2025-12-23): 
  - 完整的API文档更新
  - 新增应用状态接口
  - 新增邮箱验证相关接口
  - 新增管理员后台接口
  - 新增日志管理功能
  - 完善错误代码和使用示例