From ac989fe98581cb9328a6134cf2c506417f322de0 Mon Sep 17 00:00:00 2001
From: moyin <244344649@qq.com>
Date: Mon, 12 Jan 2026 19:21:30 +0800
Subject: [PATCH] =?UTF-8?q?style(verification):=20=E6=B7=BB=E5=8A=A0?=
 =?UTF-8?q?=E7=B1=BB=E6=B3=A8=E9=87=8A=EF=BC=8C=E5=AE=8C=E5=96=84=E4=BB=A3?=
 =?UTF-8?q?=E7=A0=81=E8=A7=84=E8=8C=83?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

范围：src/core/utils/verification/
- 为VerificationService添加完整的类注释，包含职责、主要方法和使用场景说明
- 为VerificationModule添加完整的类注释，包含模块职责和功能说明
- 更新文件修改记录和版本号（1.0.1  1.0.2）
- 更新@lastModified时间戳为2026-01-12
---
 .../utils/verification/verification.module.ts | 23 +++++++++++++--
 .../verification/verification.service.ts      | 28 +++++++++++++++++--
 2 files changed, 47 insertions(+), 4 deletions(-)

diff --git a/src/core/utils/verification/verification.module.ts b/src/core/utils/verification/verification.module.ts
index b7050e6..4d1af7d 100644
--- a/src/core/utils/verification/verification.module.ts
+++ b/src/core/utils/verification/verification.module.ts
@@ -11,12 +11,13 @@
  * - 服务提供者注册和导出
  * 
  * 最近修改：
+ * - 2026-01-12: 代码规范优化 - 添加VerificationModule类注释，完善模块职责说明 (修改者: moyin)
  * - 2026-01-07: 代码规范优化 - 完善文件头注释和修改记录规范
  * 
  * @author moyin
- * @version 1.0.1
+ * @version 1.0.2
  * @since 2025-12-17
- * @lastModified 2026-01-07
+ * @lastModified 2026-01-12
  */
 
 import { Module } from '@nestjs/common';
@@ -24,6 +25,24 @@ import { ConfigModule } from '@nestjs/config';
 import { VerificationService } from './verification.service';
 import { RedisModule } from '../../redis/redis.module';
 
+/**
+ * 验证码服务模块
+ * 
+ * 职责：
+ * - 配置和提供验证码服务的模块依赖
+ * - 集成Redis模块和配置服务
+ * - 导出VerificationService供其他模块使用
+ * - 管理验证码相关的依赖注入配置
+ * 
+ * 主要功能：
+ * - 模块依赖管理：导入ConfigModule和RedisModule
+ * - 服务提供者注册：注册VerificationService
+ * - 服务导出：使VerificationService可被其他模块注入
+ * 
+ * 使用场景：
+ * - 在需要验证码功能的业务模块中导入
+ * - 为登录、注册、密码重置等功能提供验证码支持
+ */
 @Module({
   imports: [ConfigModule, RedisModule],
   providers: [VerificationService],
diff --git a/src/core/utils/verification/verification.service.ts b/src/core/utils/verification/verification.service.ts
index 084f85e..f8c18bc 100644
--- a/src/core/utils/verification/verification.service.ts
+++ b/src/core/utils/verification/verification.service.ts
@@ -17,13 +17,14 @@
  * - 手机短信验证码
  * 
  * 最近修改：
+ * - 2026-01-12: 代码规范优化 - 添加VerificationService类注释，完善职责和方法说明 (修改者: moyin)
  * - 2026-01-07: 代码规范优化 - 清理未使用的导入(ConfigService)和多余空行
  * - 2026-01-07: 代码规范优化 - 完善文件头注释和修改记录规范
  * 
  * @author moyin
- * @version 1.0.1
+ * @version 1.0.2
  * @since 2025-12-17
- * @lastModified 2026-01-07
+ * @lastModified 2026-01-12
  */
 
 import { Injectable, Logger, BadRequestException, HttpException, HttpStatus, Inject } from '@nestjs/common';
@@ -52,6 +53,29 @@ export interface VerificationCodeInfo {
   maxAttempts: number;
 }
 
+/**
+ * 验证码管理服务
+ * 
+ * 职责：
+ * - 生成和管理各种类型的验证码（邮箱、密码重置、短信）
+ * - 提供验证码验证和尝试次数控制机制
+ * - 实现防刷机制和频率限制功能
+ * - 管理Redis缓存中的验证码存储和过期
+ * 
+ * 主要方法：
+ * - generateCode() - 生成指定类型的验证码
+ * - verifyCode() - 验证用户输入的验证码
+ * - codeExists() - 检查验证码是否存在
+ * - deleteCode() - 删除指定验证码
+ * - getCodeTTL() - 获取验证码剩余时间
+ * - clearCooldown() - 清除发送冷却时间
+ * 
+ * 使用场景：
+ * - 用户注册时的邮箱验证
+ * - 密码重置流程的安全验证
+ * - 短信验证码的生成和校验
+ * - 防止验证码恶意刷取和暴力破解
+ */
 @Injectable()
 export class VerificationService {
   private readonly logger = new Logger(VerificationService.name);