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
@@ -0,0 +1,363 @@
+# 日志系统详细说明
+
+## 📋 概述
+
+本项目的日志系统基于 Pino 高性能日志库构建，提供完整的日志记录、管理和分析功能。
+
+---
+
+## 🗂️ 日志文件结构
+
+### 开发环境 (`NODE_ENV=development`)
+
+```
+logs/
+└── dev.log                 # 开发环境综合日志（所有级别）
+```
+
+**输出方式：**
+- 🖥️ **控制台**：彩色美化输出，便于开发调试
+- 📁 **文件**：保存到 `logs/dev.log`，便于问题追踪
+
+### 生产环境 (`NODE_ENV=production`)
+
+```
+logs/
+├── app.log                 # 应用综合日志（info及以上级别）
+├── error.log               # 错误日志（error和fatal级别）
+├── access.log              # HTTP访问日志（请求响应记录）
+├── app.log.gz              # 压缩的历史日志文件
+├── error.log.gz            # 压缩的历史错误日志
+└── access.log.gz           # 压缩的历史访问日志
+```
+
+**输出方式：**
+- 📁 **文件**：分类保存到不同的日志文件
+- 🖥️ **控制台**：仅输出 warn 及以上级别（用于容器日志收集）
+
+---
+
+## 📊 日志级别和用途
+
+| 级别 | 数值 | 用途 | 保存位置 | 示例场景 |
+|------|------|------|----------|----------|
+| **TRACE** | 10 | 极细粒度调试 | dev.log | 循环内变量状态 |
+| **DEBUG** | 20 | 开发调试信息 | dev.log | 方法调用参数 |
+| **INFO** | 30 | 重要业务操作 | app.log, dev.log | 用户登录成功 |
+| **WARN** | 40 | 警告信息 | app.log, dev.log, 控制台 | 参数验证失败 |
+| **ERROR** | 50 | 错误信息 | error.log, app.log, 控制台 | 数据库连接失败 |
+| **FATAL** | 60 | 致命错误 | error.log, app.log, 控制台 | 系统不可用 |
+
+---
+
+## 🔄 日志轮转和管理
+
+### 自动轮转策略
+
+| 文件类型 | 轮转频率 | 文件大小限制 | 保留时间 | 压缩策略 |
+|----------|----------|--------------|----------|----------|
+| **app.log** | 每日 | 10MB | 7天 | 7天后压缩 |
+| **error.log** | 每日 | 10MB | 30天 | 7天后压缩 |
+| **access.log** | 每日 | 50MB | 14天 | 7天后压缩 |
+| **dev.log** | 手动 | 无限制 | 无限制 | 不压缩 |
+
+### 定时任务
+
+| 任务 | 执行时间 | 功能 |
+|------|----------|------|
+| **日志清理** | 每天 02:00 | 删除过期日志文件 |
+| **日志压缩** | 每周日 03:00 | 压缩7天前的日志文件 |
+| **健康监控** | 每小时 | 监控日志系统状态 |
+| **统计报告** | 每天 09:00 | 输出日志统计信息 |
+
+---
+
+## 🚀 如何使用日志系统
+
+### 基本使用
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { AppLoggerService } from '../core/utils/logger/logger.service';
+
+@Injectable()
+export class UserService {
+  constructor(private readonly logger: AppLoggerService) {}
+
+  async createUser(userData: CreateUserDto) {
+    // 记录操作开始
+    this.logger.info('开始创建用户', {
+      operation: 'createUser',
+      email: userData.email,
+      timestamp: new Date().toISOString()
+    });
+
+    try {
+      const user = await this.userRepository.save(userData);
+      
+      // 记录成功操作
+      this.logger.info('用户创建成功', {
+        operation: 'createUser',
+        userId: user.id,
+        email: userData.email,
+        duration: Date.now() - startTime
+      });
+
+      return user;
+    } catch (error) {
+      // 记录错误
+      this.logger.error('用户创建失败', {
+        operation: 'createUser',
+        email: userData.email,
+        error: error.message
+      }, error.stack);
+      
+      throw error;
+    }
+  }
+}
+```
+
+### 请求上下文绑定
+
+```typescript
+@Controller('users')
+export class UserController {
+  constructor(private readonly logger: AppLoggerService) {}
+
+  @Get(':id')
+  async getUser(@Param('id') id: string, @Req() req: Request) {
+    // 绑定请求上下文
+    const requestLogger = this.logger.bindRequest(req, 'UserController');
+    
+    requestLogger.info('开始获取用户信息', { userId: id });
+    
+    try {
+      const user = await this.userService.findById(id);
+      requestLogger.info('用户信息获取成功', { userId: id });
+      return user;
+    } catch (error) {
+      requestLogger.error('用户信息获取失败', error.stack, { 
+        userId: id, 
+        reason: error.message 
+      });
+      throw error;
+    }
+  }
+}
+```
+
+---
+
+## 🔍 日志格式详解
+
+### 开发环境日志格式
+
+```
+🕐 2024-12-13 14:30:25 📝 INFO pixel-game-server [UserService] 用户创建成功
+    operation: "createUser"
+    userId: "user_123"
+    email: "user@example.com"
+    duration: 45
+```
+
+### 生产环境日志格式 (JSON)
+
+```json
+{
+  "level": 30,
+  "time": 1702456225000,
+  "pid": 12345,
+  "hostname": "server-01",
+  "app": "pixel-game-server",
+  "version": "1.0.0",
+  "msg": "用户创建成功",
+  "operation": "createUser",
+  "userId": "user_123",
+  "email": "user@example.com",
+  "duration": 45,
+  "reqId": "req_1702456225_abc123"
+}
+```
+
+### HTTP 请求日志格式
+
+```json
+{
+  "level": 30,
+  "time": 1702456225000,
+  "req": {
+    "id": "req_1702456225_abc123",
+    "method": "POST",
+    "url": "/api/users",
+    "headers": {
+      "host": "localhost:3000",
+      "user-agent": "Mozilla/5.0...",
+      "content-type": "application/json"
+    },
+    "ip": "127.0.0.1"
+  },
+  "res": {
+    "statusCode": 201,
+    "responseTime": 45
+  },
+  "msg": "POST /api/users completed in 45ms"
+}
+```
+
+---
+
+## 🛠️ 问题排查指南
+
+### 1. 如何查找特定用户的操作日志？
+
+```bash
+# 在日志文件中搜索特定用户ID
+grep "userId.*user_123" logs/app.log
+
+# 搜索特定操作
+grep "operation.*createUser" logs/app.log
+
+# 搜索特定时间段的日志
+grep "2024-12-13 14:" logs/app.log
+```
+
+### 2. 如何查找错误日志？
+
+```bash
+# 查看所有错误日志
+cat logs/error.log
+
+# 查看最近的错误
+tail -f logs/error.log
+
+# 搜索特定错误
+grep "数据库连接失败" logs/error.log
+```
+
+### 3. 如何分析性能问题？
+
+```bash
+# 查找响应时间超过1000ms的请求
+grep "responseTime.*[0-9][0-9][0-9][0-9]" logs/access.log
+
+# 查找特定接口的性能数据
+grep "POST /api/users" logs/access.log | grep responseTime
+```
+
+### 4. 如何监控系统健康状态？
+
+```bash
+# 查看日志统计信息
+grep "日志系统健康状态报告" logs/app.log
+
+# 查看日志清理记录
+grep "日志清理任务完成" logs/app.log
+
+# 查看压缩记录
+grep "日志压缩任务完成" logs/app.log
+```
+
+---
+
+## 📈 日志分析和监控
+
+### 日志统计信息
+
+系统会自动收集以下统计信息：
+
+- **文件数量**：当前日志文件总数
+- **总大小**：所有日志文件占用的磁盘空间
+- **错误日志数量**：错误级别日志文件数量
+- **最旧/最新文件**：日志文件的时间范围
+- **平均文件大小**：单个日志文件的平均大小
+
+### 健康监控告警
+
+系统会在以下情况发出警告：
+
+- 📊 **磁盘空间告警**：日志文件总大小超过阈值
+- ⚠️ **错误日志告警**：错误日志数量异常增长
+- 🔧 **清理失败告警**：日志清理任务执行失败
+- 💾 **压缩失败告警**：日志压缩任务执行失败
+
+---
+
+## ⚙️ 配置说明
+
+### 环境变量配置
+
+```bash
+# 应用名称
+APP_NAME=pixel-game-server
+
+# 环境标识
+NODE_ENV=development
+
+# 日志级别
+LOG_LEVEL=debug
+
+# 日志目录
+LOG_DIR=./logs
+
+# 日志保留天数
+LOG_MAX_FILES=7d
+
+# 单个日志文件最大大小
+LOG_MAX_SIZE=10m
+```
+
+### 高级配置选项
+
+如需自定义日志配置，可以修改 `src/core/utils/logger/logger.config.ts`：
+
+```typescript
+// 自定义日志轮转策略
+{
+  target: 'pino-roll',
+  options: {
+    file: path.join(logDir, 'app.log'),
+    frequency: 'daily',    // 轮转频率：daily, hourly, weekly
+    size: '10m',          // 文件大小限制
+    limit: {
+      count: 7,           // 保留文件数量
+    },
+  },
+}
+```
+
+---
+
+## 🚨 注意事项
+
+### 安全考虑
+
+1. **敏感信息过滤**：系统自动过滤密码、token等敏感字段
+2. **访问控制**：确保日志文件只有授权用户可以访问
+3. **传输加密**：生产环境建议使用加密传输日志
+
+### 性能考虑
+
+1. **异步写入**：Pino 使用异步写入，不会阻塞主线程
+2. **日志级别**：生产环境建议使用 info 及以上级别
+3. **文件轮转**：及时清理和压缩日志文件，避免占用过多磁盘空间
+
+### 运维建议
+
+1. **监控磁盘空间**：定期检查日志目录的磁盘使用情况
+2. **备份重要日志**：对于重要的错误日志，建议定期备份
+3. **日志分析**：可以集成 ELK Stack 等日志分析工具
+4. **告警设置**：配置日志监控告警，及时发现系统问题
+
+---
+
+## 🔗 相关文档
+
+- [后端开发规范 - 日志系统使用指南](./backend_development_guide.md#四日志系统使用指南)
+- [AI 辅助开发规范指南](./AI辅助开发规范指南.md)
+- [Pino 官方文档](https://getpino.io/)
+- [NestJS Pino 集成文档](https://github.com/iamolegga/nestjs-pino)
+
+---
+
+**💡 提示：使用 [AI 辅助开发指南](./AI辅助开发规范指南.md) 可以让 AI 帮你自动生成符合规范的日志代码！**