docs：重新组织系统文档结构

- 将日志系统文档移动到 docs/systems/logger/detailed-specification.md - 将邮箱验证部署指南移动到 docs/systems/email-verification/deployment-guide.md - 创建邮箱验证系统完整文档 docs/systems/email-verification/README.md - 按功能模块组织文档，提高可维护性
2025-12-17 20:20:00 +08:00
parent 0065357fa5
commit e58cc57769
3 changed files with 581 additions and 0 deletions
--- a/docs/systems/email-verification/README.md
+++ b/docs/systems/email-verification/README.md
@@ -0,0 +1,265 @@
+# 邮箱验证系统
+
+## 概述
+
+邮箱验证系统提供完整的邮箱验证功能，包括验证码生成、发送、验证和管理。
+
+## 功能特性
+
+- 📧 邮箱验证码发送
+- 🔐 验证码安全验证
+- ⏰ 验证码过期管理
+- 🚫 防刷机制（频率限制）
+- 📊 验证统计和监控
+
+## 系统架构
+
+```
+邮箱验证系统
+├── 验证码服务 (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缓存
+  - 添加防刷机制