# LoginCore 登录核心模块

LoginCore 是应用的用户认证核心模块，提供完整的用户登录、注册、密码管理和邮箱验证功能，支持多种认证方式包括密码登录、验证码登录和 GitHub OAuth 登录。

## 认证相关

### login()
支持用户名/邮箱/手机号的密码登录
- 支持多种登录标识符（用户名、邮箱、手机号）
- 密码哈希验证
- 用户状态检查
- OAuth用户检测

### verificationCodeLogin()
使用邮箱或手机验证码登录
- 邮箱验证码登录（需邮箱已验证）
- 手机验证码登录
- 自动清除验证码冷却时间

### githubOAuth()
GitHub OAuth 第三方登录
- 现有用户信息更新
- 新用户自动注册
- 用户名冲突自动处理

## 注册相关

### register()
用户注册，支持邮箱验证
- 用户名、邮箱、手机号唯一性检查
- 邮箱验证码验证（可选）
- 密码强度验证
- 自动发送欢迎邮件

## 密码管理

### changePassword()
修改用户密码
- 旧密码验证
- 新密码强度检查
- OAuth用户保护

### resetPassword()
通过验证码重置密码
- 验证码验证
- 新密码强度检查
- 自动清除验证码冷却

### sendPasswordResetCode()
发送密码重置验证码
- 邮箱/手机号用户查找
- 邮箱验证状态检查
- 验证码生成和发送

## 邮箱验证

### sendEmailVerification()
发送邮箱验证码
- 邮箱重复注册检查
- 验证码生成和发送
- 测试模式支持

### verifyEmailCode()
验证邮箱验证码
- 验证码验证
- 用户邮箱验证状态更新
- 自动发送欢迎邮件

### resendEmailVerification()
重新发送邮箱验证码
- 用户存在性检查
- 邮箱验证状态检查
- 防重复验证

## 登录验证码

### sendLoginVerificationCode()
发送登录用验证码
- 用户存在性验证
- 邮箱验证状态检查
- 支持邮箱和手机号

## 辅助功能

### deleteUser()
删除用户（用于回滚操作）
- 用户存在性验证
- 安全删除操作
- 异常处理

### debugVerificationCode()
调试验证码信息
- 验证码状态查询
- 开发调试支持

## 核心特性

### 多种认证方式
- 支持密码、验证码、OAuth 三种登录方式
- 灵活的认证策略选择
- 统一的认证结果格式

### 灵活的登录标识
- 支持用户名、邮箱、手机号登录
- 自动识别标识符类型
- 统一的查找逻辑

### 完整的用户生命周期
- 从注册到登录的完整流程
- 邮箱验证和用户激活
- 密码管理和重置

### 安全性保障
- 密码哈希存储（bcrypt，12轮盐值）
- 用户状态检查
- 验证码冷却机制
- OAuth用户保护

### 异常处理完善
- 详细的错误分类和异常处理
- 用户友好的错误信息
- 业务逻辑异常捕获

### 测试覆盖完整
- 15个测试用例，覆盖所有核心功能
- Mock外部依赖，确保单元测试独立性
- 异常情况和边界条件测试

## 潜在风险

### 验证码安全
- 验证码在测试模式下会输出到控制台
- 生产环境需确保安全传输
- 建议实施验证码加密传输

### 密码强度
- 当前密码验证规则相对简单（8位+字母数字）
- 可能需要更严格的密码策略
- 建议增加特殊字符要求

### 频率限制
- 依赖 VerificationService 的频率限制
- 需确保该服务正常工作
- 建议增加备用限制机制

### 用户状态管理
- 用户状态变更可能影响登录
- 需要完善的状态管理机制
- 建议增加状态变更日志

### 第三方依赖
- GitHub OAuth 依赖外部服务
- 需要处理网络异常情况
- 建议增加重试和降级机制

## 使用示例

```typescript
// 密码登录
const result = await loginCoreService.login({
  identifier: 'user@example.com',
  password: 'password123'
});

// 用户注册
const registerResult = await loginCoreService.register({
  username: 'newuser',
  password: 'password123',
  nickname: '新用户',
  email: 'user@example.com',
  email_verification_code: '123456'
});

// 验证码登录
const codeLoginResult = await loginCoreService.verificationCodeLogin({
  identifier: 'user@example.com',
  verificationCode: '123456'
});

// GitHub OAuth登录
const oauthResult = await loginCoreService.githubOAuth({
  github_id: 'github123',
  username: 'githubuser',
  nickname: 'GitHub用户',
  email: 'user@example.com'
});
```

## 依赖服务

- **UsersService**: 用户数据访问服务
- **EmailService**: 邮件发送服务  
- **VerificationService**: 验证码管理服务

## 版本信息

- **版本**: 1.0.1
- **作者**: moyin
- **创建时间**: 2025-12-17
- **最后修改**: 2025-01-07