refactor：项目架构重构和命名规范化
- 统一文件命名为snake_case格式（kebab-case snake_case） - 重构zulip模块为zulip_core，明确Core层职责 - 重构user-mgmt模块为user_mgmt，统一命名规范 - 调整模块依赖关系，优化架构分层 - 删除过时的文件和目录结构 - 更新相关文档和配置文件 本次重构涉及大量文件重命名和模块重组， 旨在建立更清晰的项目架构和统一的命名规范。
This commit is contained in:
moyin
223
src/business/auth/README.md
Normal file
223
src/business/auth/README.md
Normal file
@@ -0,0 +1,223 @@
|
||||
# Auth 用户认证业务模块
|
||||
|
||||
Auth 是应用的核心用户认证业务模块，提供完整的用户登录、注册、密码管理、JWT令牌认证和GitHub OAuth集成功能，支持邮箱验证、验证码登录、安全防护和Zulip账号同步，具备完善的业务流程控制、错误处理和安全审计能力。
|
||||
|
||||
## 用户认证功能
|
||||
|
||||
### login()
|
||||
处理用户登录请求，支持用户名/邮箱/手机号登录，验证用户凭据并生成JWT令牌。
|
||||
|
||||
### register()
|
||||
处理用户注册请求，支持邮箱验证，自动创建Zulip账号并建立关联。
|
||||
|
||||
### githubOAuth()
|
||||
处理GitHub OAuth登录，支持新用户自动注册和现有用户绑定。
|
||||
|
||||
### verificationCodeLogin()
|
||||
支持邮箱或手机号验证码登录，提供无密码登录方式。
|
||||
|
||||
## 密码管理功能
|
||||
|
||||
### sendPasswordResetCode()
|
||||
发送密码重置验证码到用户邮箱或手机号，支持测试模式和真实发送模式。
|
||||
|
||||
### resetPassword()
|
||||
使用验证码重置用户密码，包含密码强度验证和安全检查。
|
||||
|
||||
### changePassword()
|
||||
修改用户密码，验证旧密码并应用新密码强度规则。
|
||||
|
||||
## 邮箱验证功能
|
||||
|
||||
### sendEmailVerification()
|
||||
发送邮箱验证码，用于注册时的邮箱验证和账户安全验证。
|
||||
|
||||
### verifyEmailCode()
|
||||
验证邮箱验证码，确认邮箱所有权并更新用户验证状态。
|
||||
|
||||
### resendEmailVerification()
|
||||
重新发送邮箱验证码，处理验证码过期或丢失的情况。
|
||||
|
||||
### sendLoginVerificationCode()
|
||||
发送登录验证码，支持验证码登录功能。
|
||||
|
||||
## 调试和管理功能
|
||||
|
||||
### debugVerificationCode()
|
||||
获取验证码调试信息，用于开发环境的测试和调试。
|
||||
|
||||
## 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
|
||||
当前用户装饰器，从请求上下文中提取认证用户信息，支持获取完整用户对象或特定属性。
|
||||
|
||||
## 使用的项目内部依赖
|
||||
|
||||
### LoginCoreService (来自 core/login_core/login_core.service)
|
||||
登录核心服务，提供用户认证、密码管理、JWT令牌生成验证等核心功能实现。
|
||||
|
||||
### ZulipAccountService (来自 core/zulip_core/services/zulip_account.service)
|
||||
Zulip账号服务，处理Zulip账号的创建、管理和API Key安全存储。
|
||||
|
||||
### ZulipAccountsService (来自 core/db/zulip_accounts/zulip_accounts.service)
|
||||
Zulip账号数据服务，管理游戏用户与Zulip账号的关联关系数据。
|
||||
|
||||
### ApiKeySecurityService (来自 core/zulip_core/services/api_key_security.service)
|
||||
API Key安全服务，负责Zulip API Key的加密存储和安全管理。
|
||||
|
||||
### Users (来自 core/db/users/users.entity)
|
||||
用户实体类，定义用户数据结构和数据库映射关系。
|
||||
|
||||
### UserStatus (来自 business/user_mgmt/user_status.enum)
|
||||
用户状态枚举，定义用户的激活、禁用、待验证等状态值。
|
||||
|
||||
### LoginDto, RegisterDto (本模块)
|
||||
登录和注册数据传输对象，提供完整的数据验证规则和类型定义。
|
||||
|
||||
### LoginResponseDto, RegisterResponseDto (本模块)
|
||||
登录和注册响应数据传输对象，定义API响应的数据结构和格式。
|
||||
|
||||
### ThrottlePresets, TimeoutPresets (来自 core/security_core/decorators)
|
||||
安全防护预设配置，提供限流和超时控制的标准配置。
|
||||
|
||||
## 核心特性
|
||||
|
||||
### 多种登录方式支持
|
||||
- 用户名/邮箱/手机号密码登录
|
||||
- GitHub OAuth第三方登录
|
||||
- 邮箱/手机号验证码登录
|
||||
- 自动识别登录标识符类型
|
||||
|
||||
### JWT令牌管理
|
||||
- 访问令牌和刷新令牌双令牌机制
|
||||
- 令牌自动刷新和过期处理
|
||||
- 安全的令牌签名和验证
|
||||
- 用户信息载荷和权限控制
|
||||
|
||||
### Zulip集成支持
|
||||
- 注册时自动创建Zulip账号
|
||||
- 游戏用户与Zulip账号关联管理
|
||||
- API Key安全存储和加密
|
||||
- 注册失败时的回滚机制
|
||||
|
||||
### 邮箱验证系统
|
||||
- 注册时邮箱验证流程
|
||||
- 密码重置邮箱验证
|
||||
- 验证码生成和过期管理
|
||||
- 测试模式和生产模式支持
|
||||
|
||||
### 安全防护机制
|
||||
- 请求频率限制和防暴力破解
|
||||
- 密码强度验证和安全存储
|
||||
- 用户状态检查和权限控制
|
||||
- 详细的安全审计日志
|
||||
|
||||
### 业务流程控制
|
||||
- 完整的错误处理和异常管理
|
||||
- 统一的响应格式和状态码
|
||||
- 业务规则验证和数据完整性
|
||||
- 操作日志和性能监控
|
||||
|
||||
## 潜在风险
|
||||
|
||||
### Zulip账号创建失败风险
|
||||
- Zulip服务不可用时注册流程可能失败
|
||||
- 网络异常导致账号创建不完整
|
||||
- 建议实现重试机制和降级策略，允许跳过Zulip账号创建
|
||||
|
||||
### 验证码发送依赖风险
|
||||
- 邮件服务配置错误导致验证码无法发送
|
||||
- 测试模式下验证码泄露到日志中
|
||||
- 建议完善邮件服务监控和测试模式安全控制
|
||||
|
||||
### JWT令牌安全风险
|
||||
- 令牌泄露可能导致账户被盗用
|
||||
- 刷新令牌长期有效增加安全风险
|
||||
- 建议实现令牌黑名单机制和异常登录检测
|
||||
|
||||
### 并发操作风险
|
||||
- 同时注册相同用户名可能导致数据冲突
|
||||
- 高并发场景下验证码生成可能重复
|
||||
- 建议加强数据库唯一性约束和分布式锁机制
|
||||
|
||||
### 第三方服务依赖风险
|
||||
- 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集成的错误处理和重试机制
|
||||
Reference in New Issue
Block a user