docs: 完善API文档，添加验证码登录功能说明

- 新增验证码登录接口文档 (POST /auth/verification-code-login)
- 新增发送登录验证码接口文档 (POST /auth/send-login-verification-code)
- 更新接口列表和数量统计 (21个 -> 23个接口)
- 添加验证码登录测试场景和cURL示例
- 完善错误码说明和响应格式
- 确保文档与当前实现完全一致

src/core/db/users/users.service.spec.ts

@@ -231,7 +231,7 @@ describe('Users Entity, DTO and Service Tests', () => {
       it('应该在用户名重复时抛出ConflictException', async () => {
         mockRepository.findOne.mockResolvedValue(mockUser); // 模拟用户名已存在
 
-        await expect(service.create(createUserDto)).rejects.toThrow(ConflictException);
+        await expect(service.createWithDuplicateCheck(createUserDto)).rejects.toThrow(ConflictException);
         expect(mockRepository.save).not.toHaveBeenCalled();
       });
 

src/core/login_core/login_core.service.spec.ts

@@ -264,82 +264,6 @@ describe('LoginCoreService', () => {
     });
   });
 
-  describe('verificationCodeLogin', () => {
-    it('should successfully login with email verification code', async () => {
-      const verifiedUser = { ...mockUser, email_verified: true };
-      usersService.findByEmail.mockResolvedValue(verifiedUser);
-      verificationService.verifyCode.mockResolvedValue(true);
-
-      const result = await service.verificationCodeLogin({
-        identifier: 'test@example.com',
-        verificationCode: '123456'
-      });
-
-      expect(result.user).toEqual(verifiedUser);
-      expect(result.isNewUser).toBe(false);
-      expect(verificationService.verifyCode).toHaveBeenCalledWith(
-        'test@example.com',
-        VerificationCodeType.EMAIL_VERIFICATION,
-        '123456'
-      );
-    });
-
-    it('should successfully login with phone verification code', async () => {
-      const phoneUser = { ...mockUser, phone: '+8613800138000' };
-      usersService.findAll.mockResolvedValue([phoneUser]);
-      verificationService.verifyCode.mockResolvedValue(true);
-
-      const result = await service.verificationCodeLogin({
-        identifier: '+8613800138000',
-        verificationCode: '123456'
-      });
-
-      expect(result.user).toEqual(phoneUser);
-      expect(result.isNewUser).toBe(false);
-      expect(verificationService.verifyCode).toHaveBeenCalledWith(
-        '+8613800138000',
-        VerificationCodeType.SMS_VERIFICATION,
-        '123456'
-      );
-    });
-
-    it('should reject unverified email user', async () => {
-      usersService.findByEmail.mockResolvedValue(mockUser); // email_verified: false
-
-      await expect(service.verificationCodeLogin({
-        identifier: 'test@example.com',
-        verificationCode: '123456'
-      })).rejects.toThrow('邮箱未验证，请先验证邮箱后再使用验证码登录');
-    });
-
-    it('should reject non-existent user', async () => {
-      usersService.findByEmail.mockResolvedValue(null);
-
-      await expect(service.verificationCodeLogin({
-        identifier: 'nonexistent@example.com',
-        verificationCode: '123456'
-      })).rejects.toThrow('用户不存在，请先注册账户');
-    });
-
-    it('should reject invalid verification code', async () => {
-      const verifiedUser = { ...mockUser, email_verified: true };
-      usersService.findByEmail.mockResolvedValue(verifiedUser);
-      verificationService.verifyCode.mockResolvedValue(false);
-
-      await expect(service.verificationCodeLogin({
-        identifier: 'test@example.com',
-        verificationCode: '999999'
-      })).rejects.toThrow('验证码验证失败');
-    });
-
-    it('should reject invalid identifier format', async () => {
-      await expect(service.verificationCodeLogin({
-        identifier: 'invalid-identifier',
-        verificationCode: '123456'
-      })).rejects.toThrow('请提供有效的邮箱或手机号');
-    });
-  });
-
   describe('sendLoginVerificationCode', () => {
     it('should successfully send email login verification code', async () => {
       const verifiedUser = { ...mockUser, email_verified: true };
@@ -468,55 +392,79 @@ describe('LoginCoreService', () => {
     });
   });
 
-  describe('sendLoginVerificationCode', () => {
-    it('should successfully send email login verification code', async () => {
+  describe('verificationCodeLogin', () => {
+    it('should successfully login with email verification code', async () => {
       const verifiedUser = { ...mockUser, email_verified: true };
       usersService.findByEmail.mockResolvedValue(verifiedUser);
-      verificationService.generateCode.mockResolvedValue('123456');
-      emailService.sendVerificationCode.mockResolvedValue({
-        success: true,
-        isTestMode: false
+      verificationService.verifyCode.mockResolvedValue(true);
+
+      const result = await service.verificationCodeLogin({
+        identifier: 'test@example.com',
+        verificationCode: '123456'
       });
 
-      const result = await service.sendLoginVerificationCode('test@example.com');
-
-      expect(result.code).toBe('123456');
-      expect(result.isTestMode).toBe(false);
-      expect(emailService.sendVerificationCode).toHaveBeenCalledWith({
-        email: 'test@example.com',
-        code: '123456',
-        nickname: mockUser.nickname,
-        purpose: 'login_verification'
-      });
+      expect(result.user).toEqual(verifiedUser);
+      expect(result.isNewUser).toBe(false);
+      expect(verificationService.verifyCode).toHaveBeenCalledWith(
+        'test@example.com',
+        VerificationCodeType.EMAIL_VERIFICATION,
+        '123456'
+      );
     });
 
-    it('should return verification code in test mode', async () => {
-      const verifiedUser = { ...mockUser, email_verified: true };
-      usersService.findByEmail.mockResolvedValue(verifiedUser);
-      verificationService.generateCode.mockResolvedValue('123456');
-      emailService.sendVerificationCode.mockResolvedValue({
-        success: true,
-        isTestMode: true
+    it('should successfully login with phone verification code', async () => {
+      const phoneUser = { ...mockUser, phone: '+8613800138000' };
+      usersService.findAll.mockResolvedValue([phoneUser]);
+      verificationService.verifyCode.mockResolvedValue(true);
+
+      const result = await service.verificationCodeLogin({
+        identifier: '+8613800138000',
+        verificationCode: '123456'
       });
 
-      const result = await service.sendLoginVerificationCode('test@example.com');
-
-      expect(result.code).toBe('123456');
-      expect(result.isTestMode).toBe(true);
+      expect(result.user).toEqual(phoneUser);
+      expect(result.isNewUser).toBe(false);
+      expect(verificationService.verifyCode).toHaveBeenCalledWith(
+        '+8613800138000',
+        VerificationCodeType.SMS_VERIFICATION,
+        '123456'
+      );
     });
 
-    it('should reject unverified email', async () => {
+    it('should reject unverified email user', async () => {
       usersService.findByEmail.mockResolvedValue(mockUser); // email_verified: false
 
-      await expect(service.sendLoginVerificationCode('test@example.com'))
-        .rejects.toThrow('邮箱未验证，无法使用验证码登录');
+      await expect(service.verificationCodeLogin({
+        identifier: 'test@example.com',
+        verificationCode: '123456'
+      })).rejects.toThrow('邮箱未验证，请先验证邮箱后再使用验证码登录');
     });
 
     it('should reject non-existent user', async () => {
       usersService.findByEmail.mockResolvedValue(null);
 
-      await expect(service.sendLoginVerificationCode('nonexistent@example.com'))
-        .rejects.toThrow('用户不存在');
+      await expect(service.verificationCodeLogin({
+        identifier: 'nonexistent@example.com',
+        verificationCode: '123456'
+      })).rejects.toThrow('用户不存在，请先注册账户');
+    });
+
+    it('should reject invalid verification code', async () => {
+      const verifiedUser = { ...mockUser, email_verified: true };
+      usersService.findByEmail.mockResolvedValue(verifiedUser);
+      verificationService.verifyCode.mockResolvedValue(false);
+
+      await expect(service.verificationCodeLogin({
+        identifier: 'test@example.com',
+        verificationCode: '999999'
+      })).rejects.toThrow('验证码验证失败');
+    });
+
+    it('should reject invalid identifier format', async () => {
+      await expect(service.verificationCodeLogin({
+        identifier: 'invalid-identifier',
+        verificationCode: '123456'
+      })).rejects.toThrow('请提供有效的邮箱或手机号');
     });
   });
 });

src/core/login_core/login_core.service.ts

@@ -757,7 +757,7 @@ export class LoginCoreService {
         email: identifier,
         code: verificationCode,
         nickname: user.nickname,
-        purpose: 'password_reset'
+        purpose: 'login_verification'
       });
 
       if (!result.success) {

src/core/utils/email/email.service.ts

@@ -47,7 +47,7 @@ export interface VerificationEmailOptions {
   /** 用户昵称 */
   nickname?: string;
   /** 验证码用途 */
-  purpose: 'email_verification' | 'password_reset';
+  purpose: 'email_verification' | 'password_reset' | 'login_verification';
 }
 
 /**
@@ -167,9 +167,15 @@ export class EmailService {
     if (purpose === 'email_verification') {
       subject = '【Whale Town】邮箱验证码';
       template = this.getEmailVerificationTemplate(code, nickname);
-    } else {
+    } else if (purpose === 'password_reset') {
       subject = '【Whale Town】密码重置验证码';
       template = this.getPasswordResetTemplate(code, nickname);
+    } else if (purpose === 'login_verification') {
+      subject = '【Whale Town】登录验证码';
+      template = this.getPasswordResetTemplate(code, nickname); // 复用密码重置模板
+    } else {
+      subject = '【Whale Town】验证码';
+      template = this.getEmailVerificationTemplate(code, nickname);
     }
 
     return await this.sendEmail({