# Whale Town 像素游戏服务器 API 文档 **版本**: 2.0.0 **更新时间**: 2026-01-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 ``` ### 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 进行错误处理 --- **文档维护**: 本文档根据后端代码自动生成，如有疑问请参考源代码或联系开发团队。