datawhale/whale-town-end
3
4
Fork 2
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 全面更新API接口文档

Browse Source 
- 重构文档结构，按功能模块分类
- 新增应用状态接口 (GET /)
- 完善用户认证接口，新增4个邮箱验证相关接口
- 新增管理员后台接口，包含用户管理和日志管理
- 更新错误代码说明和数据验证规则
- 完善使用示例和注意事项
- 更新版本日志至v1.0.0

涵盖后端所有API接口，提供完整的开发参考文档
This commit is contained in:
moyin
2025-12-23 19:51:34 +08:00
parent 0313b78852
commit 032c97a1fc
1 changed files with 529 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

596
docs/api/api-documentation.md
View File

@@ -1,11 +1,13 @@
# 用户认证API接口文档 # Pixel Game Server API接口文档
## 概述 ## 概述
本文档描述了像素游戏服务器的用户认证相关API接口，包括登录、注册、密码找回等功能。 本文档描述了像素游戏服务器的完整API接口，包括用户认证、管理员后台、应用状态等功能。
**基础URL**: `http://localhost:3000` **基础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`: 响应消息 - `message`: 响应消息
- `error_code`: 错误代码（失败时返回） - `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` **接口地址**: `POST /auth/login`
@@ -84,7 +150,7 @@
} }
``` ```
### 2. 用户注册 #### 2. 用户注册
**接口地址**: `POST /auth/register` **接口地址**: `POST /auth/register`
@@ -144,7 +210,7 @@
} }
``` ```
### 3. GitHub OAuth登录 #### 3. GitHub OAuth登录
**接口地址**: `POST /auth/github` **接口地址**: `POST /auth/github`
@@ -195,7 +261,7 @@
} }
``` ```
### 4. 发送密码重置验证码 #### 4. 发送密码重置验证码
**接口地址**: `POST /auth/forgot-password` **接口地址**: `POST /auth/forgot-password`
@@ -228,7 +294,7 @@
**注意**: 实际应用中不应返回验证码，这里仅用于演示。 **注意**: 实际应用中不应返回验证码，这里仅用于演示。
### 5. 重置密码 #### 5. 重置密码
**接口地址**: `POST /auth/reset-password` **接口地址**: `POST /auth/reset-password`
@@ -260,7 +326,7 @@
} }
``` ```
### 6. 修改密码 #### 6. 修改密码
**接口地址**: `PUT /auth/change-password` **接口地址**: `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 <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 文件）
## 错误代码说明 ## 错误代码说明
| 错误代码 | 说明 | | 错误代码 | 说明 |
@@ -302,6 +706,10 @@
| SEND_CODE_FAILED | 发送验证码失败 | | SEND_CODE_FAILED | 发送验证码失败 |
| RESET_PASSWORD_FAILED | 重置密码失败 | | RESET_PASSWORD_FAILED | 重置密码失败 |
| CHANGE_PASSWORD_FAILED | 修改密码失败 | | CHANGE_PASSWORD_FAILED | 修改密码失败 |
| TEST_MODE_ONLY | 测试模式（验证码未真实发送） |
| ADMIN_LOGIN_FAILED | 管理员登录失败 |
| ADMIN_USERS_FAILED | 获取用户列表失败 |
| ADMIN_OPERATION_FAILED | 管理员操作失败 |
## 数据验证规则 ## 数据验证规则
@@ -318,12 +726,27 @@
### 验证码规则 ### 验证码规则
- 长度：6位数字 - 长度：6位数字
- 正则表达式：`^\d{6}$` - 正则表达式：`^\d{6}$`
- 有效期：通常为5-15分钟
### 邮箱规则
- 格式：符合标准邮箱格式
- 验证：支持邮箱验证码验证
### 管理员权限
- 角色：role=9 为管理员
- 认证：需要 JWT Token
- 权限：可管理所有用户数据
## 使用示例 ## 使用示例
### JavaScript/TypeScript 示例 ### JavaScript/TypeScript 示例
```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', { const loginResponse = await fetch('http://localhost:3000/auth/login', {
method: 'POST', method: 'POST',
@@ -343,7 +766,19 @@ if (loginData.success) {
localStorage.setItem('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', { const registerResponse = await fetch('http://localhost:3000/auth/register', {
method: 'POST', method: 'POST',
headers: { headers: {
@@ -353,16 +788,45 @@ const registerResponse = await fetch('http://localhost:3000/auth/register', {
username: 'newuser', username: 'newuser',
password: 'password123', password: 'password123',
nickname: '新用户', 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 示例 ### cURL 示例
```bash ```bash
# 获取应用状态
curl -X GET http://localhost:3000/
# 用户登录 # 用户登录
curl -X POST http://localhost:3000/auth/login \ curl -X POST http://localhost:3000/auth/login \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
@@ -371,6 +835,13 @@ curl -X POST http://localhost:3000/auth/login \
"password": "password123" "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 \ curl -X POST http://localhost:3000/auth/register \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
@@ -378,81 +849,70 @@ curl -X POST http://localhost:3000/auth/register \
"username": "newuser", "username": "newuser",
"password": "password123", "password": "password123",
"nickname": "新用户", "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" \ -H "Content-Type: application/json" \
-d '{ -d '{
"identifier": "test@example.com" "identifier": "admin",
"password": "Admin123456"
}' }'
# 重置密码 # 获取用户列表（需要管理员Token）
curl -X POST http://localhost:3000/auth/reset-password \ 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 "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
-d '{ -d '{
"identifier": "test@example.com", "new_password": "NewPass1234"
"verification_code": "123456",
"new_password": "newpassword123"
}' }'
# 获取运行日志
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协议 1. **安全性**: 实际应用中应使用HTTPS协议
2. **令牌**: 示例中的access_token是简单的Base64编码，实际应用中应使用JWT 2. **令牌**: 示例中的access_token是JWT格式，需要妥善保存
3. **验证码**: 实际应用中不应在响应中返回验证码 3. **验证码**:
- 实际应用中不应在响应中返回验证码
- 测试模式下会在控制台显示验证码
- 验证码有效期通常为5-15分钟
4. **用户ID**: 修改密码接口中的user_id应从JWT令牌中获取，而不是从请求体中传递 4. **用户ID**: 修改密码接口中的user_id应从JWT令牌中获取，而不是从请求体中传递
5. **错误处理**: 建议在客户端实现适当的错误处理和用户提示 5. **错误处理**: 建议在客户端实现适当的错误处理和用户提示
6. **限流**: 建议对登录、注册等接口实施限流策略 6. **限流**: 建议对登录、注册等接口实施限流策略
7. **管理员权限**:
- 管理员接口需要 role=9 的用户权限
- 需要在请求头中携带有效的JWT Token
- Token格式：`Authorization: Bearer <token>`
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:管理员) |