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

# 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 进行错误处理

---

**文档维护**: 本文档根据后端代码自动生成，如有疑问请参考源代码或联系开发团队。