ANGJustinl/whale-town-end
1
0
Fork 0
forked from datawhale/whale-town-end
Code Pull Requests Activity

refactor(auth): 移除Controller，专注于业务逻辑层

Browse Source 
范围：src/business/auth/
涉及文件：
- src/business/auth/auth.module.ts
- src/business/auth/README.md

主要改进：
- 移除LoginController和RegisterController的导入和声明
- 调整模块结构，专注于业务逻辑层
- 更新README文档，明确Business Layer职责定位
- 完善依赖关系说明和架构层级描述
- 版本号从1.0.2升级到2.0.0（架构重构）
This commit is contained in:
moyin
2026-01-14 12:00:19 +08:00
parent efbc5c4084
commit f7c3983cc1
2 changed files with 302 additions and 207 deletions
Download Patch File Download Diff File Expand all files Collapse all files

468
src/business/auth/README.md
View File

@@ -1,246 +1,330 @@
<!--
Auth 用户认证业务模块文档
# 认证业务模块 (Auth Business Module)
功能描述：
- 提供完整的用户认证业务模块文档
- 详细说明登录、注册、密码管理等功能
- 包含API接口、组件说明和使用指南
- 提供架构设计和安全特性说明
## 架构层级
职责分离：
- 专注于业务模块的功能文档编写
- 提供开发者参考和使用指南
- 说明模块的设计理念和最佳实践
**Business Layer（业务层）**
最近修改：
- 2026-01-12: 代码规范优化 - 添加文档头注释，完善注释规范 (修改者: moyin)
## 职责定位
@author moyin
@version 1.0.1
@since 2025-12-17
@lastModified 2026-01-12
-->
业务层负责实现核心业务逻辑和流程控制：
# Auth 用户认证业务模块
1. **业务流程**：实现完整的业务流程和规则
2. **服务协调**：协调多个核心服务完成业务功能
3. **数据转换**：将核心层数据转换为业务数据
4. **业务验证**：实现业务规则验证
5. **事务管理**：处理跨服务的事务逻辑
Auth 是应用的核心用户认证业务模块，提供完整的用户登录、注册、密码管理、JWT令牌认证和GitHub OAuth集成功能，支持邮箱验证、验证码登录、安全防护和Zulip账号同步，具备完善的业务流程控制、错误处理和安全审计能力。
## 模块组成
## 用户认证功能
```
src/business/auth/
├── login.service.ts # 登录业务服务
├── register.service.ts # 注册业务服务
├── auth.module.ts # 业务模块配置
└── README.md # 模块文档
```
### login()
处理用户登录请求，支持用户名/邮箱/手机号登录，验证用户凭据并生成JWT令牌。
## 对外提供的接口
### register()
处理用户注册请求，支持邮箱验证，自动创建Zulip账号并建立关联。
### LoginService
### githubOAuth()
处理GitHub OAuth登录，支持新用户自动注册和现有用户绑定。
#### login(loginRequest: LoginRequest): Promise<ApiResponse<LoginResponse>>
处理用户登录请求，验证用户凭据并生成JWT令牌，支持Zulip账号验证和更新。
### verificationCodeLogin()
支持邮箱或手机号验证码登录，提供无密码登录方式。
#### githubOAuth(oauthRequest: GitHubOAuthRequest): Promise<ApiResponse<LoginResponse>>
使用GitHub账户登录或注册，自动创建用户账号并生成JWT令牌。
## 密码管理功能
#### verificationCodeLogin(loginRequest: VerificationCodeLoginRequest): Promise<ApiResponse<LoginResponse>>
使用邮箱或手机号和验证码进行登录，无需密码即可完成认证。
### sendPasswordResetCode()
发送密码重置验证码到用户邮箱或手机号，支持测试模式和真实发送模式。
#### sendPasswordResetCode(identifier: string): Promise<ApiResponse<{verification_code?: string; is_test_mode?: boolean}>>
向用户邮箱或手机发送密码重置验证码，支持测试模式和真实发送模式。
### resetPassword()
使用验证码重置用户密码，包含密码强度验证和安全检查。
#### resetPassword(resetRequest: PasswordResetRequest): Promise<ApiResponse>
使用验证码重置用户密码，验证验证码有效性后更新密码。
### changePassword()
修改用户密码，验证旧密码并应用新密码强度规则。
#### changePassword(userId: bigint, oldPassword: string, newPassword: string): Promise<ApiResponse>
修改用户密码，需要验证旧密码正确性后才能更新为新密码。
## 邮箱验证功能
#### refreshAccessToken(refreshToken: string): Promise<ApiResponse<TokenPair>>
使用有效的刷新令牌生成新的访问令牌，实现无感知的令牌续期。
### sendEmailVerification()
发送邮箱验证码，用于注册时的邮箱验证和账户安全验证。
#### sendLoginVerificationCode(identifier: string): Promise<ApiResponse<{verification_code?: string; is_test_mode?: boolean}>>
向用户邮箱或手机发送登录验证码，用于验证码登录功能。
### verifyEmailCode()
验证邮箱验证码，确认邮箱所有权并更新用户验证状态。
### RegisterService
### resendEmailVerification()
重新发送邮箱验证码，处理验证码过期或丢失的情况。
#### register(registerRequest: RegisterRequest): Promise<ApiResponse<RegisterResponse>>
处理用户注册请求，创建游戏账号和Zulip账号，支持邮箱验证和自动回滚。
### sendLoginVerificationCode()
发送登录验证码，支持验证码登录功能。
#### sendEmailVerification(email: string): Promise<ApiResponse<{verification_code?: string; is_test_mode?: boolean}>>
向指定邮箱发送验证码，支持测试模式和真实发送模式。
## 调试和管理功能
#### verifyEmailCode(email: string, code: string): Promise<ApiResponse>
验证邮箱验证码的有效性，用于邮箱验证流程。
### debugVerificationCode()
获取验证码调试信息，用于开发环境的测试和调试。
#### resendEmailVerification(email: string): Promise<ApiResponse<{verification_code?: string; is_test_mode?: boolean}>>
重新向指定邮箱发送验证码，用于验证码过期或未收到的情况。
## HTTP API接口
## 依赖关系
### POST /auth/login
用户登录接口，接受用户名/邮箱/手机号和密码，返回JWT令牌和用户信息。
### POST /auth/register
用户注册接口，创建新用户账户并可选择性创建Zulip账号。
### POST /auth/github
GitHub OAuth登录接口，处理GitHub第三方登录和账户绑定。
### POST /auth/forgot-password
发送密码重置验证码接口，支持邮箱和手机号找回密码。
### POST /auth/reset-password
重置密码接口，使用验证码验证身份并设置新密码。
### PUT /auth/change-password
修改密码接口，需要验证旧密码并设置新密码。
### POST /auth/send-email-verification
发送邮箱验证码接口，用于邮箱验证流程。
### POST /auth/verify-email
验证邮箱验证码接口，确认邮箱所有权。
### POST /auth/resend-email-verification
重新发送邮箱验证码接口，处理验证码重发需求。
### POST /auth/verification-code-login
验证码登录接口，支持无密码登录方式。
### POST /auth/send-login-verification-code
发送登录验证码接口，为验证码登录提供验证码。
### POST /auth/refresh-token
刷新JWT令牌接口，使用刷新令牌获取新的访问令牌。
### POST /auth/debug-verification-code
调试验证码接口，获取验证码状态和调试信息。
### POST /auth/debug-clear-throttle
清除限流记录接口，仅用于开发环境调试。
## 认证和授权组件
### JwtAuthGuard
JWT认证守卫，验证请求中的Bearer令牌并提取用户信息到请求上下文。
### CurrentUser
当前用户装饰器，从请求上下文中提取认证用户信息，支持获取完整用户对象或特定属性。
```
Gateway Layer (auth.gateway.module)
↓ 使用
Business Layer (auth.module)
↓ 依赖
Core Layer (login_core.module, zulip_core.module)
```
## 使用的项目内部依赖
### LoginCoreService (来自 core/login_core/login_core.service)
登录核心服务，提供用户认证、密码管理、JWT令牌生成验证等核心功能实现。
### LoginCoreService (来自 core/login_core)
核心登录服务，提供用户认证、JWT令牌生成、密码验证、验证码管理等技术实现。
### ZulipAccountService (来自 core/zulip_core/services/zulip_account.service)
Zulip账号服务，处理Zulip账号的创建、管理和API Key安全存储。
### ZulipAccountService (来自 core/zulip_core)
Zulip账号服务，提供Zulip账号创建、API Key管理、账号验证等功能。
### ZulipAccountsService (来自 core/db/zulip_accounts/zulip_accounts.service)
Zulip账号数据服务，管理游戏用户与Zulip账号的关联关系数据。
### ApiKeySecurityService (来自 core/zulip_core)
API Key安全服务，负责Zulip API Key的加密存储和Redis缓存管理。
### ApiKeySecurityService (来自 core/zulip_core/services/api_key_security.service)
API Key安全服务，负责Zulip API Key的加密存储和安全管理。
### ZulipAccountsService (来自 core/db/zulip_accounts)
Zulip账号数据访问服务，提供游戏账号与Zulip账号的关联管理。
### Users (来自 core/db/users/users.entity)
用户实体类，定义用户数据结构和数据库映射关系。
### Users (来自 core/db/users)
用户实体，定义用户数据结构和数据库映射关系。
### UserStatus (来自 business/user_mgmt/user_status.enum)
用户状态枚举，定义用户的激活、禁用、待验证等状态值。
## 核心原则
### LoginDto, RegisterDto (本模块)
登录和注册数据传输对象，提供完整的数据验证规则和类型定义。
### 1. 专注业务逻辑，不处理HTTP协议
### LoginResponseDto, RegisterResponseDto (本模块)
登录和注册响应数据传输对象，定义API响应的数据结构和格式。
```typescript
// ✅ 正确：返回统一的业务响应
async login(loginRequest: LoginRequest): Promise<ApiResponse<LoginResponse>> {
try {
// 1. 调用核心服务进行认证
const authResult = await this.loginCoreService.login(loginRequest);
// 2. 验证Zulip账号
await this.validateAndUpdateZulipApiKey(authResult.user);
// 3. 生成JWT令牌
const tokenPair = await this.loginCoreService.generateTokenPair(authResult.user);
// 4. 返回业务响应
return {
success: true,
data: { user: this.formatUserInfo(authResult.user), ...tokenPair },
message: '登录成功'
};
} catch (error) {
return {
success: false,
message: error.message,
error_code: 'LOGIN_FAILED'
};
}
}
```
### ThrottlePresets, TimeoutPresets (来自 core/security_core/decorators)
安全防护预设配置，提供限流和超时控制的标准配置。
### 2. 协调多个核心服务
```typescript
async register(registerRequest: RegisterRequest): Promise<ApiResponse<RegisterResponse>> {
// 1. 初始化Zulip管理员客户端
await this.initializeZulipAdminClient();
// 2. 调用核心服务进行注册
const authResult = await this.loginCoreService.register(registerRequest);
// 3. 创建Zulip账号
await this.createZulipAccountForUser(authResult.user, registerRequest.password);
// 4. 生成JWT令牌
const tokenPair = await this.loginCoreService.generateTokenPair(authResult.user);
// 5. 返回完整的业务响应
return { success: true, data: { ... }, message: '注册成功' };
}
```
### 3. 统一的响应格式
```typescript
interface ApiResponse<T = any> {
success: boolean;
data?: T;
message: string;
error_code?: string;
}
```
## 业务服务
### LoginService
负责登录相关的业务逻辑：
- `login()` - 用户登录
- `githubOAuth()` - GitHub OAuth登录
- `verificationCodeLogin()` - 验证码登录
- `sendPasswordResetCode()` - 发送密码重置验证码
- `resetPassword()` - 重置密码
- `changePassword()` - 修改密码
- `refreshAccessToken()` - 刷新访问令牌
- `sendLoginVerificationCode()` - 发送登录验证码
### RegisterService
负责注册相关的业务逻辑：
- `register()` - 用户注册
- `sendEmailVerification()` - 发送邮箱验证码
- `verifyEmailCode()` - 验证邮箱验证码
- `resendEmailVerification()` - 重新发送邮箱验证码
## 核心特性
### 多种登录方式支持
- 用户名/邮箱/手机号密码登录
- GitHub OAuth第三方登录
- 邮箱/手机号验证码登录
- 自动识别登录标识符类型
### Zulip集成
- **自动创建Zulip账号**：注册时同步创建Zulip聊天账号
- **API Key管理**：安全存储和验证Zulip API Key
- **账号关联**：建立游戏账号与Zulip账号的映射关系
- **失败回滚**：Zulip账号创建失败时自动回滚游戏账号
### JWT令牌管理
- 访问令牌和刷新令牌双令牌机制
- 令牌自动刷新和过期处理
- 安全的令牌签名和验证
- 用户信息载荷和权限控制
- **双令牌机制**：访问令牌（短期）+ 刷新令牌（长期）
- **无感知续期**：通过刷新令牌自动更新访问令牌
- **令牌验证**：完整的令牌签名和过期时间验证
### Zulip集成支持
- 注册时自动创建Zulip账号
- 游戏用户与Zulip账号关联管理
- API Key安全存储和加密
- 注册失败时的回滚机制
### 统一响应格式
- **ApiResponse接口**：统一的业务响应格式
- **错误代码**：标准化的错误代码定义
- **成功/失败标识**：明确的success字段
### 邮箱验证系统
- 注册时邮箱验证流程
- 密码重置邮箱验证
- 验证码生成和过期管理
- 测试模式和生产模式支持
### 数据转换和格式化
- **用户信息格式化**：将Core层数据转换为业务数据
- **BigInt处理**：自动将bigint类型转换为string
- **敏感信息过滤**：响应中不包含密码等敏感数据
### 安全防护机制
- 请求频率限制和防暴力破解
- 密码强度验证和安全存储
- 用户状态检查和权限控制
- 详细的安全审计日志
### 完整的错误处理
- **业务异常捕获**：捕获所有业务逻辑异常
- **详细日志记录**：记录操作ID、用户ID、错误信息、执行时间
- **友好错误消息**：返回用户可理解的错误提示
### 业务流程控制
- 完整的错误处理和异常管理
- 统一的响应格式和状态码
- 业务规则验证和数据完整性
- 操作日志和性能监控
## 业务流程示例
### 用户注册流程
```
1. 接收注册请求
↓
2. 初始化Zulip管理员客户端
↓
3. 调用LoginCoreService.register()创建游戏用户
↓
4. 创建Zulip账号并建立关联
├─ 创建Zulip账号
├─ 获取API Key
├─ 存储到Redis
└─ 创建数据库关联记录
↓
5. 生成JWT令牌对
↓
6. 返回注册成功响应
```
### 用户登录流程
```
1. 接收登录请求
↓
2. 调用LoginCoreService.login()验证用户
↓
3. 验证并更新Zulip API Key
├─ 查找Zulip账号关联
├─ 从Redis获取API Key
├─ 验证API Key有效性
└─ 如果无效，重新生成
↓
4. 生成JWT令牌对
↓
5. 返回登录成功响应
```
## 与其他层的交互
### 与Gateway层的交互
Gateway层调用Business层服务：
```typescript
// Gateway Layer
@Post('login')
async login(@Body() loginDto: LoginDto, @Res() res: Response): Promise<void> {
const result = await this.loginService.login({
identifier: loginDto.identifier,
password: loginDto.password
});
this.handleResponse(result, res);
}
```
### 与Core层的交互
Business层调用Core层服务：
```typescript
// Business Layer
async login(loginRequest: LoginRequest): Promise<ApiResponse<LoginResponse>> {
// 调用核心服务
const authResult = await this.loginCoreService.login(loginRequest);
const tokenPair = await this.loginCoreService.generateTokenPair(authResult.user);
// 返回业务响应
return { success: true, data: { ... } };
}
```
## 最佳实践
1. **业务逻辑集中**：所有业务规则都在Business层实现
2. **服务协调**：协调多个Core层服务完成复杂业务
3. **错误处理**：捕获异常并转换为业务错误
4. **日志记录**：记录关键业务操作和错误
5. **事务管理**：处理跨服务的数据一致性
6. **数据转换**：将Core层数据转换为业务数据
## 潜在风险
### Zulip账号创建失败风险
- Zulip服务不可用时注册流程可能失败
- 网络异常导致账号创建不完整
- 建议实现重试机制和降级策略，允许跳过Zulip账号创建
- **风险描述**：注册流程中Zulip账号创建可能失败
- **影响范围**：导致注册流程中断，已创建的游戏账号需要回滚
- **缓解措施**：完整的事务回滚机制和错误日志记录
### 验证码发送依赖风险
- 邮件服务配置错误导致验证码无法发送
- 测试模式下验证码泄露到日志中
- 建议完善邮件服务监控和测试模式安全控制
### API Key验证失败风险
- **风险描述**：登录时Zulip API Key可能已失效或不存在
- **影响范围**：用户无法使用Zulip聊天功能
- **缓解措施**：API Key验证失败不影响登录流程，记录警告日志，尝试重新生成
### JWT令牌安全风险
- 令牌泄露可能导致账户被盗用
- 刷新令牌长期有效增加安全风险
- 建议实现令牌黑名单机制和异常登录检测
### 跨服务事务一致性风险
- **风险描述**：涉及多个Core层服务的协调操作，部分操作成功部分失败
- **影响范围**：数据不一致，如游戏账号创建成功但Zulip账号创建失败
- **缓解措施**：明确的操作顺序、完整的错误处理、自动回滚机制
### 并发操作风险
- 同时注册相同用户名可能导致数据冲突
- 高并发场景下验证码生成可能重复
- 建议加强数据库唯一性约束和分布式锁机制
### 业务逻辑复杂度风险
- **风险描述**：登录和注册流程涉及多个步骤和服务，代码复杂度高
- **影响范围**：增加维护难度，容易引入bug
- **缓解措施**：详细的注释、完整的测试覆盖（41个测试用例）、清晰的日志记录
### 第三方服务依赖风险
- GitHub OAuth服务不可用影响第三方登录
- Zulip服务异常影响账号同步功能
- 建议实现服务降级和故障转移机制
### 验证码发送失败风险
- **风险描述**：邮件服务不可用或配置错误导致验证码无法发送
- **影响范围**：用户无法完成邮箱验证、密码重置、验证码登录
- **缓解措施**：测试模式支持、详细的错误日志、邮件服务健康检查
### 密码安全风险
- 弱密码策略可能导致账户安全问题
- 密码重置流程可能被恶意利用
- 建议加强密码策略和增加二次验证机制
## 注意事项
## 补充信息
### 版本信息
- 模块版本：1.0.2
- 最后修改：2026-01-07
- 作者：moyin
- 创建时间：2025-12-17
### 架构优化记录
- 2026-01-07：将JWT技术实现从Business层移至Core层，符合分层架构原则
- 2026-01-07：完成代码规范优化，统一注释格式和文件命名规范
- 2026-01-07：完善测试覆盖，确保所有公共方法都有对应的单元测试
### 已知限制
- 短信验证码功能尚未实现，目前仅支持邮箱验证码
- Zulip账号创建失败时的重试机制有待完善
- 多设备登录管理和会话控制功能待开发
### 改进建议
- 实现短信验证码发送功能，完善多渠道验证
- 增加社交登录支持（微信、QQ等）
- 实现多因素认证（MFA）提升账户安全
- 添加登录设备管理和异常登录检测
- 完善Zulip集成的错误处理和重试机制
- Business层不应该处理HTTP协议
- Business层不应该直接访问数据库（通过Core层）
- Business层不应该包含技术实现细节
- 所有业务逻辑都应该有完善的错误处理
- 关键业务操作都应该有日志记录

