# 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集成的错误处理和重试机制