refactor：项目架构重构和命名规范化

- 统一文件命名为snake_case格式（kebab-case snake_case） - 重构zulip模块为zulip_core，明确Core层职责 - 重构user-mgmt模块为user_mgmt，统一命名规范 - 调整模块依赖关系，优化架构分层 - 删除过时的文件和目录结构 - 更新相关文档和配置文件本次重构涉及大量文件重命名和模块重组，旨在建立更清晰的项目架构和统一的命名规范。
2026-01-08 00:14:14 +08:00
parent 4fa4bd1a70
commit bb796a2469
178 changed files with 24767 additions and 3484 deletions
--- a/docs/development/AI代码检查规范.md
+++ b/docs/development/AI代码检查规范.md
--- a/docs/development/AI辅助开发规范指南.md
+++ b/docs/development/AI辅助开发规范指南.md
@@ -37,6 +37,35 @@
 | [后端开发规范](./backend_development_guide.md) | 注释、日志、业务逻辑 | 注释完整性、日志规范 |
 | [NestJS 使用指南](./nestjs_guide.md) | 框架最佳实践 | 架构设计、代码组织 |

+**📝 重要：修改记录注释规范**
+
+当对现有文件进行修改时，必须在文件头注释中添加修改记录，格式如下：
+
+```typescript
+/**
+ * 文件功能描述
+ * 
+ * 最近修改：
+ * - YYYY-MM-DD: 修改类型 - 具体修改内容描述
+ * - YYYY-MM-DD: 修改类型 - 具体修改内容描述
+ * 
+ * @author 原作者
+ * @version x.x.x (修改后递增版本号)
+ * @since 创建日期
+ * @lastModified 最后修改日期
+ */
+```
+
+**📏 重要限制：修改记录只保留最近5次修改，超出时删除最旧记录，保持注释简洁。**
+
+**修改类型包括：**
+- `代码规范优化` - 命名规范、注释规范、代码清理等
+- `功能新增` - 添加新的功能或方法
+- `功能修改` - 修改现有功能的实现
+- `Bug修复` - 修复代码缺陷
+- `性能优化` - 提升代码性能
+- `重构` - 代码结构调整但功能不变
+
 ---

 ## 🤖 AI 辅助开发工作流程
@@ -89,6 +118,7 @@
   - 模块级注释（功能描述、依赖模块、作者、版本）
   - 类级注释（职责、主要方法、使用场景）
   - 方法级注释（功能描述、业务逻辑、参数、返回值、异常、示例）
+   - 修改记录注释（如果是修改现有文件，添加修改记录和更新版本号）

 2. 按照命名规范：
   - 类名使用大驼峰
@@ -229,6 +259,7 @@
 □ 模块级注释（功能描述、依赖模块、作者、版本）
 □ 类级注释（职责、主要方法、使用场景）  
 □ 方法级注释（功能描述、业务逻辑、参数、返回值、异常、示例）
+□ 修改记录注释（如果是修改现有文件，必须添加修改记录和更新版本号，只保留最近5次修改）
 □ 文件命名使用下划线分隔
 □ 类名使用大驼峰命名
 □ 方法名使用小驼峰命名
