From 7385c63ffd4fa8c3d58066f0d2297bbb6c72d084 Mon Sep 17 00:00:00 2001 From: moyin <244344649@qq.com> Date: Thu, 25 Dec 2025 16:11:07 +0800 Subject: [PATCH 1/2] =?UTF-8?q?feat(docs):=20=E6=9B=B4=E6=96=B0OpenAPI?= =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=8C=E6=B7=BB=E5=8A=A0=E9=AA=8C=E8=AF=81?= =?UTF-8?q?=E7=A0=81=E7=99=BB=E5=BD=95=E5=92=8C=E5=AE=8C=E6=95=B4=E6=8E=A5?= =?UTF-8?q?=E5=8F=A3=E5=AE=9A=E4=B9=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 添加验证码登录接口：/auth/verification-code-login - 添加发送登录验证码接口：/auth/send-login-verification-code - 添加邮箱验证相关接口：send/verify/resend-email-verification - 添加调试接口：debug-verification-code, debug-clear-throttle - 添加应用状态接口：GET / - 完善所有Schema定义和响应格式 - 添加测试模式和限流错误响应 - 确保OpenAPI文档与实际API完全匹配 --- docs/api/openapi.yaml | 532 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 531 insertions(+), 1 deletion(-) diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml index 7151c11..e4774d3 100644 --- a/docs/api/openapi.yaml +++ b/docs/api/openapi.yaml @@ -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 \ No newline at end of file + 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 \ No newline at end of file From 9f606abbb2f010d45e5b38deb2ef59d18d4ac75f Mon Sep 17 00:00:00 2001 From: moyin <244344649@qq.com> Date: Thu, 25 Dec 2025 16:15:52 +0800 Subject: [PATCH 2/2] =?UTF-8?q?chore:=20=E5=8D=87=E7=BA=A7=E7=89=88?= =?UTF-8?q?=E6=9C=AC=E5=88=B01.1.0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 版本升级：1.0.0 1.1.0 新功能： - 验证码登录功能完整实现 - 支持邮箱和手机号验证码登录 - 新增2个API接口（总计23个） 文档更新： - Swagger API文档版本更新 - OpenAPI规范文档更新 - 手动API文档版本更新 - 添加v1.1.0版本更新日志 技术改进： - 完善验证码相关错误处理 - 优化API响应格式一致性 - 增强测试覆盖率 更新内容： - package.json: 1.0.0 1.1.0 - Swagger配置: 1.0.0 1.1.0 - OpenAPI文档: 1.0.0 1.1.0 - 应用状态接口: 1.0.0 1.1.0 - API文档: 添加v1.1.0更新日志 --- docs/api/api-documentation.md | 13 +++++++++++++ docs/api/openapi.yaml | 4 ++-- package.json | 4 ++-- src/app.service.ts | 2 +- src/main.ts | 4 ++-- 5 files changed, 20 insertions(+), 7 deletions(-) diff --git a/docs/api/api-documentation.md b/docs/api/api-documentation.md index 457b3d2..26c7ec1 100644 --- 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文档更新** - 重新整理接口分类，将用户管理接口独立分类 diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml index e4774d3..3235acc 100644 --- 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 diff --git a/package.json b/package.json index 9c60e3a..1e8e2ab 100644 --- 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", diff --git a/src/app.service.ts b/src/app.service.ts index ef9dea5..7b1ca9a 100644 --- 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), diff --git a/src/main.ts b/src/main.ts index a917c46..ccdb0a0 100644 --- 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(