Merge pull request 'feature/verification-code-login-v1.1.0' (#24) from feature/verification-code-login-v1.1.0 into main

Reviewed-on: datawhale/whale-town-end#24
2025-12-25 16:19:23 +08:00
parent 8d5a44d985 9f606abbb2
commit a8e29c6a46
5 changed files with 551 additions and 8 deletions
--- a/docs/api/api-documentation.md
+++ b/docs/api/api-documentation.md
@@ -2288,6 +2288,19 @@ echo "📈 性能测试完成，请查看上述结果"

 这些测试场景和边界条件将帮助前端开发者进行全面的API测试，确保应用的稳定性和安全性。

+- **v1.1.0** (2025-12-25): 
+  - **新增验证码登录功能**
+    - 添加验证码登录接口 (POST /auth/verification-code-login)
+    - 添加发送登录验证码接口 (POST /auth/send-login-verification-code)
+    - 支持邮箱和手机号验证码登录
+    - 完善验证码相关错误处理和限流机制
+  - **文档完善**
+    - 更新API文档，新增验证码登录相关说明
+    - 修正错误码与实际响应的一致性
+    - 添加验证码登录测试场景和使用示例
+    - 更新OpenAPI规范文档
+  - **接口数量更新**：21个 → 23个API接口
+  - **用户认证接口**：11个 → 13个接口
 - **v1.0.0** (2025-12-24): 
  - **完整的API文档更新**
    - 重新整理接口分类，将用户管理接口独立分类
--- a/docs/api/openapi.yaml
+++ b/docs/api/openapi.yaml
@@ -1,8 +1,8 @@
 openapi: 3.0.3
 info:
  title: Pixel Game Server - Auth API
-  description: 像素游戏服务器用户认证API接口文档
-  version: 1.0.0
+  description: 像素游戏服务器用户认证API接口文档 - 包含验证码登录功能
+  version: 1.1.0
  contact:
    name: API Support
    email: support@example.com
@@ -15,10 +15,39 @@ servers:
    description: 开发环境

 tags:
+  - name: app
+    description: 应用状态相关接口
  - name: auth
    description: 用户认证相关接口
+  - name: admin
+    description: 管理员后台相关接口
+  - name: user-management
+    description: 用户管理相关接口

 paths:
+  /:
+    get:
+      tags:
+        - app
+      summary: 获取应用状态
+      description: 返回应用的基本运行状态信息，用于健康检查和监控
+      operationId: getAppStatus
+      responses:
+        '200':
+          description: 应用状态获取成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AppStatusResponse'
+              example:
+                service: Pixel Game Server
+                version: 1.0.0
+                status: running
+                timestamp: "2025-12-25T08:00:00.000Z"
+                uptime: 3600
+                environment: development
+                storage_mode: database
+
  /auth/login:
    post:
      tags:
@@ -259,8 +288,280 @@ paths:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

+  /auth/send-email-verification:
+    post:
+      tags:
+        - auth
+      summary: 发送邮箱验证码
+      description: 向指定邮箱发送验证码
+      operationId: sendEmailVerification
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SendEmailVerificationDto'
+            example:
+              email: test@example.com
+      responses:
+        '200':
+          description: 验证码发送成功（真实发送模式）
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EmailVerificationResponse'
+        '206':
+          description: 测试模式：验证码已生成但未真实发送
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TestModeEmailVerificationResponse'
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: 发送频率过高
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ThrottleErrorResponse'
+
+  /auth/verify-email:
+    post:
+      tags:
+        - auth
+      summary: 验证邮箱验证码
+      description: 使用验证码验证邮箱
+      operationId: verifyEmail
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/EmailVerificationDto'
+            example:
+              email: test@example.com
+              verification_code: "123456"
+      responses:
+        '200':
+          description: 邮箱验证成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CommonResponse'
+        '400':
+          description: 验证码错误或已过期
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
+  /auth/resend-email-verification:
+    post:
+      tags:
+        - auth
+      summary: 重新发送邮箱验证码
+      description: 重新向指定邮箱发送验证码
+      operationId: resendEmailVerification
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SendEmailVerificationDto'
+            example:
+              email: test@example.com
+      responses:
+        '200':
+          description: 验证码重新发送成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EmailVerificationResponse'
+        '206':
+          description: 测试模式：验证码已生成但未真实发送
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TestModeEmailVerificationResponse'
+        '400':
+          description: 邮箱已验证或用户不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: 发送频率过高
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ThrottleErrorResponse'
+
+  /auth/verification-code-login:
+    post:
+      tags:
+        - auth
+      summary: 验证码登录
+      description: 使用邮箱或手机号和验证码进行登录，无需密码
+      operationId: verificationCodeLogin
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/VerificationCodeLoginDto'
+            example:
+              identifier: test@example.com
+              verification_code: "123456"
+      responses:
+        '200':
+          description: 验证码登录成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LoginResponse'
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          description: 验证码错误或已过期
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VerificationCodeLoginErrorResponse'
+        '404':
+          description: 用户不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
+  /auth/send-login-verification-code:
+    post:
+      tags:
+        - auth
+      summary: 发送登录验证码
+      description: 向用户邮箱或手机发送登录验证码
+      operationId: sendLoginVerificationCode
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SendLoginVerificationCodeDto'
+            example:
+              identifier: test@example.com
+      responses:
+        '200':
+          description: 验证码发送成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EmailVerificationResponse'
+        '206':
+          description: 测试模式：验证码已生成但未真实发送
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TestModeEmailVerificationResponse'
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: 用户不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SendLoginCodeErrorResponse'
+        '429':
+          description: 发送频率过高
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ThrottleErrorResponse'
+
+  /auth/debug-verification-code:
+    post:
+      tags:
+        - auth
+      summary: 调试验证码信息
+      description: 获取验证码的详细调试信息（仅开发环境）
+      operationId: debugVerificationCode
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SendEmailVerificationDto'
+            example:
+              email: test@example.com
+      responses:
+        '200':
+          description: 调试信息获取成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DebugVerificationCodeResponse'
+
+  /auth/debug-clear-throttle:
+    post:
+      tags:
+        - auth
+      summary: 清除限流记录
+      description: 清除所有限流记录（仅开发环境使用）
+      operationId: clearThrottle
+      responses:
+        '200':
+          description: 限流记录已清除
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CommonResponse'
+
 components:
  schemas:
+    AppStatusResponse:
+      type: object
+      properties:
+        service:
+          type: string
+          description: 服务名称
+          example: Pixel Game Server
+        version:
+          type: string
+          description: 版本号
+          example: 1.0.0
+        status:
+          type: string
+          description: 运行状态
+          example: running
+        timestamp:
+          type: string
+          format: date-time
+          description: 当前时间戳
+          example: "2025-12-25T08:00:00.000Z"
+        uptime:
+          type: integer
+          description: 运行时间（秒）
+          example: 3600
+        environment:
+          type: string
+          description: 运行环境
+          example: development
+        storage_mode:
+          type: string
+          description: 存储模式
+          example: database
+
    LoginDto:
      type: object
      required:
@@ -415,6 +716,64 @@ components:
          pattern: '^(?=.*[a-zA-Z])(?=.*\d)'
          example: newpassword123

+    SendEmailVerificationDto:
+      type: object
+      required:
+        - email
+      properties:
+        email:
+          type: string
+          format: email
+          description: 邮箱地址
+          example: test@example.com
+
+    EmailVerificationDto:
+      type: object
+      required:
+        - email
+        - verification_code
+      properties:
+        email:
+          type: string
+          format: email
+          description: 邮箱地址
+          example: test@example.com
+        verification_code:
+          type: string
+          description: 6位数字验证码
+          pattern: '^\d{6}$'
+          example: "123456"
+
+    VerificationCodeLoginDto:
+      type: object
+      required:
+        - identifier
+        - verification_code
+      properties:
+        identifier:
+          type: string
+          description: 登录标识符（邮箱或手机号）
+          minLength: 1
+          maxLength: 100
+          example: test@example.com
+        verification_code:
+          type: string
+          description: 6位数字验证码
+          pattern: '^\d{6}$'
+          example: "123456"
+
+    SendLoginVerificationCodeDto:
+      type: object
+      required:
+        - identifier
+      properties:
+        identifier:
+          type: string
+          description: 邮箱或手机号
+          minLength: 1
+          maxLength: 100
+          example: test@example.com
+
    UserInfo:
      type: object
      properties:
@@ -565,4 +924,175 @@ components:
        error_code:
          type: string
          description: 错误代码
-          example: OPERATION_FAILED
+          example: OPERATION_FAILED
+
+    EmailVerificationResponse:
+      type: object
+      properties:
+        success:
+          type: boolean
+          description: 请求是否成功
+          example: true
+        data:
+          type: object
+          properties:
+            sent_to:
+              type: string
+              description: 发送目标
+              example: test@example.com
+            expires_in:
+              type: integer
+              description: 过期时间（秒）
+              example: 300
+            is_test_mode:
+              type: boolean
+              description: 是否为测试模式
+              example: false
+        message:
+          type: string
+          description: 响应消息
+          example: 验证码已发送，请查收邮件
+
+    TestModeEmailVerificationResponse:
+      type: object
+      properties:
+        success:
+          type: boolean
+          description: 请求是否成功
+          example: false
+        data:
+          type: object
+          properties:
+            verification_code:
+              type: string
+              description: 验证码（仅测试模式）
+              example: "123456"
+            sent_to:
+              type: string
+              description: 发送目标
+              example: test@example.com
+            expires_in:
+              type: integer
+              description: 过期时间（秒）
+              example: 300
+            is_test_mode:
+              type: boolean
+              description: 是否为测试模式
+              example: true
+        message:
+          type: string
+          description: 响应消息
+          example: 测试模式：验证码已生成但未真实发送
+        error_code:
+          type: string
+          description: 错误代码
+          example: TEST_MODE_ONLY
+
+    VerificationCodeLoginErrorResponse:
+      type: object
+      properties:
+        success:
+          type: boolean
+          description: 请求是否成功
+          example: false
+        message:
+          type: string
+          description: 错误消息
+          example: 验证码错误或已过期
+        error_code:
+          type: string
+          description: 错误代码
+          example: VERIFICATION_CODE_LOGIN_FAILED
+
+    SendLoginCodeErrorResponse:
+      type: object
+      properties:
+        success:
+          type: boolean
+          description: 请求是否成功
+          example: false
+        message:
+          type: string
+          description: 错误消息
+          example: 用户不存在
+        error_code:
+          type: string
+          description: 错误代码
+          example: SEND_LOGIN_CODE_FAILED
+
+    ThrottleErrorResponse:
+      type: object
+      properties:
+        success:
+          type: boolean
+          description: 请求是否成功
+          example: false
+        message:
+          type: string
+          description: 错误消息
+          example: 请求过于频繁，请稍后再试
+        error_code:
+          type: string
+          description: 错误代码
+          example: TOO_MANY_REQUESTS
+        throttle_info:
+          type: object
+          properties:
+            limit:
+              type: integer
+              description: 限制次数
+              example: 1
+            window_seconds:
+              type: integer
+              description: 时间窗口（秒）
+              example: 60
+            current_requests:
+              type: integer
+              description: 当前请求次数
+              example: 1
+            reset_time:
+              type: string
+              format: date-time
+              description: 重置时间
+              example: "2025-12-25T08:01:00.000Z"
+
+    DebugVerificationCodeResponse:
+      type: object
+      properties:
+        success:
+          type: boolean
+          description: 请求是否成功
+          example: true
+        data:
+          type: object
+          properties:
+            key:
+              type: string
+              description: Redis键名
+              example: verification_code:email_verification:test@example.com
+            exists:
+              type: boolean
+              description: 是否存在
+              example: true
+            ttl:
+              type: integer
+              description: 剩余生存时间（秒）
+              example: 290
+            rawData:
+              type: string
+              description: 原始数据
+              example: '{"code":"123456","createdAt":1766649341250}'
+            parsedData:
+              type: object
+              description: 解析后的数据
+              properties:
+                code:
+                  type: string
+                  example: "123456"
+                createdAt:
+                  type: integer
+                  example: 1766649341250
+            currentTime:
+              type: integer
+              description: 当前时间戳
+              example: 1766649341250
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
  "name": "pixel-game-server",
-  "version": "1.0.0",
-  "description": "A 2D pixel art game server built with NestJS",
+  "version": "1.1.0",
+  "description": "A 2D pixel art game server built with NestJS - 支持验证码登录功能",
  "main": "dist/main.js",
  "scripts": {
    "dev": "nest start --watch",
--- a/src/app.service.ts
+++ b/src/app.service.ts
@@ -31,7 +31,7 @@ export class AppService {
    
    return {
      service: 'Pixel Game Server',
-      version: '1.0.0',
+      version: '1.1.0',
      status: 'running',
      timestamp: new Date().toISOString(),
      uptime: Math.floor((Date.now() - this.startTime) / 1000),
--- a/src/main.ts
+++ b/src/main.ts
@@ -58,8 +58,8 @@ async function bootstrap() {
  // 配置Swagger文档
  const config = new DocumentBuilder()
    .setTitle('Pixel Game Server API')
-    .setDescription('像素游戏服务器API文档 - 包含用户认证、登录注册等功能')
-    .setVersion('1.0.0')
+    .setDescription('像素游戏服务器API文档 - 包含用户认证、登录注册、验证码登录等功能')
+    .setVersion('1.1.0')
    .addTag('auth', '用户认证相关接口')
    .addTag('admin', '管理员后台相关接口')
    .addBearerAuth(