41
src/business/auth/auth.module.ts
View File

@@ -1,32 +1,38 @@
/**
* 用户认证业务模块
*
* 架构层级：Business Layer（业务层）
*
* 功能描述：
* - 整合所有用户认证相关功能
* - 用户登录、注册、密码管理
* - GitHub OAuth集成
* - 邮箱验证功能
* - JWT令牌管理和验证
* - 整合所有用户认证相关的业务逻辑
* - 用户登录、注册、密码管理业务流程
* - GitHub OAuth业务集成
* - 邮箱验证业务功能
* - Zulip账号关联业务
*
* 职责分离：
* - 专注于认证业务模块的依赖注入和配置
* - 整合核心服务和业务服务
* - 提供JWT模块的统一配置
* - 专注于业务逻辑实现和流程控制
* - 整合核心服务完成业务功能
* - 不包含HTTP协议处理（由Gateway层负责）
* - 不包含数据访问细节（由Core层负责）
*
* 依赖关系：
* - 依赖 Core Layer 的 LoginCoreModule
* - 依赖 Core Layer 的 ZulipCoreModule
* - 被 Gateway Layer 的 AuthGatewayModule 使用
*
* 最近修改：
* - 2026-01-14: 架构重构 - 移除Controller，专注于业务逻辑层
* - 2026-01-07: 代码规范优化 - 文件夹扁平化，移除单文件文件夹结构
* - 2026-01-07: 代码规范优化 - 更新注释规范，修正文件引用路径
*
* @author moyin
* @version 1.0.2
* @version 2.0.0
* @since 2025-12-24
* @lastModified 2026-01-07
* @lastModified 2026-01-14
*/
import { Module } from '@nestjs/common';
import { LoginController } from './login.controller';
import { LoginService } from './login.service';
import { RegisterController } from './register.controller';
import { RegisterService } from './register.service';
import { LoginCoreModule } from '../../core/login_core/login_core.module';
import { ZulipCoreModule } from '../../core/zulip_core/zulip_core.module';
@@ -35,16 +41,21 @@ import { UsersModule } from '../../core/db/users/users.module';
@Module({
imports: [
// 导入核心层模块
LoginCoreModule,
ZulipCoreModule,
ZulipAccountsModule.forRoot(),
UsersModule,
],
controllers: [LoginController, RegisterController],
providers: [
// 业务服务
LoginService,
RegisterService,
],
exports: [
// 导出业务服务供Gateway层使用
LoginService,
RegisterService,
],
exports: [LoginService, RegisterService],
})
export class AuthModule {}