2496 lines
41 KiB
Markdown
2496 lines
41 KiB
Markdown
# Whale Town 像素游戏服务器 API 文档
|
||
|
||
**版本**: 2.0.0
|
||
**更新时间**: 2026-01-20
|
||
|
||
## <20> 目录
|
||
|
||
- [概述](#概述)
|
||
- [认证机制](#认证机制)
|
||
- [通用响应格式](#通用响应格式)
|
||
- [错误代码说明](#错误代码说明)
|
||
- [API接口列表](#api接口列表)
|
||
- [应用状态](#应用状态)
|
||
- [用户认证](#用户认证)
|
||
- [管理员接口](#管理员接口)
|
||
- [用户管理](#用户管理)
|
||
- [聊天系统](#聊天系统)
|
||
- [位置广播](#位置广播)
|
||
- [通知系统](#通知系统)
|
||
- [Zulip集成](#zulip集成)
|
||
- [数据库管理](#数据库管理)
|
||
- [操作日志](#操作日志)
|
||
|
||
---
|
||
|
||
## 概述
|
||
|
||
Whale Town 像素游戏服务器提供完整的 RESTful API 和 WebSocket 实时通信接口，支持：
|
||
|
||
- 用户认证与授权（JWT）
|
||
- 实时聊天和位置广播
|
||
- 管理员后台管理
|
||
- Zulip 第三方集成
|
||
- 通知推送系统
|
||
|
||
**基础URL**: `https://whaletownend.xinghangee.icu`
|
||
**WebSocket URL**: `wss://whaletownend.xinghangee.icu/game`
|
||
|
||
---
|
||
|
||
## 认证机制
|
||
|
||
### JWT Token 认证
|
||
|
||
大部分接口需要在请求头中携带 JWT Token：
|
||
|
||
```http
|
||
Authorization: Bearer <your_jwt_token>
|
||
```
|
||
|
||
### Token 获取方式
|
||
|
||
1. 用户登录：`POST /auth/login`
|
||
2. 用户注册：`POST /auth/register`
|
||
3. GitHub OAuth：`POST /auth/github`
|
||
4. 验证码登录：`POST /auth/verification-code-login`
|
||
|
||
### Token 刷新
|
||
|
||
使用刷新令牌获取新的访问令牌：`POST /auth/refresh-token`
|
||
|
||
---
|
||
|
||
## 通用响应格式
|
||
|
||
### 成功响应
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": { ... },
|
||
"message": "操作成功"
|
||
}
|
||
```
|
||
|
||
### 错误响应
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "错误描述",
|
||
"error_code": "ERROR_CODE"
|
||
}
|
||
```
|
||
|
||
|
||
---
|
||
|
||
## 错误代码说明
|
||
|
||
| 错误代码 | HTTP状态码 | 说明 |
|
||
|---------|-----------|------|
|
||
| LOGIN_FAILED | 401 | 登录失败（用户名或密码错误） |
|
||
| REGISTER_FAILED | 400/409 | 注册失败（参数错误或用户已存在） |
|
||
| TOKEN_REFRESH_FAILED | 401 | Token刷新失败 |
|
||
| VERIFICATION_CODE_LOGIN_FAILED | 401 | 验证码登录失败 |
|
||
| SEND_CODE_FAILED | 400/404 | 验证码发送失败 |
|
||
| RESET_PASSWORD_FAILED | 400 | 密码重置失败 |
|
||
| CHANGE_PASSWORD_FAILED | 400/401 | 密码修改失败 |
|
||
| TEST_MODE_ONLY | 206 | 测试模式（验证码未真实发送） |
|
||
| ADMIN_LOGIN_FAILED | 401/403 | 管理员登录失败 |
|
||
| USER_NOT_FOUND | 404 | 用户不存在 |
|
||
| TOO_MANY_REQUESTS | 429 | 请求过于频繁 |
|
||
|
||
---
|
||
|
||
## API接口列表
|
||
|
||
### 应用状态
|
||
|
||
#### 获取应用状态
|
||
|
||
**接口**: `GET /`
|
||
|
||
**描述**: 获取应用的基本运行状态信息，用于健康检查和服务监控
|
||
|
||
**认证**: 不需要
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"service": "Pixel Game Server",
|
||
"version": "2.0.0",
|
||
"status": "running",
|
||
"timestamp": "2026-01-20T10:00:00.000Z",
|
||
"uptime": 86400,
|
||
"environment": "production",
|
||
"storage_mode": "database"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 用户认证
|
||
|
||
#### 1. 用户登录
|
||
|
||
**接口**: `POST /auth/login`
|
||
|
||
**描述**: 支持用户名、邮箱或手机号登录
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"identifier": "testuser",
|
||
"password": "password123"
|
||
}
|
||
```
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"user": {
|
||
"id": "1",
|
||
"username": "testuser",
|
||
"nickname": "测试用户",
|
||
"email": "test@example.com",
|
||
"phone": null,
|
||
"avatar_url": null,
|
||
"role": 1,
|
||
"created_at": "2026-01-20T10:00:00.000Z"
|
||
},
|
||
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||
"is_new_user": false,
|
||
"message": "登录成功"
|
||
},
|
||
"message": "登录成功"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
- `401`: 用户名或密码错误
|
||
- `403`: 账户被禁用或锁定
|
||
- `429`: 登录尝试过于频繁
|
||
|
||
---
|
||
|
||
#### 2. 用户注册
|
||
|
||
**接口**: `POST /auth/register`
|
||
|
||
**描述**: 创建新用户账户，支持邮箱验证
|
||
|
||
**请求体（基础注册）**:
|
||
|
||
```json
|
||
{
|
||
"username": "newuser",
|
||
"password": "password123",
|
||
"nickname": "新用户"
|
||
}
|
||
```
|
||
|
||
**请求体（带邮箱验证）**:
|
||
|
||
```json
|
||
{
|
||
"username": "newuser",
|
||
"password": "password123",
|
||
"nickname": "新用户",
|
||
"email": "newuser@example.com",
|
||
"email_verification_code": "123456"
|
||
}
|
||
```
|
||
|
||
**成功响应 (201)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"user": {
|
||
"id": "2",
|
||
"username": "newuser",
|
||
"nickname": "新用户",
|
||
"email": "newuser@example.com",
|
||
"phone": null,
|
||
"avatar_url": null,
|
||
"role": 1,
|
||
"created_at": "2026-01-20T10:00:00.000Z"
|
||
},
|
||
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||
"is_new_user": true,
|
||
"message": "注册成功"
|
||
},
|
||
"message": "注册成功"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
- `400`: 验证码错误或参数错误
|
||
- `409`: 用户名或邮箱已存在
|
||
- `429`: 注册请求过于频繁
|
||
|
||
---
|
||
|
||
#### 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"
|
||
}
|
||
```
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"user": {
|
||
"id": "3",
|
||
"username": "octocat",
|
||
"nickname": "The Octocat",
|
||
"email": "octocat@github.com",
|
||
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
|
||
"role": 1,
|
||
"created_at": "2026-01-20T10:00:00.000Z"
|
||
},
|
||
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||
"is_new_user": false,
|
||
"message": "GitHub登录成功"
|
||
},
|
||
"message": "GitHub登录成功"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 4. 验证码登录
|
||
|
||
**接口**: `POST /auth/verification-code-login`
|
||
|
||
**描述**: 使用邮箱或手机号和验证码进行登录，无需密码
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"identifier": "test@example.com",
|
||
"verification_code": "123456"
|
||
}
|
||
```
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"user": { ... },
|
||
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||
"is_new_user": false,
|
||
"message": "验证码登录成功"
|
||
},
|
||
"message": "验证码登录成功"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
- `401`: 验证码错误或已过期
|
||
- `404`: 用户不存在
|
||
|
||
---
|
||
|
||
#### 5. 发送登录验证码
|
||
|
||
**接口**: `POST /auth/send-login-verification-code`
|
||
|
||
**描述**: 向用户邮箱或手机发送登录验证码
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"identifier": "test@example.com"
|
||
}
|
||
```
|
||
|
||
**成功响应 (200) - 生产环境**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"is_test_mode": false
|
||
},
|
||
"message": "验证码已发送，请查收"
|
||
}
|
||
```
|
||
|
||
**测试模式响应 (206) - 开发环境**:
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"data": {
|
||
"verification_code": "654321",
|
||
"is_test_mode": true
|
||
},
|
||
"message": "⚠️ 测试模式：验证码已生成但未真实发送。请在控制台查看验证码。",
|
||
"error_code": "TEST_MODE_ONLY"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
- `404`: 用户不存在
|
||
- `429`: 发送频率过高
|
||
|
||
---
|
||
|
||
#### 6. 发送邮箱验证码
|
||
|
||
**接口**: `POST /auth/send-email-verification`
|
||
|
||
**描述**: 向指定邮箱发送验证码（用于注册）
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"email": "test@example.com"
|
||
}
|
||
```
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"is_test_mode": false
|
||
},
|
||
"message": "验证码已发送，请查收邮件"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
- `409`: 邮箱已被注册
|
||
- `429`: 验证码发送过于频繁
|
||
|
||
---
|
||
|
||
#### 7. 验证邮箱验证码
|
||
|
||
**接口**: `POST /auth/verify-email`
|
||
|
||
**描述**: 使用验证码验证邮箱
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"email": "test@example.com",
|
||
"verification_code": "123456"
|
||
}
|
||
```
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "邮箱验证成功"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
- `400`: 验证码错误或已过期
|
||
|
||
---
|
||
|
||
#### 8. 重新发送邮箱验证码
|
||
|
||
**接口**: `POST /auth/resend-email-verification`
|
||
|
||
**描述**: 重新向指定邮箱发送验证码
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"email": "test@example.com"
|
||
}
|
||
```
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"is_test_mode": false
|
||
},
|
||
"message": "验证码已重新发送，请查收邮件"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
- `400`: 邮箱已验证，无需重复验证
|
||
- `429`: 发送频率过高
|
||
|
||
---
|
||
|
||
#### 9. 发送密码重置验证码
|
||
|
||
**接口**: `POST /auth/forgot-password`
|
||
|
||
**描述**: 向用户邮箱或手机发送密码重置验证码
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"identifier": "test@example.com"
|
||
}
|
||
```
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"is_test_mode": false
|
||
},
|
||
"message": "验证码已发送，请查收"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
- `404`: 用户不存在
|
||
- `429`: 发送频率过高
|
||
|
||
---
|
||
|
||
#### 10. 重置密码
|
||
|
||
**接口**: `POST /auth/reset-password`
|
||
|
||
**描述**: 使用验证码重置用户密码
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"identifier": "test@example.com",
|
||
"verification_code": "789012",
|
||
"new_password": "newpassword123"
|
||
}
|
||
```
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "密码重置成功"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
- `400`: 验证码错误或参数无效
|
||
- `404`: 用户不存在
|
||
- `429`: 重置请求过于频繁
|
||
|
||
---
|
||
|
||
#### 11. 修改密码
|
||
|
||
**接口**: `PUT /auth/change-password`
|
||
|
||
**描述**: 用户修改自己的密码（需要提供旧密码）
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"user_id": "1",
|
||
"old_password": "oldpassword123",
|
||
"new_password": "newpassword123"
|
||
}
|
||
```
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "密码修改成功"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
- `400`: 请求参数错误
|
||
- `401`: 旧密码不正确
|
||
- `404`: 用户不存在
|
||
|
||
---
|
||
|
||
#### 12. 刷新访问令牌
|
||
|
||
**接口**: `POST /auth/refresh-token`
|
||
|
||
**描述**: 使用有效的刷新令牌生成新的访问令牌
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
||
}
|
||
```
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||
"expires_in": 3600
|
||
},
|
||
"message": "令牌刷新成功"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
- `401`: 刷新令牌无效或已过期
|
||
- `404`: 用户不存在或已被禁用
|
||
- `429`: 刷新请求过于频繁
|
||
|
||
|
||
---
|
||
|
||
### 管理员接口
|
||
|
||
#### 1. 管理员登录
|
||
|
||
**接口**: `POST /admin/auth/login`
|
||
|
||
**描述**: 管理员身份认证，仅允许 role=9 的账户登录
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"identifier": "admin",
|
||
"password": "Admin123456"
|
||
}
|
||
```
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"admin": {
|
||
"id": "1",
|
||
"username": "admin",
|
||
"nickname": "管理员",
|
||
"role": 9
|
||
},
|
||
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||
"expires_in": 28800,
|
||
"message": "管理员登录成功"
|
||
},
|
||
"message": "管理员登录成功"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
- `401`: 用户名或密码错误
|
||
- `403`: 权限不足，需要管理员权限
|
||
- `429`: 登录尝试过于频繁
|
||
|
||
---
|
||
|
||
#### 2. 获取用户列表
|
||
|
||
**接口**: `GET /admin/users`
|
||
|
||
**描述**: 分页获取系统中的用户列表
|
||
|
||
**认证**: 需要管理员 Token
|
||
|
||
**查询参数**:
|
||
|
||
- `limit` (可选): 返回数量，默认100
|
||
- `offset` (可选): 偏移量，默认0
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"users": [
|
||
{
|
||
"id": "1",
|
||
"username": "testuser",
|
||
"nickname": "测试用户",
|
||
"email": "test@example.com",
|
||
"phone": null,
|
||
"role": 1,
|
||
"status": "active",
|
||
"email_verified": true,
|
||
"created_at": "2026-01-20T10:00:00.000Z",
|
||
"updated_at": "2026-01-20T10:00:00.000Z"
|
||
}
|
||
],
|
||
"pagination": {
|
||
"limit": 100,
|
||
"offset": 0,
|
||
"total": 1
|
||
}
|
||
},
|
||
"message": "用户列表获取成功"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 3. 获取用户详情
|
||
|
||
**接口**: `GET /admin/users/:id`
|
||
|
||
**描述**: 根据用户ID获取指定用户的详细信息
|
||
|
||
**认证**: 需要管理员 Token
|
||
|
||
**路径参数**:
|
||
|
||
- `id`: 用户ID
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"user": {
|
||
"id": "1",
|
||
"username": "testuser",
|
||
"nickname": "测试用户",
|
||
"email": "test@example.com",
|
||
"phone": null,
|
||
"role": 1,
|
||
"status": "active",
|
||
"email_verified": true,
|
||
"github_id": null,
|
||
"avatar_url": null,
|
||
"created_at": "2026-01-20T10:00:00.000Z",
|
||
"updated_at": "2026-01-20T10:00:00.000Z"
|
||
}
|
||
},
|
||
"message": "用户详情获取成功"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
- `404`: 用户不存在
|
||
|
||
---
|
||
|
||
#### 4. 重置用户密码
|
||
|
||
**接口**: `POST /admin/users/:id/reset-password`
|
||
|
||
**描述**: 管理员直接为指定用户设置新密码
|
||
|
||
**认证**: 需要管理员 Token
|
||
|
||
**路径参数**:
|
||
|
||
- `id`: 用户ID
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"newPassword": "newpassword123"
|
||
}
|
||
```
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "用户密码重置成功"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
- `400`: 密码不符合强度规则
|
||
- `404`: 用户不存在
|
||
- `429`: 操作过于频繁
|
||
|
||
---
|
||
|
||
#### 5. 获取运行时日志
|
||
|
||
**接口**: `GET /admin/logs/runtime`
|
||
|
||
**描述**: 从 logs/ 目录读取最近的日志行
|
||
|
||
**认证**: 需要管理员 Token
|
||
|
||
**查询参数**:
|
||
|
||
- `lines` (可选): 返回行数，默认200，最大2000
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"logs": [
|
||
"[2026-01-20 18:27:35] LOG [NestApplication] Nest application successfully started",
|
||
"[2026-01-20 18:27:35] LOG [RouterExplorer] Mapped {/, GET} route"
|
||
],
|
||
"total_lines": 2,
|
||
"timestamp": "2026-01-20T10:27:44.352Z"
|
||
},
|
||
"message": "运行时日志获取成功"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 6. 下载全部运行日志
|
||
|
||
**接口**: `GET /admin/logs/archive`
|
||
|
||
**描述**: 将 logs/ 目录打包为 tar.gz 并下载
|
||
|
||
**认证**: 需要管理员 Token
|
||
|
||
**响应**: 二进制流（application/gzip）
|
||
|
||
---
|
||
|
||
### 用户管理
|
||
|
||
#### 1. 修改用户状态
|
||
|
||
**接口**: `PUT /admin/users/:id/status`
|
||
|
||
**描述**: 管理员修改指定用户的账户状态
|
||
|
||
**认证**: 需要管理员 Token
|
||
|
||
**路径参数**:
|
||
|
||
- `id`: 用户ID
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"status": "locked",
|
||
"reason": "违规操作"
|
||
}
|
||
```
|
||
|
||
**支持的状态值**:
|
||
|
||
- `active`: 激活
|
||
- `inactive`: 未激活
|
||
- `locked`: 锁定
|
||
- `banned`: 禁用
|
||
- `deleted`: 已删除
|
||
- `pending`: 待审核
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"user": {
|
||
"id": "1",
|
||
"username": "testuser",
|
||
"status": "locked",
|
||
"updated_at": "2026-01-20T10:00:00.000Z"
|
||
}
|
||
},
|
||
"message": "用户状态修改成功"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
- `400`: 状态值无效
|
||
- `403`: 权限不足
|
||
- `404`: 用户不存在
|
||
- `429`: 操作过于频繁
|
||
|
||
---
|
||
|
||
#### 2. 批量修改用户状态
|
||
|
||
**接口**: `POST /admin/users/batch-status`
|
||
|
||
**描述**: 管理员批量修改多个用户的账户状态
|
||
|
||
**认证**: 需要管理员 Token
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"userIds": ["1", "2", "3"],
|
||
"status": "active",
|
||
"reason": "批量激活"
|
||
}
|
||
```
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"updated_count": 3,
|
||
"failed_count": 0,
|
||
"results": [
|
||
{
|
||
"user_id": "1",
|
||
"success": true,
|
||
"new_status": "active"
|
||
},
|
||
{
|
||
"user_id": "2",
|
||
"success": true,
|
||
"new_status": "active"
|
||
},
|
||
{
|
||
"user_id": "3",
|
||
"success": true,
|
||
"new_status": "active"
|
||
}
|
||
]
|
||
},
|
||
"message": "批量状态修改完成"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 3. 获取用户状态统计
|
||
|
||
**接口**: `GET /admin/users/status-stats`
|
||
|
||
**描述**: 获取各种用户状态的数量统计信息
|
||
|
||
**认证**: 需要管理员 Token
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"stats": {
|
||
"active": 15,
|
||
"inactive": 3,
|
||
"locked": 2,
|
||
"banned": 1,
|
||
"deleted": 0,
|
||
"pending": 5
|
||
},
|
||
"total": 26
|
||
},
|
||
"message": "用户状态统计获取成功"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 聊天系统
|
||
|
||
#### 1. 获取聊天历史记录
|
||
|
||
**接口**: `GET /chat/history`
|
||
|
||
**描述**: 获取指定地图的聊天历史记录
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**查询参数**:
|
||
|
||
- `mapId` (可选): 地图ID
|
||
- `limit` (可选): 消息数量限制
|
||
- `offset` (可选): 偏移量
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"messages": [
|
||
{
|
||
"id": "msg_123",
|
||
"userId": "1",
|
||
"username": "testuser",
|
||
"nickname": "测试用户",
|
||
"content": "Hello World",
|
||
"mapId": "map_001",
|
||
"timestamp": "2026-01-20T10:00:00.000Z"
|
||
}
|
||
],
|
||
"total": 100,
|
||
"limit": 50,
|
||
"offset": 0
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 2. 获取聊天系统状态
|
||
|
||
**接口**: `GET /chat/status`
|
||
|
||
**描述**: 获取聊天系统的运行状态和统计信息
|
||
|
||
**认证**: 不需要
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"websocket": {
|
||
"totalConnections": 150,
|
||
"authenticatedConnections": 120,
|
||
"activeSessions": 120,
|
||
"mapPlayerCounts": {
|
||
"map_001": 45,
|
||
"map_002": 38,
|
||
"map_003": 37
|
||
}
|
||
},
|
||
"zulip": {
|
||
"serverConnected": true,
|
||
"serverVersion": "11.4",
|
||
"botAccountActive": true,
|
||
"availableStreams": 12,
|
||
"gameStreams": ["Whale Port", "Pumpkin Valley", "Novice Village"],
|
||
"recentMessageCount": 156
|
||
},
|
||
"uptime": 86400,
|
||
"memory": {
|
||
"used": "128.5 MB",
|
||
"total": "256.0 MB",
|
||
"percentage": 50.2
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 3. 获取 WebSocket 连接信息
|
||
|
||
**接口**: `GET /chat/websocket/info`
|
||
|
||
**描述**: 获取 WebSocket 连接配置信息
|
||
|
||
**认证**: 不需要
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"websocketUrl": "wss://whaletownend.xinghangee.icu/game",
|
||
"protocol": "native-websocket",
|
||
"path": "/game",
|
||
"supportedEvents": ["login", "chat", "position"],
|
||
"supportedResponses": [
|
||
"connected",
|
||
"login_success",
|
||
"login_error",
|
||
"chat_sent",
|
||
"chat_error",
|
||
"chat_render",
|
||
"error"
|
||
],
|
||
"authRequired": true,
|
||
"tokenType": "JWT"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 位置广播
|
||
|
||
#### 1. 创建新会话
|
||
|
||
**接口**: `POST /location-broadcast/sessions`
|
||
|
||
**描述**: 创建一个新的游戏会话，用于多人位置广播
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"sessionId": "session_12345",
|
||
"name": "测试会话",
|
||
"description": "这是一个测试会话",
|
||
"maxUsers": 50,
|
||
"allowObservers": true,
|
||
"password": "optional_password",
|
||
"allowedMaps": ["map_001", "map_002"],
|
||
"broadcastRange": 100,
|
||
"metadata": {
|
||
"custom_field": "value"
|
||
}
|
||
}
|
||
```
|
||
|
||
**成功响应 (201)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"sessionId": "session_12345",
|
||
"createdAt": 1641024000000,
|
||
"config": {
|
||
"maxUsers": 50,
|
||
"allowObservers": true,
|
||
"broadcastRange": 100
|
||
},
|
||
"metadata": {
|
||
"custom_field": "value"
|
||
}
|
||
},
|
||
"message": "会话创建成功"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
- `400`: 请求参数错误
|
||
- `409`: 会话ID已存在
|
||
|
||
---
|
||
|
||
#### 2. 查询会话列表
|
||
|
||
**接口**: `GET /location-broadcast/sessions`
|
||
|
||
**描述**: 根据条件查询游戏会话列表
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**查询参数**:
|
||
|
||
- `status` (可选): 会话状态
|
||
- `minUsers` (可选): 最小用户数
|
||
- `maxUsers` (可选): 最大用户数
|
||
- `publicOnly` (可选): 只显示公开会话
|
||
- `offset` (可选): 分页偏移
|
||
- `limit` (可选): 分页大小
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"sessions": [
|
||
{
|
||
"sessionId": "session_12345",
|
||
"name": "测试会话",
|
||
"status": "active",
|
||
"currentUsers": 15,
|
||
"maxUsers": 50,
|
||
"createdAt": 1641024000000
|
||
}
|
||
],
|
||
"total": 10,
|
||
"page": 1,
|
||
"pageSize": 10
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 3. 获取会话详情
|
||
|
||
**接口**: `GET /location-broadcast/sessions/:sessionId`
|
||
|
||
**描述**: 获取指定会话的详细信息，包括用户列表和位置信息
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**路径参数**:
|
||
|
||
- `sessionId`: 会话ID
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"session": {
|
||
"sessionId": "session_12345",
|
||
"name": "测试会话",
|
||
"status": "active",
|
||
"currentUsers": 15,
|
||
"maxUsers": 50
|
||
},
|
||
"users": [
|
||
{
|
||
"userId": "1",
|
||
"username": "testuser",
|
||
"joinedAt": 1641024000000
|
||
}
|
||
],
|
||
"onlineCount": 15,
|
||
"activeMaps": ["map_001", "map_002"]
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
- `404`: 会话不存在
|
||
|
||
---
|
||
|
||
#### 4. 更新会话配置
|
||
|
||
**接口**: `PUT /location-broadcast/sessions/:sessionId/config`
|
||
|
||
**描述**: 更新指定会话的配置参数（需要管理员权限）
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**路径参数**:
|
||
|
||
- `sessionId`: 会话ID
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"maxUsers": 100,
|
||
"allowObservers": false,
|
||
"broadcastRange": 150
|
||
}
|
||
```
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"sessionId": "session_12345",
|
||
"config": {
|
||
"maxUsers": 100,
|
||
"allowObservers": false,
|
||
"broadcastRange": 150
|
||
}
|
||
},
|
||
"message": "会话配置更新成功"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
- `403`: 权限不足
|
||
- `404`: 会话不存在
|
||
|
||
---
|
||
|
||
#### 5. 结束会话
|
||
|
||
**接口**: `DELETE /location-broadcast/sessions/:sessionId`
|
||
|
||
**描述**: 结束指定的游戏会话（需要管理员权限）
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**路径参数**:
|
||
|
||
- `sessionId`: 会话ID
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "会话结束成功"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
- `403`: 权限不足
|
||
- `404`: 会话不存在
|
||
|
||
---
|
||
|
||
#### 6. 查询位置信息
|
||
|
||
**接口**: `GET /location-broadcast/positions`
|
||
|
||
**描述**: 根据条件查询用户位置信息
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**查询参数**:
|
||
|
||
- `userIds` (可选): 用户ID列表（逗号分隔）
|
||
- `mapId` (可选): 地图ID
|
||
- `sessionId` (可选): 会话ID
|
||
- `centerX` (可选): 范围查询中心X坐标
|
||
- `centerY` (可选): 范围查询中心Y坐标
|
||
- `radius` (可选): 范围查询半径
|
||
- `offset` (可选): 分页偏移
|
||
- `limit` (可选): 分页大小
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"positions": [
|
||
{
|
||
"userId": "1",
|
||
"username": "testuser",
|
||
"mapId": "map_001",
|
||
"x": 100,
|
||
"y": 200,
|
||
"timestamp": 1641024000000
|
||
}
|
||
],
|
||
"total": 20,
|
||
"timestamp": 1641024000000
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 7. 获取位置统计信息
|
||
|
||
**接口**: `GET /location-broadcast/positions/stats`
|
||
|
||
**描述**: 获取位置数据的统计信息，包括用户分布、活跃地图等
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**查询参数**:
|
||
|
||
- `mapId` (可选): 地图ID
|
||
- `sessionId` (可选): 会话ID
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"totalUsers": 100,
|
||
"onlineUsers": 85,
|
||
"activeMaps": 5,
|
||
"mapDistribution": {
|
||
"map_001": 35,
|
||
"map_002": 28,
|
||
"map_003": 22
|
||
},
|
||
"updateFrequency": 2.5,
|
||
"timestamp": 1641024000000
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 8. 获取用户位置历史
|
||
|
||
**接口**: `GET /location-broadcast/users/:userId/position-history`
|
||
|
||
**描述**: 获取指定用户的位置历史记录
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**路径参数**:
|
||
|
||
- `userId`: 用户ID
|
||
|
||
**查询参数**:
|
||
|
||
- `mapId` (可选): 地图ID过滤
|
||
- `limit` (可选): 最大记录数
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"userId": "1",
|
||
"mapId": "map_001",
|
||
"x": 100,
|
||
"y": 200,
|
||
"timestamp": 1641024000000
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
- `403`: 权限不足（只能查看自己的历史记录）
|
||
|
||
---
|
||
|
||
#### 9. 清理用户数据
|
||
|
||
**接口**: `DELETE /location-broadcast/users/:userId/data`
|
||
|
||
**描述**: 清理指定用户的位置广播相关数据（需要管理员权限）
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**路径参数**:
|
||
|
||
- `userId`: 用户ID
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "用户数据清理成功"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
- `403`: 权限不足
|
||
|
||
|
||
---
|
||
|
||
### 通知系统
|
||
|
||
#### 1. 创建通知
|
||
|
||
**接口**: `POST /api/notices`
|
||
|
||
**描述**: 创建新的通知消息
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"title": "系统通知",
|
||
"content": "这是一条系统通知消息",
|
||
"userId": 1,
|
||
"type": "system"
|
||
}
|
||
```
|
||
|
||
**成功响应 (201)**:
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"title": "系统通知",
|
||
"content": "这是一条系统通知消息",
|
||
"userId": 1,
|
||
"type": "system",
|
||
"isRead": false,
|
||
"createdAt": "2026-01-20T10:00:00.000Z"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 2. 获取通知列表
|
||
|
||
**接口**: `GET /api/notices`
|
||
|
||
**描述**: 获取当前用户的通知列表
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**查询参数**:
|
||
|
||
- `all` (可选): 管理员可设置为 `true` 获取所有通知
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": 1,
|
||
"title": "系统通知",
|
||
"content": "这是一条系统通知消息",
|
||
"userId": 1,
|
||
"type": "system",
|
||
"isRead": false,
|
||
"createdAt": "2026-01-20T10:00:00.000Z"
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
#### 3. 获取未读通知数量
|
||
|
||
**接口**: `GET /api/notices/unread-count`
|
||
|
||
**描述**: 获取当前用户的未读通知数量
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"count": 5
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 4. 获取通知详情
|
||
|
||
**接口**: `GET /api/notices/:id`
|
||
|
||
**描述**: 获取指定通知的详细信息
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**路径参数**:
|
||
|
||
- `id`: 通知ID
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"title": "系统通知",
|
||
"content": "这是一条系统通知消息",
|
||
"userId": 1,
|
||
"type": "system",
|
||
"isRead": false,
|
||
"createdAt": "2026-01-20T10:00:00.000Z"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 5. 标记通知为已读
|
||
|
||
**接口**: `PATCH /api/notices/:id/read`
|
||
|
||
**描述**: 将指定通知标记为已读
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**路径参数**:
|
||
|
||
- `id`: 通知ID
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"title": "系统通知",
|
||
"content": "这是一条系统通知消息",
|
||
"userId": 1,
|
||
"type": "system",
|
||
"isRead": true,
|
||
"createdAt": "2026-01-20T10:00:00.000Z"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 6. 发送系统通知
|
||
|
||
**接口**: `POST /api/notices/system`
|
||
|
||
**描述**: 发送系统通知给指定用户或所有用户
|
||
|
||
**认证**: 需要 JWT Token（管理员）
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"title": "系统维护通知",
|
||
"content": "系统将于今晚22:00进行维护",
|
||
"userId": 1
|
||
}
|
||
```
|
||
|
||
**成功响应 (201)**:
|
||
|
||
```json
|
||
{
|
||
"id": 2,
|
||
"title": "系统维护通知",
|
||
"content": "系统将于今晚22:00进行维护",
|
||
"userId": 1,
|
||
"type": "system",
|
||
"isRead": false,
|
||
"createdAt": "2026-01-20T10:00:00.000Z"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 7. 发送广播通知
|
||
|
||
**接口**: `POST /api/notices/broadcast`
|
||
|
||
**描述**: 向所有用户发送广播通知
|
||
|
||
**认证**: 需要 JWT Token（管理员）
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"title": "重要公告",
|
||
"content": "新版本即将上线，敬请期待！"
|
||
}
|
||
```
|
||
|
||
**成功响应 (201)**:
|
||
|
||
```json
|
||
{
|
||
"id": 3,
|
||
"title": "重要公告",
|
||
"content": "新版本即将上线，敬请期待！",
|
||
"type": "broadcast",
|
||
"isRead": false,
|
||
"createdAt": "2026-01-20T10:00:00.000Z"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### Zulip集成
|
||
|
||
#### 1. 创建Zulip账号关联
|
||
|
||
**接口**: `POST /zulip-accounts`
|
||
|
||
**描述**: 为游戏用户创建与Zulip账号的关联关系
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"gameUserId": "12345",
|
||
"zulipUserId": 67890,
|
||
"zulipEmail": "user@example.com",
|
||
"zulipFullName": "Test User",
|
||
"status": "active"
|
||
}
|
||
```
|
||
|
||
**成功响应 (201)**:
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"gameUserId": "12345",
|
||
"zulipUserId": 67890,
|
||
"zulipEmail": "user@example.com",
|
||
"zulipFullName": "Test User",
|
||
"status": "active",
|
||
"createdAt": "2026-01-20T10:00:00.000Z",
|
||
"updatedAt": "2026-01-20T10:00:00.000Z"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
- `400`: 请求参数错误
|
||
- `409`: 关联已存在
|
||
|
||
---
|
||
|
||
#### 2. 查询Zulip账号关联列表
|
||
|
||
**接口**: `GET /zulip-accounts`
|
||
|
||
**描述**: 根据条件查询Zulip账号关联列表
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**查询参数**:
|
||
|
||
- `gameUserId` (可选): 游戏用户ID
|
||
- `zulipUserId` (可选): Zulip用户ID
|
||
- `zulipEmail` (可选): Zulip邮箱地址
|
||
- `status` (可选): 账号状态
|
||
- `limit` (可选): 返回数量
|
||
- `offset` (可选): 偏移量
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"gameUserId": "12345",
|
||
"zulipUserId": 67890,
|
||
"zulipEmail": "user@example.com",
|
||
"zulipFullName": "Test User",
|
||
"status": "active",
|
||
"createdAt": "2026-01-20T10:00:00.000Z"
|
||
}
|
||
],
|
||
"total": 1,
|
||
"limit": 10,
|
||
"offset": 0
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 3. 根据ID获取Zulip账号关联
|
||
|
||
**接口**: `GET /zulip-accounts/:id`
|
||
|
||
**描述**: 根据关联ID获取Zulip账号关联详情
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**路径参数**:
|
||
|
||
- `id`: 关联ID
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"gameUserId": "12345",
|
||
"zulipUserId": 67890,
|
||
"zulipEmail": "user@example.com",
|
||
"zulipFullName": "Test User",
|
||
"status": "active",
|
||
"createdAt": "2026-01-20T10:00:00.000Z",
|
||
"updatedAt": "2026-01-20T10:00:00.000Z"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
- `404`: 关联不存在
|
||
|
||
---
|
||
|
||
#### 4. 根据游戏用户ID获取关联
|
||
|
||
**接口**: `GET /zulip-accounts/game-user/:gameUserId`
|
||
|
||
**描述**: 根据游戏用户ID获取Zulip账号关联
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**路径参数**:
|
||
|
||
- `gameUserId`: 游戏用户ID
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"gameUserId": "12345",
|
||
"zulipUserId": 67890,
|
||
"zulipEmail": "user@example.com",
|
||
"zulipFullName": "Test User",
|
||
"status": "active"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 5. 根据Zulip用户ID获取关联
|
||
|
||
**接口**: `GET /zulip-accounts/zulip-user/:zulipUserId`
|
||
|
||
**描述**: 根据Zulip用户ID获取账号关联
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**路径参数**:
|
||
|
||
- `zulipUserId`: Zulip用户ID
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"gameUserId": "12345",
|
||
"zulipUserId": 67890,
|
||
"zulipEmail": "user@example.com",
|
||
"zulipFullName": "Test User",
|
||
"status": "active"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 6. 根据Zulip邮箱获取关联
|
||
|
||
**接口**: `GET /zulip-accounts/zulip-email/:zulipEmail`
|
||
|
||
**描述**: 根据Zulip邮箱获取账号关联
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**路径参数**:
|
||
|
||
- `zulipEmail`: Zulip邮箱地址
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"gameUserId": "12345",
|
||
"zulipUserId": 67890,
|
||
"zulipEmail": "user@example.com",
|
||
"zulipFullName": "Test User",
|
||
"status": "active"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 7. 更新Zulip账号关联
|
||
|
||
**接口**: `PUT /zulip-accounts/:id`
|
||
|
||
**描述**: 更新指定的Zulip账号关联信息
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**路径参数**:
|
||
|
||
- `id`: 关联ID
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"zulipFullName": "Updated Name",
|
||
"status": "inactive"
|
||
}
|
||
```
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"gameUserId": "12345",
|
||
"zulipUserId": 67890,
|
||
"zulipEmail": "user@example.com",
|
||
"zulipFullName": "Updated Name",
|
||
"status": "inactive",
|
||
"updatedAt": "2026-01-20T10:00:00.000Z"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 8. 根据游戏用户ID更新关联
|
||
|
||
**接口**: `PUT /zulip-accounts/game-user/:gameUserId`
|
||
|
||
**描述**: 根据游戏用户ID更新Zulip账号关联
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**路径参数**:
|
||
|
||
- `gameUserId`: 游戏用户ID
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"zulipFullName": "Updated Name",
|
||
"status": "active"
|
||
}
|
||
```
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"gameUserId": "12345",
|
||
"zulipUserId": 67890,
|
||
"zulipEmail": "user@example.com",
|
||
"zulipFullName": "Updated Name",
|
||
"status": "active",
|
||
"updatedAt": "2026-01-20T10:00:00.000Z"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 9. 删除Zulip账号关联
|
||
|
||
**接口**: `DELETE /zulip-accounts/:id`
|
||
|
||
**描述**: 删除指定的Zulip账号关联
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**路径参数**:
|
||
|
||
- `id`: 关联ID
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "Zulip账号关联删除成功"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 10. 根据游戏用户ID删除关联
|
||
|
||
**接口**: `DELETE /zulip-accounts/game-user/:gameUserId`
|
||
|
||
**描述**: 根据游戏用户ID删除Zulip账号关联
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**路径参数**:
|
||
|
||
- `gameUserId`: 游戏用户ID
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "Zulip账号关联删除成功"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 11. 获取需要验证的账号列表
|
||
|
||
**接口**: `GET /zulip-accounts/management/verification-needed`
|
||
|
||
**描述**: 获取需要验证的Zulip账号列表
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"gameUserId": "12345",
|
||
"zulipEmail": "user@example.com",
|
||
"status": "pending_verification"
|
||
}
|
||
],
|
||
"total": 1
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 12. 获取错误状态的账号列表
|
||
|
||
**接口**: `GET /zulip-accounts/management/error-accounts`
|
||
|
||
**描述**: 获取处于错误状态的Zulip账号列表
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"data": [
|
||
{
|
||
"id": 2,
|
||
"gameUserId": "67890",
|
||
"zulipEmail": "error@example.com",
|
||
"status": "error",
|
||
"errorMessage": "连接失败"
|
||
}
|
||
],
|
||
"total": 1
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 13. 批量更新账号状态
|
||
|
||
**接口**: `PUT /zulip-accounts/management/batch-status`
|
||
|
||
**描述**: 批量更新Zulip账号的状态
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"accountIds": [1, 2, 3],
|
||
"status": "active"
|
||
}
|
||
```
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"updated": 3,
|
||
"message": "批量更新成功"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 14. 获取账号状态统计
|
||
|
||
**接口**: `GET /zulip-accounts/management/statistics`
|
||
|
||
**描述**: 获取Zulip账号的状态统计信息
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"total": 100,
|
||
"active": 85,
|
||
"inactive": 10,
|
||
"pending_verification": 3,
|
||
"error": 2
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 15. 验证账号有效性
|
||
|
||
**接口**: `POST /zulip-accounts/management/verify`
|
||
|
||
**描述**: 验证Zulip账号的有效性
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"accountId": 1
|
||
}
|
||
```
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"valid": true,
|
||
"message": "账号验证成功"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 16. 检查邮箱是否已存在
|
||
|
||
**接口**: `GET /zulip-accounts/validation/email-exists/:email`
|
||
|
||
**描述**: 检查指定邮箱是否已在Zulip中存在
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**路径参数**:
|
||
|
||
- `email`: 邮箱地址
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"exists": true,
|
||
"accountId": 1
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 17. 检查Zulip用户ID是否已存在
|
||
|
||
**接口**: `GET /zulip-accounts/validation/zulip-user-exists/:zulipUserId`
|
||
|
||
**描述**: 检查指定Zulip用户ID是否已关联
|
||
|
||
**认证**: 需要 JWT Token
|
||
|
||
**路径参数**:
|
||
|
||
- `zulipUserId`: Zulip用户ID
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"exists": true,
|
||
"accountId": 1
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 数据库管理
|
||
|
||
#### 1. 获取用户列表
|
||
|
||
**接口**: `GET /admin/database/users`
|
||
|
||
**描述**: 分页获取用户列表（管理员专用）
|
||
|
||
**认证**: 需要管理员 Token
|
||
|
||
**查询参数**:
|
||
|
||
- `limit` (可选): 返回数量，默认20，最大100
|
||
- `offset` (可选): 偏移量，默认0
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"id": "1",
|
||
"username": "testuser",
|
||
"nickname": "测试用户",
|
||
"email": "test@example.com",
|
||
"role": 1,
|
||
"status": "active",
|
||
"created_at": "2026-01-20T10:00:00.000Z"
|
||
}
|
||
],
|
||
"total": 100,
|
||
"limit": 20,
|
||
"offset": 0
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 2. 获取用户详情
|
||
|
||
**接口**: `GET /admin/database/users/:id`
|
||
|
||
**描述**: 根据用户ID获取详细的用户信息
|
||
|
||
**认证**: 需要管理员 Token
|
||
|
||
**路径参数**:
|
||
|
||
- `id`: 用户ID
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"id": "1",
|
||
"username": "testuser",
|
||
"nickname": "测试用户",
|
||
"email": "test@example.com",
|
||
"phone": null,
|
||
"role": 1,
|
||
"status": "active",
|
||
"email_verified": true,
|
||
"created_at": "2026-01-20T10:00:00.000Z",
|
||
"updated_at": "2026-01-20T10:00:00.000Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 3. 搜索用户
|
||
|
||
**接口**: `GET /admin/database/users/search`
|
||
|
||
**描述**: 根据关键词搜索用户，支持用户名、邮箱、昵称模糊匹配
|
||
|
||
**认证**: 需要管理员 Token
|
||
|
||
**查询参数**:
|
||
|
||
- `keyword`: 搜索关键词
|
||
- `limit` (可选): 返回数量，默认20，最大50
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"id": "1",
|
||
"username": "testuser",
|
||
"nickname": "测试用户",
|
||
"email": "test@example.com"
|
||
}
|
||
],
|
||
"total": 5
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 4. 创建用户
|
||
|
||
**接口**: `POST /admin/database/users`
|
||
|
||
**描述**: 创建新用户（管理员专用）
|
||
|
||
**认证**: 需要管理员 Token
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"username": "newuser",
|
||
"password": "password123",
|
||
"nickname": "新用户",
|
||
"email": "newuser@example.com",
|
||
"role": 1
|
||
}
|
||
```
|
||
|
||
**成功响应 (201)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"id": "2",
|
||
"username": "newuser",
|
||
"nickname": "新用户",
|
||
"email": "newuser@example.com",
|
||
"role": 1,
|
||
"created_at": "2026-01-20T10:00:00.000Z"
|
||
},
|
||
"message": "用户创建成功"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
- `400`: 请求参数错误
|
||
- `409`: 用户名或邮箱已存在
|
||
|
||
---
|
||
|
||
#### 5. 更新用户
|
||
|
||
**接口**: `PUT /admin/database/users/:id`
|
||
|
||
**描述**: 根据用户ID更新用户信息
|
||
|
||
**认证**: 需要管理员 Token
|
||
|
||
**路径参数**:
|
||
|
||
- `id`: 用户ID
|
||
|
||
**请求体**:
|
||
|
||
```json
|
||
{
|
||
"nickname": "更新后的昵称",
|
||
"email": "newemail@example.com",
|
||
"status": "active"
|
||
}
|
||
```
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"id": "1",
|
||
"username": "testuser",
|
||
"nickname": "更新后的昵称",
|
||
"email": "newemail@example.com",
|
||
"status": "active",
|
||
"updated_at": "2026-01-20T10:00:00.000Z"
|
||
},
|
||
"message": "用户更新成功"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
- `404`: 用户不存在
|
||
|
||
---
|
||
|
||
#### 6. 删除用户
|
||
|
||
**接口**: `DELETE /admin/database/users/:id`
|
||
|
||
**描述**: 根据用户ID删除用户（软删除）
|
||
|
||
**认证**: 需要管理员 Token
|
||
|
||
**路径参数**:
|
||
|
||
- `id`: 用户ID
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "用户删除成功"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
- `404`: 用户不存在
|
||
|
||
---
|
||
|
||
### 操作日志
|
||
|
||
#### 1. 获取操作日志列表
|
||
|
||
**接口**: `GET /admin/operation-logs`
|
||
|
||
**描述**: 分页获取管理员操作日志，支持多种过滤条件
|
||
|
||
**认证**: 需要管理员 Token
|
||
|
||
**查询参数**:
|
||
|
||
- `limit` (可选): 返回数量，默认50，最大200
|
||
- `offset` (可选): 偏移量，默认0
|
||
- `adminUserId` (可选): 管理员用户ID过滤
|
||
- `operationType` (可选): 操作类型过滤（CREATE, UPDATE, DELETE, QUERY）
|
||
- `targetType` (可选): 目标类型过滤（users, admin_logs等）
|
||
- `operationResult` (可选): 操作结果过滤（SUCCESS, FAILURE）
|
||
- `startDate` (可选): 开始日期（ISO格式）
|
||
- `endDate` (可选): 结束日期（ISO格式）
|
||
- `isSensitive` (可选): 是否敏感操作
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"id": "log_123",
|
||
"adminUserId": "1",
|
||
"operationType": "CREATE",
|
||
"targetType": "users",
|
||
"targetId": "2",
|
||
"operationResult": "SUCCESS",
|
||
"description": "创建用户",
|
||
"isSensitive": true,
|
||
"createdAt": "2026-01-20T10:00:00.000Z"
|
||
}
|
||
],
|
||
"total": 100,
|
||
"limit": 50,
|
||
"offset": 0
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 2. 获取操作日志详情
|
||
|
||
**接口**: `GET /admin/operation-logs/:id`
|
||
|
||
**描述**: 根据日志ID获取操作日志的详细信息
|
||
|
||
**认证**: 需要管理员 Token
|
||
|
||
**路径参数**:
|
||
|
||
- `id`: 日志ID
|
||
|
||
**成功响应 (200)**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"id": "log_123",
|
||
"adminUserId": "1",
|
||
"operationType": "CREATE",
|
||
"targetType": "users",
|
||
"targetId": "2",
|
||
"operationResult": "SUCCESS",
|
||
"description": "创建用户",
|
||
"isSensitive": true,
|
||
"metadata": {
|
||
"username": "newuser",
|
||
"email": "newuser@example.com"
|
||
},
|
||
"createdAt": "2026-01-20T10:00:00.000Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
|
||
- `404`: 日志不存在
|
||
|
||
---
|
||
|
||
## 📊 版本更新记录
|
||
|
||
### v2.0.0 (2026-01-20)
|
||
- **架构升级**: 完整的四层架构实现（Gateway、Business、Core、Database）
|
||
- **新增功能**: 位置广播系统、通知系统、Zulip集成
|
||
- **数据库管理**: 完整的管理员数据库管理接口
|
||
- **操作日志**: 管理员操作审计日志系统
|
||
- **Token刷新**: 支持刷新令牌机制
|
||
- **WebSocket**: 完整的实时通信支持
|
||
|
||
### v1.1.2 (2025-12-25)
|
||
- **验证码冷却优化**: 注册、密码重置、验证码登录成功后自动清除验证码冷却时间
|
||
- **用户体验提升**: 成功操作后可立即发送新的验证码
|
||
|
||
### v1.1.1 (2025-12-25)
|
||
- **邮箱冲突检测优化**: 发送邮箱验证码前检查邮箱是否已被注册
|
||
- **错误处理改进**: 返回409 Conflict状态码和明确错误信息
|
||
|
||
### v1.1.0 (2025-12-25)
|
||
- **新增验证码登录功能**: 支持邮箱验证码登录
|
||
- **HTTP状态码修复**: 所有接口返回正确的业务状态码
|
||
- **完善错误处理**: 统一错误响应格式和错误代码
|
||
|
||
---
|
||
|
||
## 🔗 相关资源
|
||
|
||
- [OpenAPI 规范文件](./openapi.yaml)
|
||
- [Postman 测试集合](./postman-collection.json)
|
||
- [项目架构文档](../ARCHITECTURE.md)
|
||
- [开发规范指南](../development/)
|
||
- [WebSocket 文档](./websocket-api.md)
|
||
|
||
---
|
||
|
||
## 📝 注意事项
|
||
|
||
1. **认证机制**: 大部分接口需要 JWT Token 认证
|
||
2. **频率限制**: 已实现 API 频率限制，请注意请求频率
|
||
3. **测试模式**: 开发环境下邮件服务返回206状态码，验证码在响应中返回
|
||
4. **WebSocket**: 实时功能（聊天、位置广播）推荐使用 WebSocket 接口
|
||
5. **管理员权限**: 管理员接口需要 role=9 的账户权限
|
||
6. **数据格式**: 所有日期时间使用 ISO 8601 格式
|
||
7. **错误处理**: 根据 HTTP 状态码和 error_code 进行错误处理
|
||
|
||
---
|
||
|
||
**文档维护**: 本文档根据后端代码自动生成，如有疑问请参考源代码或联系开发团队。
|