From 032c97a1fc4a529e4ad60beb3ce8614253dc9be3 Mon Sep 17 00:00:00 2001 From: moyin <244344649@qq.com> Date: Tue, 23 Dec 2025 19:51:34 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=85=A8=E9=9D=A2=E6=9B=B4=E6=96=B0API?= =?UTF-8?q?=E6=8E=A5=E5=8F=A3=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 重构文档结构，按功能模块分类 - 新增应用状态接口 (GET /) - 完善用户认证接口，新增4个邮箱验证相关接口 - 新增管理员后台接口，包含用户管理和日志管理 - 更新错误代码说明和数据验证规则 - 完善使用示例和注意事项 - 更新版本日志至v1.0.0 涵盖后端所有API接口，提供完整的开发参考文档 --- docs/api/api-documentation.md | 598 ++++++++++++++++++++++++++++++---- 1 file changed, 529 insertions(+), 69 deletions(-) diff --git a/docs/api/api-documentation.md b/docs/api/api-documentation.md index e7a7567..c9e44ed 100644 --- a/docs/api/api-documentation.md +++ b/docs/api/api-documentation.md @@ -1,11 +1,13 @@ -# 用户认证API接口文档 +# Pixel Game Server API接口文档 ## 概述 -本文档描述了像素游戏服务器的用户认证相关API接口，包括登录、注册、密码找回等功能。 +本文档描述了像素游戏服务器的完整API接口，包括用户认证、管理员后台、应用状态等功能。 **基础URL**: `http://localhost:3000` -**API文档地址**: `http://localhost:3000/api-docs` +**API文档地址**: `http://localhost:3000/api-docs` +**项目名称**: Pixel Game Server +**版本**: 1.0.0 ## 通用响应格式 @@ -27,9 +29,73 @@ - `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. 用户登录 +### 应用状态接口 + +#### 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` @@ -84,7 +150,7 @@ } ``` -### 2. 用户注册 +#### 2. 用户注册 **接口地址**: `POST /auth/register` @@ -144,7 +210,7 @@ } ``` -### 3. GitHub OAuth登录 +#### 3. GitHub OAuth登录 **接口地址**: `POST /auth/github` @@ -195,7 +261,7 @@ } ``` -### 4. 发送密码重置验证码 +#### 4. 发送密码重置验证码 **接口地址**: `POST /auth/forgot-password` @@ -228,7 +294,7 @@ **注意**: 实际应用中不应返回验证码，这里仅用于演示。 -### 5. 重置密码 +#### 5. 重置密码 **接口地址**: `POST /auth/reset-password` @@ -260,7 +326,7 @@ } ``` -### 6. 修改密码 +#### 6. 修改密码 **接口地址**: `PUT /auth/change-password` @@ -292,6 +358,344 @@ } ``` +#### 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 `，且用户角色必须为管理员 (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 文件） + ## 错误代码说明 | 错误代码 | 说明 | @@ -302,6 +706,10 @@ | SEND_CODE_FAILED | 发送验证码失败 | | RESET_PASSWORD_FAILED | 重置密码失败 | | CHANGE_PASSWORD_FAILED | 修改密码失败 | +| TEST_MODE_ONLY | 测试模式（验证码未真实发送） | +| ADMIN_LOGIN_FAILED | 管理员登录失败 | +| ADMIN_USERS_FAILED | 获取用户列表失败 | +| ADMIN_OPERATION_FAILED | 管理员操作失败 | ## 数据验证规则 @@ -318,12 +726,27 @@ ### 验证码规则 - 长度：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', @@ -343,7 +766,19 @@ if (loginData.success) { 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: { @@ -353,16 +788,45 @@ const registerResponse = await fetch('http://localhost:3000/auth/register', { username: 'newuser', password: 'password123', nickname: '新用户', - email: 'newuser@example.com' + email: 'newuser@example.com', + email_verification_code: '123456' }) }); -const registerData = await registerResponse.json(); +// 管理员登录 +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" \ @@ -371,6 +835,13 @@ curl -X POST http://localhost:3000/auth/login \ "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" \ @@ -378,81 +849,70 @@ curl -X POST http://localhost:3000/auth/register \ "username": "newuser", "password": "password123", "nickname": "新用户", - "email": "newuser@example.com" + "email": "newuser@example.com", + "email_verification_code": "123456" }' -# 发送密码重置验证码 -curl -X POST http://localhost:3000/auth/forgot-password \ +# 管理员登录 +curl -X POST http://localhost:3000/admin/auth/login \ -H "Content-Type: application/json" \ -d '{ - "identifier": "test@example.com" + "identifier": "admin", + "password": "Admin123456" }' -# 重置密码 -curl -X POST http://localhost:3000/auth/reset-password \ +# 获取用户列表（需要管理员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 '{ - "identifier": "test@example.com", - "verification_code": "123456", - "new_password": "newpassword123" + "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是简单的Base64编码，实际应用中应使用JWT -3. **验证码**: 实际应用中不应在响应中返回验证码 +2. **令牌**: 示例中的access_token是JWT格式，需要妥善保存 +3. **验证码**: + - 实际应用中不应在响应中返回验证码 + - 测试模式下会在控制台显示验证码 + - 验证码有效期通常为5-15分钟 4. **用户ID**: 修改密码接口中的user_id应从JWT令牌中获取，而不是从请求体中传递 5. **错误处理**: 建议在客户端实现适当的错误处理和用户提示 6. **限流**: 建议对登录、注册等接口实施限流策略 +7. **管理员权限**: + - 管理员接口需要 role=9 的用户权限 + - 需要在请求头中携带有效的JWT Token + - Token格式：`Authorization: Bearer ` +8. **存储模式**: + - 数据库模式：数据持久化存储在MySQL + - 内存模式：数据存储在内存中，重启后丢失 +9. **邮箱验证**: + - 注册时如果提供邮箱，需要先获取验证码 + - 支持重新发送验证码功能 + - 调试接口仅用于开发环境 ## 更新日志 -- **v1.0.0** (2025-12-17): 初始版本，包含基础的用户认证功能 -## 管理员接口 +- **v1.0.0** (2025-12-23): + - 完整的API文档更新 + - 新增应用状态接口 + - 新增邮箱验证相关接口 + - 新增管理员后台接口 + - 新增日志管理功能 + - 完善错误代码和使用示例 -**注意**：所有管理员接口都需要在 Header 中携带 ，且用户角色必须为管理员 (role=9)。 - -### 1. 获取用户列表 - -**接口地址**: `GET /admin/users` - -**功能描述**: 分页获取所有注册用户列表 - -#### 请求参数 - -| 参数名 | 类型 | 必填 | 说明 | -|--------|------|------|------| -| page | number | 否 | 页码，默认1 | -| limit | number | 否 | 每页数量，默认10 | - -### 2. 重置用户密码 - -**接口地址**: `POST /admin/users/:id/reset-password` - -**功能描述**: 管理员强制重置指定用户的密码 - -#### 请求参数 - -| 参数名 | 类型 | 必填 | 说明 | -|--------|------|------|------| -| password | string | 是 | 新密码 | - -### 3. 删除用户 - -**接口地址**: `DELETE /admin/users/:id` - -**功能描述**: 删除指定用户 - -### 4. 修改用户角色 - -**接口地址**: `POST /admin/users/:id/role` - -**功能描述**: 修改用户的角色权限 - -#### 请求参数 - -| 参数名 | 类型 | 必填 | 说明 | -|--------|------|------|------| -| role | number | 是 | 角色ID (1:普通用户, 9:管理员) |