Files

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

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

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-03-09 11:04:57 +08:00

4.8 KiB

Raw Blame History

注册流程 Zulip 错误处理优化

修改概述

优化了用户注册流程中的 Zulip 账号创建逻辑，确保 Zulip 服务的问题不会影响用户注册体验。

修改内容

1. 异步处理 Zulip 账号创建

修改前：

Zulip 账号创建是同步的，阻塞注册流程
如果 Zulip 创建失败，会回滚游戏账号
错误信息直接返回给前端用户

修改后：

Zulip 账号创建改为异步处理，不阻塞注册流程
游戏账号创建成功后立即返回，Zulip 在后台处理
用户无感知，注册体验流畅

2. 自动重试机制

新增 createZulipAccountWithRetry() 方法：

最多重试 3 次
递增延迟：1秒、2秒、3秒
每次尝试都记录详细日志
所有重试失败后记录最终错误

3. 错误信息隔离

修改前：

{
  "success": false,
  "message": "注册失败：Zulip账号创建失败 - [具体错误]",
  "error_code": "REGISTER_FAILED"
}

修改后：

{
  "success": true,
  "data": {
    "user": {...},
    "access_token": "...",
    "message": "注册成功"
  }
}

用户永远不会看到 Zulip 相关的错误信息。

4. 日志记录增强

所有 Zulip 相关操作都有详细日志：

// 开始尝试
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 创建和回滚逻辑

// 删除的代码
try {
  await this.createZulipAccountForUser(...);
} catch (zulipError) {
  // 回滚游戏用户注册
  await this.loginCoreService.deleteUser(...);
  throw new Error(`注册失败：Zulip账号创建失败 - ${err.message}`);
}

2. 新增异步处理

// 新增的代码
if (registerRequest.email && registerRequest.password) {
  this.createZulipAccountWithRetry(
    authResult.user,
    registerRequest.password,
    operationId
  ).then(success => {
    // 成功日志
  }).catch(err => {
    // 失败日志（不影响用户）
  });
}

3. 新增重试方法

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：正常注册（无邮箱）

POST /auth/register
{
  "username": "testuser",
  "password": "Test123456",
  "nickname": "测试用户"
}

响应：
{
  "success": true,
  "data": {
    "user": {...},
    "access_token": "...",
    "message": "注册成功"  // ✓ 不包含 Zulip 信息
  }
}

测试场景 2：Zulip 服务不可用

行为：

用户注册成功
后台尝试创建 Zulip 账号
失败后自动重试 3 次
所有失败都记录在服务器日志
用户收到成功响应

日志示例：

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）
✅ 独立的重试逻辑易于调整

注意事项

Zulip 账号创建失败的用户
- 可以正常使用游戏
- 无法使用聊天功能
- 需要开发者手动处理或实现补偿机制
监控建议
- 定期检查 Zulip 创建失败的日志
- 统计失败率，及时发现 Zulip 服务问题
- 考虑实现告警机制
后续优化方向
- 实现定时任务补偿创建失败的 Zulip 账号
- 添加管理员界面查看 Zulip 创建状态
- 提供手动重试接口

修改日期

2026-02-08

修改者

AI Assistant (Kiro)

4.8 KiB Raw Blame History Unescape Escape