@@ -312,7 +343,50 @@ AI 会生成包含完整注释和异常处理的代码。
 请按照 Git 提交规范生成提交信息。
 ```

-### 案例2：代码审查场景
+### 案例3：修改现有文件规范
+
+#### 修改现有代码时的注释更新
+
+```
+我需要修改现有的 login_core.service.ts 文件，进行以下优化：
+- 清理未使用的导入 (EmailSendResult, crypto)
+- 修复常量命名 (saltRounds -> SALT_ROUNDS)  
+- 删除未使用的私有方法 (generateVerificationCode)
+
+请帮我：
+1. 在文件头注释中添加修改记录
+2. 更新版本号 (1.0.0 -> 1.0.1)
+3. 添加 @lastModified 标记
+4. 确保修改记录格式符合规范
+5. 只保留最近5次修改记录，保持注释简洁
+
+修改记录格式要求：
+- 日期格式：YYYY-MM-DD
+- 修改类型：代码规范优化
+- 描述要具体明确
+- 最多保留5条记录
+```
+
+#### AI 生成的修改记录示例
+
+```typescript
+/**
+ * 登录核心服务
+ * 
+ * 最近修改：
+ * - 2025-01-07: 代码规范优化 - 清理未使用的导入(EmailSendResult, crypto)
+ * - 2025-01-07: 代码规范优化 - 修复常量命名(saltRounds -> SALT_ROUNDS)
+ * - 2025-01-07: 代码规范优化 - 删除未使用的私有方法(generateVerificationCode)
+ * - 2025-01-07: 代码质量提升 - 确保完全符合项目命名规范和注释规范
+ * 
+ * @author moyin
+ * @version 1.0.1
+ * @since 2025-12-17
+ * @lastModified 2025-01-07
+ */
+```
+
+### 案例4：代码审查场景

 #### 现有代码检查

@@ -380,6 +454,14 @@ AI 会生成包含完整注释和异常处理的代码。
 - 日志记录
 - 规范命名

+## 代码修改模板
+修改现有文件时，请：
+- 在文件头注释添加修改记录
+- 更新版本号（递增小版本号）
+- 添加 @lastModified 标记
+- 修改记录格式：YYYY-MM-DD: 修改类型 - 具体描述
+- 只保留最近5次修改记录，保持注释简洁
+
 ## 代码检查模板  
 请检查代码规范符合性：
 [保存检查清单]
@@ -397,6 +479,7 @@ AI 会生成包含完整注释和异常处理的代码。
 3. 异常处理模板
 4. 日志记录模板
 5. 参数验证模板
+6. 文件修改记录注释模板

 每个模板都要包含完整的注释和最佳实践。
 ```
