From e58cc57769611911c668da3ea07c9aebf840c35f Mon Sep 17 00:00:00 2001
From: moyin <244344649@qq.com>
Date: Wed, 17 Dec 2025 20:20:00 +0800
Subject: [PATCH] =?UTF-8?q?docs=EF=BC=9A=E9=87=8D=E6=96=B0=E7=BB=84?=
 =?UTF-8?q?=E7=BB=87=E7=B3=BB=E7=BB=9F=E6=96=87=E6=A1=A3=E7=BB=93=E6=9E=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 将日志系统文档移动到 docs/systems/logger/detailed-specification.md
- 将邮箱验证部署指南移动到 docs/systems/email-verification/deployment-guide.md
- 创建邮箱验证系统完整文档 docs/systems/email-verification/README.md
- 按功能模块组织文档，提高可维护性
---
 docs/systems/email-verification/README.md     | 265 +++++++++++++++
 .../email-verification/deployment-guide.md    | 316 ++++++++++++++++++
 .../logger/detailed-specification.md}         |   0
 3 files changed, 581 insertions(+)
 create mode 100644 docs/systems/email-verification/README.md
 create mode 100644 docs/systems/email-verification/deployment-guide.md
 rename docs/{日志系统详细说明.md => systems/logger/detailed-specification.md} (100%)

diff --git a/docs/systems/email-verification/README.md b/docs/systems/email-verification/README.md
new file mode 100644
index 0000000..aa6d75e
--- /dev/null
+++ 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缓存
+  - 添加防刷机制
\ No newline at end of file
diff --git a/docs/systems/email-verification/deployment-guide.md b/docs/systems/email-verification/deployment-guide.md
new file mode 100644
index 0000000..78684e9
--- /dev/null
+++ 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. **失败重试**：自动重试机制
+
+---
+
+*部署完成后，建议进行完整的功能测试，确保所有邮箱验证功能正常工作。*
\ No newline at end of file
diff --git a/docs/日志系统详细说明.md b/docs/systems/logger/detailed-specification.md
similarity index 100%
rename from docs/日志系统详细说明.md
rename to docs/systems/logger/detailed-specification.md