diff --git a/README.md b/README.md index 72a21ff..1239342 100644 --- a/README.md +++ b/README.md @@ -155,9 +155,9 @@ WhaleTown/ # 🐋 项目根目录 │ ├── performance/ # ⚡ 性能测试（帧率、内存优化） │ └── api/ # 🌐 API接口测试 └── 🌐 web_assets/ # 🌍 Web导出资源 - ├── html/ # 📄 HTML模板文件 - ├── css/ # 🎨 样式文件 - └── js/ # 📜 JavaScript脚本 + ├── html/ # 📄 HTML模板文件 + ├── css/ # 🎨 样式文件 + └── js/ # 📜 JavaScript脚本 ``` ### 🔧 核心架构说明 diff --git a/claude.md b/claude.md index eb41871..bc67670 100644 --- a/claude.md +++ b/claude.md @@ -66,10 +66,10 @@ ```gdscript extends GutTest func test_event_emission(): - var sender = Node.new() - watch_signals(EventSystem) - EventSystem.emit_event(EventNames.PLAYER_MOVED, {}) - assert_signal_emitted(EventSystem, "event_raised") + var sender = Node.new() + watch_signals(EventSystem) + EventSystem.emit_event(EventNames.PLAYER_MOVED, {}) + assert_signal_emitted(EventSystem, "event_raised") ``` ## 🔄 8. Standard Development Workflow (MANDATORY) @@ -152,13 +152,13 @@ class_name Player # 3. Lifecycle func _physics_process(delta: float) -> void: - _move(delta) + _move(delta) # 4. Private Methods func _move(_delta: float) -> void: - var dir := Input.get_vector("move_left", "move_right", "move_up", "move_down") - velocity = dir * move_speed - move_and_slide() + var dir := Input.get_vector("move_left", "move_right", "move_up", "move_down") + velocity = dir * move_speed + move_and_slide() ``` ## 10. 🔄 Plan Mode Protocol (MANDATORY) - **Planning Phase**: @@ -166,9 +166,9 @@ func _move(_delta: float) -> void: - **Execution & Reporting**: - Every time a TODO item is completed, the corresponding `.md` document MUST be updated. - After updating the document, report to the user with the following: - 1. **Completed Items**: What was just finished. - 2. **User Acceptance Rules**: Instructions on how the user can test/verify the current progress. - 3. **Next Step**: The next TODO item to be tackled. + 1. **Completed Items**: What was just finished. + 2. **User Acceptance Rules**: Instructions on how the user can test/verify the current progress. + 3. **Next Step**: The next TODO item to be tackled. - **Strict Confirmation**: - After reporting progress, **Claude MUST stop and wait**. - Do NOT proceed to the next TODO until the user has replied with confirmation/approval. \ No newline at end of file diff --git a/docs/api-documentation.md b/docs/api-documentation.md new file mode 100644 index 0000000..e18004a --- /dev/null +++ b/docs/api-documentation.md @@ -0,0 +1,2495 @@ +# 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 进行错误处理 + +--- + +**文档维护**: 本文档根据后端代码自动生成，如有疑问请参考源代码或联系开发团队。