refactor(auth): 优化注册流程中Zulip账号创建为异步处理
- 注册时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
220
REGISTER_ZULIP_CHANGES.md
Normal file
220
REGISTER_ZULIP_CHANGES.md
Normal file
@@ -0,0 +1,220 @@
|
||||
# 注册流程 Zulip 错误处理优化
|
||||
|
||||
## 修改概述
|
||||
|
||||
优化了用户注册流程中的 Zulip 账号创建逻辑，确保 Zulip 服务的问题不会影响用户注册体验。
|
||||
|
||||
## 修改内容
|
||||
|
||||
### 1. 异步处理 Zulip 账号创建
|
||||
|
||||
**修改前：**
|
||||
- Zulip 账号创建是同步的，阻塞注册流程
|
||||
- 如果 Zulip 创建失败，会回滚游戏账号
|
||||
- 错误信息直接返回给前端用户
|
||||
|
||||
**修改后：**
|
||||
- Zulip 账号创建改为异步处理，不阻塞注册流程
|
||||
- 游戏账号创建成功后立即返回，Zulip 在后台处理
|
||||
- 用户无感知，注册体验流畅
|
||||
|
||||
### 2. 自动重试机制
|
||||
|
||||
新增 `createZulipAccountWithRetry()` 方法：
|
||||
- 最多重试 3 次
|
||||
- 递增延迟：1秒、2秒、3秒
|
||||
- 每次尝试都记录详细日志
|
||||
- 所有重试失败后记录最终错误
|
||||
|
||||
### 3. 错误信息隔离
|
||||
|
||||
**修改前：**
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "注册失败：Zulip账号创建失败 - [具体错误]",
|
||||
"error_code": "REGISTER_FAILED"
|
||||
}
|
||||
```
|
||||
|
||||
**修改后：**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"user": {...},
|
||||
"access_token": "...",
|
||||
"message": "注册成功"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
用户永远不会看到 Zulip 相关的错误信息。
|
||||
|
||||
### 4. 日志记录增强
|
||||
|
||||
所有 Zulip 相关操作都有详细日志：
|
||||
|
||||
```typescript
|
||||
// 开始尝试
|
||||
LOG: 尝试创建Zulip账号 (第1/3次)
|
||||
- operationId: 用于追踪
|
||||
- gameUserId: 游戏用户ID
|
||||
- email: 用户邮箱
|
||||
|
||||
// 失败重试
|
||||
WARN: Zulip账号创建失败 (第1/3次尝试)
|
||||
- error: 具体错误信息
|
||||
- 等待1000ms后重试
|
||||
|
||||
// 最终失败
|
||||
ERROR: Zulip账号创建最终失败，已尝试3次
|
||||
- finalError: 最后一次错误
|
||||
- note: 用户注册已成功，但Zulip账号创建失败
|
||||
```
|
||||
|
||||
## 代码变更
|
||||
|
||||
### 文件：`src/business/auth/register.service.ts`
|
||||
|
||||
#### 1. 移除同步 Zulip 创建和回滚逻辑
|
||||
|
||||
```typescript
|
||||
// 删除的代码
|
||||
try {
|
||||
await this.createZulipAccountForUser(...);
|
||||
} catch (zulipError) {
|
||||
// 回滚游戏用户注册
|
||||
await this.loginCoreService.deleteUser(...);
|
||||
throw new Error(`注册失败：Zulip账号创建失败 - ${err.message}`);
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. 新增异步处理
|
||||
|
||||
```typescript
|
||||
// 新增的代码
|
||||
if (registerRequest.email && registerRequest.password) {
|
||||
this.createZulipAccountWithRetry(
|
||||
authResult.user,
|
||||
registerRequest.password,
|
||||
operationId
|
||||
).then(success => {
|
||||
// 成功日志
|
||||
}).catch(err => {
|
||||
// 失败日志（不影响用户）
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. 新增重试方法
|
||||
|
||||
```typescript
|
||||
private async createZulipAccountWithRetry(
|
||||
gameUser: Users,
|
||||
password: string,
|
||||
operationId: string,
|
||||
maxRetries: number = 3
|
||||
): Promise<boolean> {
|
||||
// 重试逻辑
|
||||
for (let attempt = 1; attempt <= maxRetries; attempt++) {
|
||||
try {
|
||||
await this.createZulipAccountForUser(gameUser, password);
|
||||
return true;
|
||||
} catch (error) {
|
||||
// 记录日志并重试
|
||||
if (attempt < maxRetries) {
|
||||
await this.delay(attempt * 1000);
|
||||
}
|
||||
}
|
||||
}
|
||||
return false;
|
||||
}
|
||||
```
|
||||
|
||||
## 测试验证
|
||||
|
||||
### 测试场景 1：正常注册（无邮箱）
|
||||
|
||||
```bash
|
||||
POST /auth/register
|
||||
{
|
||||
"username": "testuser",
|
||||
"password": "Test123456",
|
||||
"nickname": "测试用户"
|
||||
}
|
||||
|
||||
响应：
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"user": {...},
|
||||
"access_token": "...",
|
||||
"message": "注册成功" // ✓ 不包含 Zulip 信息
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 测试场景 2：Zulip 服务不可用
|
||||
|
||||
**行为：**
|
||||
1. 用户注册成功
|
||||
2. 后台尝试创建 Zulip 账号
|
||||
3. 失败后自动重试 3 次
|
||||
4. 所有失败都记录在服务器日志
|
||||
5. 用户收到成功响应
|
||||
|
||||
**日志示例：**
|
||||
```
|
||||
LOG: 尝试创建Zulip账号 (第1/3次)
|
||||
WARN: Zulip账号创建失败 (第1/3次尝试)
|
||||
LOG: 等待1000ms后重试
|
||||
LOG: 尝试创建Zulip账号 (第2/3次)
|
||||
WARN: Zulip账号创建失败 (第2/3次尝试)
|
||||
LOG: 等待2000ms后重试
|
||||
LOG: 尝试创建Zulip账号 (第3/3次)
|
||||
WARN: Zulip账号创建失败 (第3/3次尝试)
|
||||
ERROR: Zulip账号创建最终失败，已尝试3次
|
||||
```
|
||||
|
||||
## 优势
|
||||
|
||||
### 1. 用户体验
|
||||
- ✅ 注册流程不受 Zulip 服务影响
|
||||
- ✅ 响应速度快（不等待 Zulip）
|
||||
- ✅ 错误信息友好（不暴露技术细节）
|
||||
|
||||
### 2. 系统稳定性
|
||||
- ✅ Zulip 故障不影响核心注册功能
|
||||
- ✅ 自动重试提高成功率
|
||||
- ✅ 降级处理保证服务可用性
|
||||
|
||||
### 3. 可维护性
|
||||
- ✅ 详细的日志便于问题排查
|
||||
- ✅ 清晰的错误追踪（operationId）
|
||||
- ✅ 独立的重试逻辑易于调整
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **Zulip 账号创建失败的用户**
|
||||
- 可以正常使用游戏
|
||||
- 无法使用聊天功能
|
||||
- 需要开发者手动处理或实现补偿机制
|
||||
|
||||
2. **监控建议**
|
||||
- 定期检查 Zulip 创建失败的日志
|
||||
- 统计失败率，及时发现 Zulip 服务问题
|
||||
- 考虑实现告警机制
|
||||
|
||||
3. **后续优化方向**
|
||||
- 实现定时任务补偿创建失败的 Zulip 账号
|
||||
- 添加管理员界面查看 Zulip 创建状态
|
||||
- 提供手动重试接口
|
||||
|
||||
## 修改日期
|
||||
|
||||
2026-02-08
|
||||
|
||||
## 修改者
|
||||
|
||||
AI Assistant (Kiro)
|
||||
Reference in New Issue
Block a user