--- a/docs/development/backend_development_guide.md
+++ b/docs/development/backend_development_guide.md
@@ -0,0 +1,505 @@
+# 后端开发规范指南
+
+本文档定义了后端开发的核心规范，包括注释规范、日志规范、业务逻辑规范等，确保代码质量和团队协作效率。
+
+## 📋 目录
+
+- [注释规范](#注释规范)
+- [日志规范](#日志规范)
+- [业务逻辑规范](#业务逻辑规范)
+- [异常处理规范](#异常处理规范)
+- [代码质量规范](#代码质量规范)
+- [最佳实践](#最佳实践)
+
+---
+
+## 📝 注释规范
+
+### 文件头注释
+
+每个 TypeScript 文件都必须包含完整的文件头注释：
+
+```typescript
+/**
+ * 文件功能描述
+ * 
+ * 功能描述：
+ * - 主要功能点1
+ * - 主要功能点2
+ * - 主要功能点3
+ * 
+ * 职责分离：
+ * - 职责描述1
+ * - 职责描述2
+ * 
+ * 最近修改：
+ * - YYYY-MM-DD: 修改类型 - 具体修改内容描述
+ * - YYYY-MM-DD: 修改类型 - 具体修改内容描述
+ * 
+ * @author 作者名
+ * @version x.x.x
+ * @since 创建日期
+ * @lastModified 最后修改日期
+ */
+```
+
+### 类注释
+
+```typescript
+/**
+ * 类功能描述
+ * 
+ * 职责：
+ * - 主要职责1
+ * - 主要职责2
+ * 
+ * 主要方法：
+ * - method1() - 方法1功能
+ * - method2() - 方法2功能
+ * 
+ * 使用场景：
+ * - 场景描述
+ */
+@Injectable()
+export class ExampleService {
+  // 类实现
+}
+```
+
+### 方法注释（三级注释标准）
+
+**必须包含以下三个级别的注释：**
+
+#### 1. 功能描述级别
+```typescript
+/**
+ * 用户登录验证
+ */
+```
+
+#### 2. 业务逻辑级别
+```typescript
+/**
+ * 用户登录验证
+ * 
+ * 业务逻辑：
+ * 1. 验证用户名或邮箱格式
+ * 2. 查找用户记录
+ * 3. 验证密码哈希值
+ * 4. 检查用户状态是否允许登录
+ * 5. 记录登录日志
+ * 6. 返回认证结果
+ */
+```
+
+#### 3. 技术实现级别
+```typescript
+/**
+ * 用户登录验证
+ * 
+ * 业务逻辑：
+ * 1. 验证用户名或邮箱格式
+ * 2. 查找用户记录
+ * 3. 验证密码哈希值
+ * 4. 检查用户状态是否允许登录
+ * 5. 记录登录日志
+ * 6. 返回认证结果
+ * 
+ * @param loginRequest 登录请求数据
+ * @returns 认证结果，包含用户信息和认证状态
+ * @throws UnauthorizedException 用户名或密码错误时
+ * @throws ForbiddenException 用户状态不允许登录时
+ * 
+ * @example
+ * ```typescript
+ * const result = await loginService.validateUser({
+ *   identifier: 'user@example.com',
+ *   password: 'password123'
+ * });
+ * ```
+ */
+async validateUser(loginRequest: LoginRequest): Promise<AuthResult> {
+  // 实现代码
+}
+```
+
+### 修改记录规范
+
+#### 修改类型定义
+
+- **代码规范优化** - 命名规范、注释规范、代码清理等
+- **功能新增** - 添加新的功能或方法
+- **功能修改** - 修改现有功能的实现
+- **Bug修复** - 修复代码缺陷
+- **性能优化** - 提升代码性能
+- **重构** - 代码结构调整但功能不变
+
+#### 修改记录格式
+
+```typescript
+/**
+ * 最近修改：
+ * - 2025-01-07: 代码规范优化 - 清理未使用的导入(EmailSendResult, crypto)
+ * - 2025-01-07: 代码规范优化 - 修复常量命名(saltRounds -> SALT_ROUNDS)
+ * - 2025-01-07: 功能新增 - 添加用户验证码登录功能
+ * - 2025-01-06: Bug修复 - 修复邮箱验证逻辑错误
+ * 
+ * @version 1.0.1 (修改后需要递增版本号)
+ * @lastModified 2025-01-07
+ */
+```
+
+#### 修改记录长度限制
+
+**重要：为保持文件头注释简洁，修改记录只保留最近的5次修改。**
+
+- ✅ **保留最新5条记录** - 便于快速了解最近变更
+- ✅ **超出时删除最旧记录** - 保持注释简洁
+- ✅ **重要修改可标注** - 重大版本更新可特别标注
+
+```typescript
+// ✅ 正确示例：保持最新5条记录
+/**
+ * 最近修改：
+ * - 2025-01-07: 功能新增 - 添加用户头像上传功能
+ * - 2025-01-06: Bug修复 - 修复邮箱验证逻辑错误  
+ * - 2025-01-05: 代码规范优化 - 统一异常处理格式
+ * - 2025-01-04: 功能修改 - 优化用户状态管理逻辑
+ * - 2025-01-03: 性能优化 - 优化数据库查询性能
+ * 
+ * @version 1.3.0
+ */
+
+// ❌ 错误示例：记录过多，注释冗长
+/**
+ * 最近修改：
+ * - 2025-01-07: 功能新增 - 添加用户头像上传功能
+ * - 2025-01-06: Bug修复 - 修复邮箱验证逻辑错误
+ * - 2025-01-05: 代码规范优化 - 统一异常处理格式
+ * - 2025-01-04: 功能修改 - 优化用户状态管理逻辑
+ * - 2025-01-03: 性能优化 - 优化数据库查询性能
+ * - 2025-01-02: 重构 - 重构用户认证逻辑
+ * - 2025-01-01: 功能新增 - 添加用户权限管理
+ * - 2024-12-31: Bug修复 - 修复登录超时问题
+ * // ... 更多记录导致注释过长
+ */
+```
+
+#### 版本号递增规则
+
+- **代码规范优化、Bug修复** → 修订版本 +1 (1.0.0 → 1.0.1)
+- **功能新增、功能修改** → 次版本 +1 (1.0.1 → 1.1.0)
+- **重构、架构变更** → 主版本 +1 (1.1.0 → 2.0.0)
+
+---
+
+## 📊 日志规范
+
+### 日志级别使用
+
+```typescript
+// ERROR - 系统错误，需要立即处理
+this.logger.error('用户登录失败', { userId, error: error.message });
+
+// WARN - 警告信息，需要关注但不影响系统运行
+this.logger.warn('用户多次登录失败', { userId, attemptCount });
+
+// INFO - 重要的业务操作记录
+this.logger.info('用户登录成功', { userId, loginTime: new Date() });
+
+// DEBUG - 调试信息，仅在开发环境使用
+this.logger.debug('验证用户密码', { userId, hashedPassword: '***' });
+```
+
+### 日志格式规范
+
+```typescript
+// ✅ 正确格式
+this.logger.info('操作描述', {
+  userId: 'user123',
+  action: 'login',
+  timestamp: new Date(),
+  metadata: { ip: '192.168.1.1' }
+});
+
+// ❌ 错误格式
+this.logger.info('用户登录');
+this.logger.info(`用户${userId}登录成功`);
+```
+
+---
+
+## 🏗️ 业务逻辑规范
+
+### 防御性编程
+
+```typescript
+async getUserById(userId: string): Promise<User> {
+  // 1. 参数验证
+  if (!userId) {
+    throw new BadRequestException('用户ID不能为空');
+  }
+
+  // 2. 业务逻辑验证
+  const user = await this.usersService.findOne(userId);
+  if (!user) {
+    throw new NotFoundException('用户不存在');
+  }
+
+  // 3. 状态检查
+  if (user.status === UserStatus.DELETED) {
+    throw new ForbiddenException('用户已被删除');
+  }
+
+  // 4. 返回结果
+  return user;
+}
+```
+
+### 业务逻辑分层
+
+```typescript
+// Controller 层 - 只处理HTTP请求和响应
+@Controller('users')
+export class UsersController {
+  @Get(':id')
+  async getUser(@Param('id') id: string) {
+    return this.usersService.getUserById(id);
+  }
+}
+
+// Service 层 - 处理业务逻辑
+@Injectable()
+export class UsersService {
+  async getUserById(id: string): Promise<User> {
+    // 业务逻辑实现
+    return this.usersCoreService.findUserById(id);
+  }
+}
+
+// Core 层 - 核心业务实现
+@Injectable()
+export class UsersCoreService {
+  async findUserById(id: string): Promise<User> {
+    // 核心逻辑实现
+  }
+}
+```
+
+---
+
+## ⚠️ 异常处理规范
+
+### 异常类型使用
+
+```typescript
+// 400 - 客户端请求错误
+throw new BadRequestException('参数格式错误');
+
+// 401 - 未授权
+throw new UnauthorizedException('用户名或密码错误');
+
+// 403 - 禁止访问
+throw new ForbiddenException('用户状态不允许此操作');
+
+// 404 - 资源不存在
+throw new NotFoundException('用户不存在');
+
+// 409 - 资源冲突
+throw new ConflictException('用户名已存在');
+
+// 500 - 服务器内部错误
+throw new InternalServerErrorException('系统内部错误');
+```
+
+### 异常处理模式
+
+```typescript
+async createUser(userData: CreateUserDto): Promise<User> {
+  try {
+    // 1. 参数验证
+    this.validateUserData(userData);
+    
+    // 2. 业务逻辑检查
+    await this.checkUserExists(userData.email);
+    
+    // 3. 执行创建操作
+    const user = await this.usersRepository.create(userData);
+    
+    // 4. 记录成功日志
+    this.logger.info('用户创建成功', { userId: user.id });
+    
+    return user;
+  } catch (error) {
+    // 5. 记录错误日志
+    this.logger.error('用户创建失败', {
+      userData: { ...userData, password: '***' },
+      error: error.message
+    });
+    
+    // 6. 重新抛出业务异常
+    if (error instanceof BadRequestException) {
+      throw error;
+    }
+    
+    // 7. 转换为系统异常
+    throw new InternalServerErrorException('用户创建失败');
+  }
+}
+```
+
+---
+
+## 🔍 代码质量规范
+
+### 代码检查清单
+
+在提交代码前，请确保：
+
+- [ ] **注释完整性**
+  - [ ] 文件头注释包含功能描述、修改记录、作者信息
+  - [ ] 类注释包含职责、主要方法、使用场景
+  - [ ] 方法注释包含三级注释（功能、业务逻辑、技术实现）
+  - [ ] 修改现有文件时添加了修改记录和更新版本号
+  - [ ] 修改记录只保留最近5次，保持注释简洁
+
+- [ ] **业务逻辑完整性**
+  - [ ] 所有参数都进行了验证
+  - [ ] 所有异常情况都进行了处理
+  - [ ] 关键操作都记录了日志
+  - [ ] 业务逻辑考虑了所有边界情况
+
+- [ ] **代码质量**
+  - [ ] 没有未使用的导入和变量
+  - [ ] 常量使用了正确的命名规范
+  - [ ] 方法长度合理（建议不超过50行）
+  - [ ] 单一职责原则，每个方法只做一件事
+
+- [ ] **安全性**
+  - [ ] 敏感信息不在日志中暴露
+  - [ ] 用户输入都进行了验证和清理
+  - [ ] 权限检查在适当的位置进行
+
+---
+
+## 💡 最佳实践
+
+### 1. 注释驱动开发
+
+```typescript
+/**
+ * 用户注册功能
+ * 
+ * 业务逻辑：
+ * 1. 验证邮箱格式和唯一性
+ * 2. 验证密码强度
+ * 3. 生成邮箱验证码
+ * 4. 创建用户记录
+ * 5. 发送验证邮件
+ * 6. 返回注册结果
+ * 
+ * @param registerData 注册数据
+ * @returns 注册结果
+ */
+async registerUser(registerData: RegisterDto): Promise<RegisterResult> {
+  // 先写注释，再写实现
+  // 这样确保逻辑清晰，不遗漏步骤
+}
+```
+
+### 2. 错误优先处理
+
+```typescript
+async processPayment(paymentData: PaymentDto): Promise<PaymentResult> {
+  // 1. 先处理所有可能的错误情况
+  if (!paymentData.amount || paymentData.amount <= 0) {
+    throw new BadRequestException('支付金额必须大于0');
+  }
+  
+  if (!paymentData.userId) {
+    throw new BadRequestException('用户ID不能为空');
+  }
+  
+  const user = await this.usersService.findOne(paymentData.userId);
+  if (!user) {
+    throw new NotFoundException('用户不存在');
+  }
+  
+  // 2. 再处理正常的业务逻辑
+  return this.executePayment(paymentData);
+}
+```
+
+### 3. 日志驱动调试
+
+```typescript
+async complexBusinessLogic(data: ComplexData): Promise<Result> {
+  this.logger.debug('开始执行复杂业务逻辑', { data });
+  
+  try {
+    // 步骤1
+    const step1Result = await this.step1(data);
+    this.logger.debug('步骤1完成', { step1Result });
+    
+    // 步骤2
+    const step2Result = await this.step2(step1Result);
+    this.logger.debug('步骤2完成', { step2Result });
+    
+    // 步骤3
+    const finalResult = await this.step3(step2Result);
+    this.logger.info('复杂业务逻辑执行成功', { finalResult });
+    
+    return finalResult;
+  } catch (error) {
+    this.logger.error('复杂业务逻辑执行失败', { data, error: error.message });
+    throw error;
+  }
+}
+```
+
+### 4. 版本管理最佳实践
+
+```typescript
+/**
+ * 用户服务
+ * 
+ * 最近修改：
+ * - 2025-01-07: 功能新增 - 添加用户头像上传功能 (v1.2.0)
+ * - 2025-01-06: Bug修复 - 修复邮箱验证逻辑错误 (v1.1.1)
+ * - 2025-01-05: 代码规范优化 - 统一异常处理格式 (v1.1.0)
+ * - 2025-01-04: 功能新增 - 添加用户状态管理 (v1.1.0)
+ * - 2025-01-03: 重构 - 重构用户认证逻辑 (v2.0.0)
+ * 
+ * @version 1.2.0
+ * @lastModified 2025-01-07
+ */
+```
+
+**修改记录管理原则：**
+- ✅ **保持简洁** - 只保留最近5次修改
+- ✅ **定期清理** - 超出5条时删除最旧记录
+- ✅ **重要标注** - 重大版本更新可特别标注版本号
+- ✅ **描述清晰** - 每条记录都要说明具体改动内容
+
+---
+
+## 🎯 总结
+
+遵循后端开发规范能够：
+
+1. **提高代码质量** - 通过完整的注释和规范的实现
+2. **提升团队效率** - 统一的规范减少沟通成本
+3. **降低维护成本** - 清晰的文档和日志便于问题定位
+4. **增强系统稳定性** - 完善的异常处理和防御性编程
+5. **促进知识传承** - 详细的修改记录和版本管理
+
+**记住：好的代码不仅要能运行，更要能被理解、维护和扩展。**
+
+---
+
+## 📚 相关文档
+
+- [命名规范](./naming_convention.md) - 代码命名规范
+- [NestJS 使用指南](./nestjs_guide.md) - 框架最佳实践
+- [Git 提交规范](./git_commit_guide.md) - 版本控制规范
+- [AI 辅助开发规范](./AI辅助开发规范指南.md) - AI 辅助开发指南
--- a/docs/development/developer_code_review_guide.md
+++ b/docs/development/developer_code_review_guide.md
--- a/docs/development/naming_convention.md
+++ b/docs/development/naming_convention.md
@@ -10,6 +10,7 @@
 - [常量命名](#常量命名)
 - [接口路由命名](#接口路由命名)
 - [TypeScript 特定规范](#typescript-特定规范)
+- [注释命名规范](#注释命名规范)
 - [命名示例](#命名示例)

 ## 文件和文件夹命名
@@ -331,6 +332,111 @@ class Repository<type, key> { }
@IsString({ message: 'name_must_be_string' })
 ```

+## 注释命名规范
+
+### 注释标签命名
+
+**规则：使用标准JSDoc标签**
+
+```typescript
+✅ 正确示例：
+@param userId 用户ID
+@returns 用户信息
+@throws NotFoundException 用户不存在时
+@author moyin
+@version 1.0.0
+@since 2025-01-07
+@lastModified 2025-01-07
+
+❌ 错误示例：
+@参数 userId 用户ID
+@返回 用户信息
+@异常 NotFoundException 用户不存在时
+@作者 moyin
+```
+
+### 修改记录命名
+
+**规则：使用标准化的修改类型**
+
+```typescript
+✅ 正确示例：
+- 2025-01-07: 代码规范优化 - 清理未使用的导入
+- 2025-01-07: 功能新增 - 添加用户验证功能
+- 2025-01-07: Bug修复 - 修复登录验证逻辑
+- 2025-01-07: 性能优化 - 优化数据库查询
+- 2025-01-07: 重构 - 重构用户服务架构
+
+❌ 错误示例：
+- 2025-01-07: 修改 - 改了一些代码
+- 2025-01-07: 更新 - 更新了功能
+- 2025-01-07: 优化 - 优化了性能
+- 2025-01-07: 调整 - 调整了结构
+```
+
+**📏 长度限制：修改记录只保留最近5次修改，保持文件头注释简洁。**
+
+### 注释内容命名
+
+**规则：使用清晰描述性的中文**
+
+```typescript
+✅ 正确示例：
+/** 用户唯一标识符 */
+userId: string;
+
+/** 用户邮箱地址，用于登录和通知 */
+email: string;
+
+/** 用户状态：active-激活, inactive-未激活, banned-已封禁 */
+status: UserStatus;
+
+/**
+ * 验证用户登录凭据
+ * 
+ * 业务逻辑：
+ * 1. 验证用户名或邮箱格式
+ * 2. 查找用户记录
+ * 3. 验证密码哈希值
+ * 4. 检查用户状态
+ */
+
+❌ 错误示例：
+/** id */
+userId: string;
+
+/** 邮箱 */
+email: string;
+
+/** 状态 */
+status: UserStatus;
+
+/**
+ * 登录
+ */
+```
+
+### 版本号命名规范
+
+**规则：使用语义化版本号**
+
+```typescript
+✅ 正确示例：
+@version 1.0.0    // 主版本.次版本.修订版本
+@version 1.2.3    // 功能更新
+@version 2.0.0    // 重大更新
+
+修改时版本递增规则：
+- 代码规范优化、Bug修复 → 修订版本 +1 (1.0.0 → 1.0.1)
+- 功能新增、功能修改 → 次版本 +1 (1.0.1 → 1.1.0)
+- 重构、架构变更 → 主版本 +1 (1.1.0 → 2.0.0)
+
+❌ 错误示例：
+@version v1        // 缺少详细版本号
+@version 1         // 格式不规范
+@version latest    // 不明确的版本标识
+```
+
 ## 命名示例

 ### 完整的模块示例
@@ -483,6 +589,11 @@ export class CreatePlayerDto {
 - [ ] 函数名清晰表达其功能
 - [ ] 布尔变量使用 is/has/can 前缀
 - [ ] 避免使用无意义的缩写
+- [ ] 注释使用标准JSDoc标签
+- [ ] 修改记录使用标准化修改类型
+- [ ] 版本号遵循语义化版本规范
+- [ ] 修改现有文件时添加了修改记录和更新版本号
+- [ ] 修改记录只保留最近5次，保持注释简洁

 ## 工具配置

--- a/docs/development/nestjs_guide.md
+++ b/docs/development/nestjs_guide.md
@@ -11,6 +11,7 @@
 - [WebSocket 实时通信](#websocket-实时通信)
 - [数据验证](#数据验证)
 - [异常处理](#异常处理)
+- [注释规范](#注释规范)

 ## 核心概念

@@ -453,6 +454,142 @@ export class RoomController {
 7. **日志记录**：使用内置 Logger 或集成第三方日志库
 8. **测试**：编写单元测试和 E2E 测试

+## 注释规范
+
+### 文件头注释
+
+每个 TypeScript 文件都应该包含完整的文件头注释：
+
+```typescript
+/**
+ * 文件功能描述
+ * 
+ * 功能描述：
+ * - 主要功能点1
+ * - 主要功能点2
+ * - 主要功能点3
+ * 
+ * 职责分离：
+ * - 职责描述1
+ * - 职责描述2
+ * 
+ * 最近修改：
+ * - YYYY-MM-DD: 修改类型 - 具体修改内容描述
+ * - YYYY-MM-DD: 修改类型 - 具体修改内容描述
+ * 
+ * @author 作者名
+ * @version x.x.x
+ * @since 创建日期
+ * @lastModified 最后修改日期
+ */
+```
+
+### 类注释
+
+```typescript
+/**
+ * 类功能描述
+ * 
+ * 职责：
+ * - 主要职责1
+ * - 主要职责2
+ * 
+ * 主要方法：
+ * - method1() - 方法1功能
+ * - method2() - 方法2功能
+ * 
+ * 使用场景：
+ * - 场景描述
+ */
+@Injectable()
+export class ExampleService {
+  // 类实现
+}
+```
+
+### 方法注释
+
+```typescript
+/**
+ * 方法功能描述
+ * 
+ * 业务逻辑：
+ * 1. 步骤1描述
+ * 2. 步骤2描述
+ * 3. 步骤3描述
+ * 
+ * @param param1 参数1描述
+ * @param param2 参数2描述
+ * @returns 返回值描述
+ * @throws ExceptionType 异常情况描述
+ * 
+ * @example
+ * ```typescript
+ * const result = await service.methodName(param1, param2);
+ * ```
+ */
+async methodName(param1: string, param2: number): Promise<ResultType> {
+  // 方法实现
+}
+```
+
+### 接口注释
+
+```typescript
+/**
+ * 接口功能描述
+ */
+export interface ExampleInterface {
+  /** 字段1描述 */
+  field1: string;
+  
+  /** 字段2描述 */
+  field2: number;
+  
+  /** 可选字段描述 */
+  optionalField?: boolean;
+}
+```
+
+### 修改记录规范
+
+当修改现有文件时，必须在文件头注释中添加修改记录：
+
+#### 修改类型定义
+
+- **代码规范优化** - 命名规范、注释规范、代码清理等
+- **功能新增** - 添加新的功能或方法
+- **功能修改** - 修改现有功能的实现
+- **Bug修复** - 修复代码缺陷
+- **性能优化** - 提升代码性能
+- **重构** - 代码结构调整但功能不变
+
+#### 修改记录格式
+
+```typescript
+/**
+ * 最近修改：
+ * - 2025-01-07: 代码规范优化 - 清理未使用的导入(EmailSendResult, crypto)
+ * - 2025-01-07: 代码规范优化 - 修复常量命名(saltRounds -> SALT_ROUNDS)
+ * - 2025-01-07: 功能新增 - 添加用户验证码登录功能
+ * - 2025-01-06: Bug修复 - 修复邮箱验证逻辑错误
+ * 
+ * @version 1.0.1 (修改后需要递增版本号)
+ * @lastModified 2025-01-07
+ */
+```
+
+**📏 修改记录长度限制：只保留最近5次修改，超出时删除最旧记录，保持注释简洁。**
+
+### 注释最佳实践
+
+1. **保持更新**：修改代码时同步更新注释
+2. **描述意图**：注释应该说明"为什么"而不只是"做什么"
+3. **业务逻辑**：复杂的业务逻辑必须有详细的步骤说明
+4. **异常处理**：明确说明可能抛出的异常和处理方式
+5. **示例代码**：复杂方法提供使用示例
+6. **版本管理**：修改文件时必须更新修改记录和版本号
+
 ## 更多资源

 - [NestJS 官方文档](https://docs.nestjs.com/)