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缓存
  - 添加防刷机制
--- a/docs/systems/email-verification/deployment-guide.md
+++ b/docs/systems/email-verification/deployment-guide.md
@@ -0,0 +1,316 @@
 # 邮箱验证功能部署指南
 ## 概述
 本指南详细说明如何部署和配置邮箱验证功能，包括Redis缓存、邮件服务配置等。
 ## 1. 安装依赖
 ```bash
 # 安装新增的依赖包
 pnpm install ioredis nodemailer
 # 安装类型定义
 pnpm install -D @types/nodemailer
 ```
 ## 2. Redis 服务配置
 ### 2.1 安装 Redis
 #### Ubuntu/Debian
 ```bash
 sudo apt update
 sudo apt install redis-server
 sudo systemctl start redis-server
 sudo systemctl enable redis-server
 ```
 #### CentOS/RHEL
 ```bash
 sudo yum install redis
 sudo systemctl start redis
 sudo systemctl enable redis
 ```
 #### Docker 方式
 ```bash
 docker run -d --name redis -p 6379:6379 redis:7-alpine
 ```
 ### 2.2 Redis 配置验证
 ```bash
 # 测试 Redis 连接
 redis-cli ping
 # 应该返回 PONG
 ```
 ## 3. 邮件服务配置
 ### 3.1 Gmail 配置示例
 1. **启用两步验证**：
   - 登录 Google 账户
   - 进入"安全性"设置
   - 启用"两步验证"
 2. **生成应用专用密码**：
   - 在"安全性"设置中找到"应用专用密码"
   - 生成新的应用密码
   - 记录生成的16位密码
 3. **环境变量配置**：
 ```env
 EMAIL_HOST=smtp.gmail.com
 EMAIL_PORT=587
 EMAIL_SECURE=false
 EMAIL_USER=your-email@gmail.com
 EMAIL_PASS=your-16-digit-app-password
 EMAIL_FROM="Whale Town Game" <noreply@gmail.com>
 ```
 ### 3.2 其他邮件服务商配置
 #### 163邮箱
 ```env
 EMAIL_HOST=smtp.163.com
 EMAIL_PORT=587
 EMAIL_SECURE=false
 EMAIL_USER=your-email@163.com
 EMAIL_PASS=your-authorization-code
 ```
 #### QQ邮箱
 ```env
 EMAIL_HOST=smtp.qq.com
 EMAIL_PORT=587
 EMAIL_SECURE=false
 EMAIL_USER=your-email@qq.com
 EMAIL_PASS=your-authorization-code
 ```
 #### 阿里云邮件推送
 ```env
 EMAIL_HOST=smtpdm.aliyun.com
 EMAIL_PORT=587
 EMAIL_SECURE=false
 EMAIL_USER=your-smtp-username
 EMAIL_PASS=your-smtp-password
 ```
 ## 4. 环境变量配置
 ### 4.1 创建环境配置文件
 ```bash
 # 复制环境变量模板
 cp .env.production.example .env
 # 编辑环境变量
 nano .env
 ```
 ### 4.2 完整的环境变量配置
 ```env
 # 数据库配置
 DB_HOST=localhost
 DB_PORT=3306
 DB_USERNAME=pixel_game
 DB_PASSWORD=your_db_password
 DB_NAME=pixel_game_db
 # 应用配置
 NODE_ENV=production
 PORT=3000
 # JWT 配置
 JWT_SECRET=your_jwt_secret_key_here_at_least_32_characters
 JWT_EXPIRES_IN=7d
 # Redis 配置
 REDIS_HOST=localhost
 REDIS_PORT=6379
 REDIS_PASSWORD=
 REDIS_DB=0
 # 邮件服务配置
 EMAIL_HOST=smtp.gmail.com
 EMAIL_PORT=587
 EMAIL_SECURE=false
 EMAIL_USER=your-email@gmail.com
 EMAIL_PASS=your-app-password
 EMAIL_FROM="Whale Town Game" <noreply@whaletown.com>
 ```
 ## 5. 数据库迁移
 由于添加了新的字段，需要更新数据库结构：
 ```sql
 -- 添加邮箱验证状态字段
 ALTER TABLE users ADD COLUMN email_verified BOOLEAN NOT NULL DEFAULT FALSE COMMENT '邮箱是否已验证';
 -- 为已有用户设置默认值
 UPDATE users SET email_verified = FALSE WHERE email_verified IS NULL;
 -- 如果是OAuth用户且有邮箱，可以设为已验证
 UPDATE users SET email_verified = TRUE WHERE github_id IS NOT NULL AND email IS NOT NULL;
 ```
 ## 6. 启动和测试
 ### 6.1 启动应用
 ```bash
 # 安装依赖
 pnpm install
 # 构建应用
 pnpm run build
 # 启动应用
 pnpm run start:prod
 ```
 ### 6.2 功能测试
 #### 测试邮箱验证码发送
 ```bash
 curl -X POST http://localhost:3000/auth/send-email-verification \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com"}'
 ```
 #### 测试邮箱验证
 ```bash
 curl -X POST http://localhost:3000/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","verification_code":"123456"}'
 ```
 #### 测试密码重置
 ```bash
 curl -X POST http://localhost:3000/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"identifier":"test@example.com"}'
 ```
 ## 7. 监控和日志
 ### 7.1 查看应用日志
 ```bash
 # PM2 日志
 pm2 logs pixel-game-server
 # 或者查看文件日志
 tail -f logs/dev.log
 ```
 ### 7.2 Redis 监控
 ```bash
 # 查看 Redis 信息
 redis-cli info
 # 监控 Redis 命令
 redis-cli monitor
 # 查看验证码相关的键
 redis-cli keys "verification_*"
 ```
 ### 7.3 邮件发送监控
 应用会记录邮件发送的日志，包括：
 - 发送成功/失败状态
 - 收件人信息
 - 发送时间
 - 错误信息（如果有）
 ## 8. 故障排除
 ### 8.1 Redis 连接问题
 **问题**：Redis连接失败
 ```
 Redis连接错误: Error: connect ECONNREFUSED 127.0.0.1:6379
 ```
 **解决方案**：
 1. 检查Redis服务状态：`sudo systemctl status redis`
 2. 启动Redis服务：`sudo systemctl start redis`
 3. 检查防火墙设置
 4. 验证Redis配置文件
 ### 8.2 邮件发送问题
 **问题**：邮件发送失败
 ```
 邮件发送失败: Error: Invalid login: 535-5.7.8 Username and Password not accepted
 ```
 **解决方案**：
 1. 检查邮箱用户名和密码
 2. 确认已启用应用专用密码（Gmail）
 3. 检查邮件服务商的SMTP设置
 4. 验证网络连接
 ### 8.3 验证码问题
 **问题**：验证码验证失败
 **解决方案**：
 1. 检查Redis中是否存在验证码：`redis-cli get verification_code:email_verification:test@example.com`
 2. 检查验证码是否过期
 3. 验证验证码格式（6位数字）
 4. 检查应用日志
 ## 9. 安全建议
 ### 9.1 邮件服务安全
 1. **使用应用专用密码**：不要使用主密码
 2. **启用TLS/SSL**：确保邮件传输加密
 3. **限制发送频率**：防止邮件轰炸
 4. **监控发送量**：避免被标记为垃圾邮件
 ### 9.2 Redis 安全
 1. **设置密码**：`requirepass your_redis_password`
 2. **绑定IP**：`bind 127.0.0.1`
 3. **禁用危险命令**：`rename-command FLUSHDB ""`
 4. **定期备份**：设置Redis数据备份
 ### 9.3 验证码安全
 1. **设置过期时间**：默认5分钟
 2. **限制尝试次数**：最多3次
 3. **防刷机制**：60秒冷却时间
 4. **记录日志**：监控异常行为
 ## 10. 性能优化
 ### 10.1 Redis 优化
 ```redis
 # Redis 配置优化
 maxmemory 256mb
 maxmemory-policy allkeys-lru
 save 900 1
 save 300 10
 save 60 10000
 ```
 ### 10.2 邮件发送优化
 1. **连接池**：复用SMTP连接
 2. **异步发送**：不阻塞主流程
 3. **队列机制**：处理大量邮件
 4. **失败重试**：自动重试机制
 ---
 *部署完成后，建议进行完整的功能测试，确保所有邮箱验证功能正常工作。*
--- a/docs/systems/logger/detailed-specification.md
+++ b/docs/systems/logger/detailed-specification.md