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

refactor(auth): 优化注册流程中Zulip账号创建为异步处理

Browse Source 
- 注册时Zulip账号创建改为异步，不阻塞注册流程
- 新增带3次重试和递增延迟的createZulipAccountWithRetry方法
- Zulip失败只记录日志，不影响用户注册成功
- 更新API文档，补充80+接口覆盖聊天/通知/位置等模块
- 添加.claude/和test-*.ps1到.gitignore

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
moyin
2026-03-09 11:04:57 +08:00
parent fc1566e616
commit 8ef45f53f1
5 changed files with 2498 additions and 587 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
docs/api/README.md
View File

@@ -1,12 +1,12 @@
# API接口文档
本目录包含了 Whale Town 像素游戏服务器的完整API文档，采用业务功能模块化设计，提供17个接口覆盖所有核心功能。
本目录包含了 Whale Town 像素游戏服务器的完整API文档，采用业务功能模块化设计，提供80+个接口覆盖所有核心功能。
## 📋 文档文件说明
### 1. api-documentation.md
详细的API接口文档，包含：
- **17个API接口** - 用户认证、用户管理、管理员功能、安全防护
- **80+个API接口** - 用户认证、用户管理、管理员功能、聊天系统、位置广播、通知系统、Zulip集成、数据库管理、操作日志
- 接口概述和通用响应格式
- 每个接口的详细说明、参数、响应示例
- 错误代码说明和状态码映射
@@ -65,18 +65,21 @@ openapi-generator generate -i docs/api/openapi.yaml -g typescript-axios -o ./cli
## 📊 API接口概览
### 🔐 用户认证模块 (9个接口)
### 🔐 用户认证模块 (12个接口)
| 接口 | 方法 | 路径 | 描述 |
|------|------|------|------|
| 用户登录 | POST | /auth/login | 支持用户名、邮箱或手机号登录 |
| 用户注册 | POST | /auth/register | 创建新用户账户 |
| GitHub OAuth | POST | /auth/github | 使用GitHub账户登录或注册 |
| 发送重置验证码 | POST | /auth/forgot-password | 发送密码重置验证码 |
| 重置密码 | POST | /auth/reset-password | 使用验证码重置密码 |
| 修改密码 | PUT | /auth/change-password | 修改用户密码 |
| 验证码登录 | POST | /auth/verification-code-login | 使用验证码登录 |
| 发送登录验证码 | POST | /auth/send-login-verification-code | 发送登录验证码 |
| 发送邮箱验证码 | POST | /auth/send-email-verification | 发送邮箱验证码 |
| 验证邮箱 | POST | /auth/verify-email | 验证邮箱验证码 |
| 重发邮箱验证码 | POST | /auth/resend-email-verification | 重新发送邮箱验证码 |
| 发送重置验证码 | POST | /auth/forgot-password | 发送密码重置验证码 |
| 重置密码 | POST | /auth/reset-password | 使用验证码重置密码 |
| 修改密码 | PUT | /auth/change-password | 修改用户密码 |
| 刷新令牌 | POST | /auth/refresh-token | 刷新访问令牌 |
### 👥 用户管理模块 (3个接口)
| 接口 | 方法 | 路径 | 描述 |
@@ -85,13 +88,83 @@ openapi-generator generate -i docs/api/openapi.yaml -g typescript-axios -o ./cli
| 批量修改状态 | POST | /admin/users/batch-status | 批量修改用户状态 |
| 用户状态统计 | GET | /admin/users/status-stats | 获取各状态用户统计 |
### 🛡️ 管理员模块 (4个接口)
### 🛡️ 管理员模块 (6个接口)
| 接口 | 方法 | 路径 | 描述 |
|------|------|------|------|
| 管理员登录 | POST | /admin/auth/login | 管理员身份认证 |
| 获取用户列表 | GET | /admin/users | 分页获取用户列表 |
| 获取用户详情 | GET | /admin/users/:id | 获取指定用户信息 |
| 重置用户密码 | POST | /admin/users/:id/reset-password | 管理员重置用户密码 |
| 获取运行时日志 | GET | /admin/logs/runtime | 获取运行日志 |
| 下载日志归档 | GET | /admin/logs/archive | 下载全部日志 |
### 💬 聊天系统 (3个接口)
| 接口 | 方法 | 路径 | 描述 |
|------|------|------|------|
| 获取聊天历史 | GET | /chat/history | 获取聊天历史记录 |
| 获取系统状态 | GET | /chat/status | 获取聊天系统状态 |
| WebSocket信息 | GET | /chat/websocket/info | 获取WebSocket连接信息 |
### 📍 位置广播 (9个接口)
| 接口 | 方法 | 路径 | 描述 |
|------|------|------|------|
| 创建会话 | POST | /location-broadcast/sessions | 创建新的游戏会话 |
| 查询会话列表 | GET | /location-broadcast/sessions | 查询游戏会话列表 |
| 获取会话详情 | GET | /location-broadcast/sessions/:sessionId | 获取会话详细信息 |
| 更新会话配置 | PUT | /location-broadcast/sessions/:sessionId/config | 更新会话配置 |
| 结束会话 | DELETE | /location-broadcast/sessions/:sessionId | 结束游戏会话 |
| 查询位置信息 | GET | /location-broadcast/positions | 查询用户位置 |
| 位置统计 | GET | /location-broadcast/positions/stats | 获取位置统计 |
| 位置历史 | GET | /location-broadcast/users/:userId/position-history | 获取位置历史 |
| 清理用户数据 | DELETE | /location-broadcast/users/:userId/data | 清理用户数据 |
### 🔔 通知系统 (7个接口)
| 接口 | 方法 | 路径 | 描述 |
|------|------|------|------|
| 创建通知 | POST | /api/notices | 创建新通知 |
| 获取通知列表 | GET | /api/notices | 获取通知列表 |
| 未读通知数量 | GET | /api/notices/unread-count | 获取未读数量 |
| 获取通知详情 | GET | /api/notices/:id | 获取通知详情 |
| 标记已读 | PATCH | /api/notices/:id/read | 标记为已读 |
| 发送系统通知 | POST | /api/notices/system | 发送系统通知 |
| 发送广播通知 | POST | /api/notices/broadcast | 发送广播通知 |
### 🔗 Zulip集成 (17个接口)
| 接口 | 方法 | 路径 | 描述 |
|------|------|------|------|
| 创建关联 | POST | /zulip-accounts | 创建Zulip账号关联 |
| 查询关联列表 | GET | /zulip-accounts | 查询关联列表 |
| 获取关联详情 | GET | /zulip-accounts/:id | 根据ID获取关联 |
| 根据游戏用户ID获取 | GET | /zulip-accounts/game-user/:gameUserId | 根据游戏用户ID获取 |
| 根据Zulip用户ID获取 | GET | /zulip-accounts/zulip-user/:zulipUserId | 根据Zulip用户ID获取 |
| 根据邮箱获取 | GET | /zulip-accounts/zulip-email/:zulipEmail | 根据邮箱获取 |
| 更新关联 | PUT | /zulip-accounts/:id | 更新关联信息 |
| 根据游戏用户ID更新 | PUT | /zulip-accounts/game-user/:gameUserId | 根据游戏用户ID更新 |
| 删除关联 | DELETE | /zulip-accounts/:id | 删除关联 |
| 根据游戏用户ID删除 | DELETE | /zulip-accounts/game-user/:gameUserId | 根据游戏用户ID删除 |
| 需要验证的账号 | GET | /zulip-accounts/management/verification-needed | 获取需要验证的账号 |
| 错误状态账号 | GET | /zulip-accounts/management/error-accounts | 获取错误状态账号 |
| 批量更新状态 | PUT | /zulip-accounts/management/batch-status | 批量更新状态 |
| 账号统计 | GET | /zulip-accounts/management/statistics | 获取统计信息 |
| 验证账号 | POST | /zulip-accounts/management/verify | 验证账号有效性 |
| 检查邮箱存在 | GET | /zulip-accounts/validation/email-exists/:email | 检查邮箱是否存在 |
| 检查用户ID存在 | GET | /zulip-accounts/validation/zulip-user-exists/:zulipUserId | 检查用户ID是否存在 |
### 🗄️ 数据库管理 (6个接口)
| 接口 | 方法 | 路径 | 描述 |
|------|------|------|------|
| 获取用户列表 | GET | /admin/database/users | 获取用户列表 |
| 获取用户详情 | GET | /admin/database/users/:id | 获取用户详情 |
| 搜索用户 | GET | /admin/database/users/search | 搜索用户 |
| 创建用户 | POST | /admin/database/users | 创建新用户 |
| 更新用户 | PUT | /admin/database/users/:id | 更新用户信息 |
| 删除用户 | DELETE | /admin/database/users/:id | 删除用户 |
### 📝 操作日志 (2个接口)
| 接口 | 方法 | 路径 | 描述 |
|------|------|------|------|
| 获取日志列表 | GET | /admin/operation-logs | 获取操作日志列表 |
| 获取日志详情 | GET | /admin/operation-logs/:id | 获取日志详情 |
### 📊 系统状态 (1个接口)
| 接口 | 方法 | 路径 | 描述 |
@@ -188,6 +261,9 @@ console.log('登录结果:', loginData);
5. **测试模式**: 邮件服务支持测试模式，验证码会在控制台输出
6. **存储模式**: 支持Redis文件存储和内存数据库，便于无依赖测试
7. **安全防护**: 实现了维护模式、内容类型检查、超时控制等安全机制
8. **WebSocket**: 实时功能（聊天、位置广播）推荐使用WebSocket接口
9. **Zulip集成**: 支持与Zulip聊天系统的完整集成
10. **操作审计**: 管理员操作自动记录审计日志
## 🔄 更新文档