whale-town-end/docs/systems/email-verification/README.md

# 邮箱验证系统

## 概述

邮箱验证系统提供完整的邮箱验证功能，包括验证码生成、发送、验证和管理。

## 功能特性

- 📧 邮箱验证码发送
- 🔐 验证码安全验证
- ⏰ 验证码过期管理
- 🚫 防刷机制（频率限制）
- 📊 验证统计和监控

## 系统架构

```
邮箱验证系统
├── 验证码服务 (VerificationService)
│   ├── 验证码生成
│   ├── 验证码验证
│   └── 防刷机制
├── 邮件服务 (EmailService)
│   ├── 验证码邮件发送
│   ├── 欢迎邮件发送
│   └── 邮件模板管理
└── Redis缓存
    ├── 验证码存储
    ├── 冷却时间管理
    └── 发送频率限制
```

## 核心组件

### 1. 验证码服务 (VerificationService)

负责验证码的生成、验证和管理：

- **验证码生成**：6位数字验证码
- **验证码验证**：支持多次尝试限制
- **过期管理**：5分钟有效期
- **防刷机制**：60秒冷却时间，每小时最多5次

### 2. 邮件服务 (EmailService)

负责邮件的发送和模板管理：

- **验证码邮件**：发送验证码到用户邮箱
- **欢迎邮件**：用户注册成功后发送
- **模板支持**：支持HTML邮件模板

### 3. Redis缓存

负责数据的临时存储：

- **验证码存储**：`verification_code:${type}:${identifier}`
- **冷却时间**：`verification_cooldown:${type}:${identifier}`
- **发送频率**：`verification_hourly:${type}:${identifier}:${date}:${hour}`

## 使用流程

### 注册流程中的邮箱验证

1. **发送验证码**
   ```typescript
   POST /auth/send-email-verification
   {
     "email": "user@example.com"
   }
   ```

2. **用户注册**
   ```typescript
   POST /auth/register
   {
     "username": "testuser",
     "password": "password123",
     "nickname": "测试用户",
     "email": "user@example.com",
     "email_verification_code": "123456"
   }
   ```

### 独立邮箱验证

1. **验证邮箱**
   ```typescript
   POST /auth/verify-email
   {
     "email": "user@example.com",
     "verification_code": "123456"
   }
   ```

## 配置说明

### 环境变量

```bash
# 邮件服务配置
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=your-email@example.com
SMTP_PASS=your-password
SMTP_FROM=noreply@example.com

# Redis配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
```

### 验证码配置

```typescript
// 验证码长度
CODE_LENGTH = 6

// 验证码过期时间（秒）
CODE_EXPIRE_TIME = 300 // 5分钟

// 最大验证尝试次数
MAX_ATTEMPTS = 3

// 发送冷却时间（秒）
RATE_LIMIT_TIME = 60 // 1分钟

// 每小时最大发送次数
MAX_SENDS_PER_HOUR = 5
```

## API接口

### 发送邮箱验证码

- **接口**：`POST /auth/send-email-verification`
- **描述**：向指定邮箱发送验证码
- **参数**：
  ```typescript
  {
    email: string; // 邮箱地址
  }
  ```

### 验证邮箱验证码

- **接口**：`POST /auth/verify-email`
- **描述**：使用验证码验证邮箱
- **参数**：
  ```typescript
  {
    email: string;            // 邮箱地址
    verification_code: string; // 6位数字验证码
  }
  ```

### 重新发送验证码

- **接口**：`POST /auth/resend-email-verification`
- **描述**：重新向指定邮箱发送验证码
- **参数**：
  ```typescript
  {
    email: string; // 邮箱地址
  }
  ```

## 错误处理

### 常见错误码

- `VERIFICATION_CODE_NOT_FOUND`：验证码不存在或已过期
- `VERIFICATION_CODE_INVALID`：验证码错误
- `TOO_MANY_ATTEMPTS`：验证尝试次数过多
- `RATE_LIMIT_EXCEEDED`：发送频率过高
- `EMAIL_SEND_FAILED`：邮件发送失败

### 错误响应格式

```typescript
{
  success: false,
  message: "错误描述",
  error_code: "ERROR_CODE"
}
```

## 监控和日志

### 关键指标

- 验证码发送成功率
- 验证码验证成功率
- 邮件发送延迟
- Redis连接状态

### 日志记录

- 验证码生成和验证日志
- 邮件发送状态日志
- 错误和异常日志
- 性能监控日志

## 安全考虑

### 防刷机制

1. **发送频率限制**：每个邮箱60秒内只能发送一次
2. **每小时限制**：每个邮箱每小时最多发送5次
3. **验证尝试限制**：每个验证码最多尝试3次

### 数据安全

1. **验证码加密存储**：Redis中的验证码经过加密
2. **过期自动清理**：验证码5分钟后自动过期
3. **日志脱敏**：日志中不记录完整验证码

## 部署指南

详细的部署说明请参考：[deployment-guide.md](./deployment-guide.md)

## 测试

### 单元测试

```bash
# 运行验证服务测试
npm test -- verification.service.spec.ts

# 运行邮件服务测试
npm test -- email.service.spec.ts
```

### 集成测试

```bash
# 运行邮箱验证集成测试
npm run test:e2e -- email-verification
```

## 故障排除

### 常见问题

1. **验证码收不到**
   - 检查SMTP配置
   - 检查邮箱是否在垃圾邮件中
   - 检查网络连接

2. **验证码验证失败**
   - 检查验证码是否过期
   - 检查验证码输入是否正确
   - 检查Redis连接状态

3. **发送频率限制**
   - 等待冷却时间结束
   - 检查是否达到每小时限制

## 更新日志

- **v1.0.0** (2025-12-17)
  - 初始版本发布
  - 支持基本的邮箱验证功能
  - 集成Redis缓存
  - 添加防刷机制