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

- 新增验证码登录接口文档 (POST /auth/verification-code-login) - 新增发送登录验证码接口文档 (POST /auth/send-login-verification-code) - 更新接口列表和数量统计 (21个 -> 23个接口) - 添加验证码登录测试场景和cURL示例 - 完善错误码说明和响应格式 - 确保文档与当前实现完全一致
2025-12-25 15:44:37 +08:00
parent 9ad98f74d9
commit 68debdcb40
7 changed files with 396 additions and 391 deletions
--- a/docs/api/api-documentation.md
+++ b/docs/api/api-documentation.md
@@ -36,6 +36,8 @@

 ### 2. 用户认证接口 (Auth)
 - `POST /auth/login` - 用户登录
+- `POST /auth/verification-code-login` - 验证码登录
+- `POST /auth/send-login-verification-code` - 发送登录验证码
 - `POST /auth/register` - 用户注册
 - `POST /auth/github` - GitHub OAuth登录
 - `POST /auth/forgot-password` - 发送密码重置验证码
@@ -156,6 +158,123 @@
 }
 ```

+#### 1.1 验证码登录
+
+**接口地址**: `POST /auth/verification-code-login`
+
+**功能描述**: 使用邮箱或手机号和验证码进行登录，无需密码
+
+#### 请求参数
+
+```json
+{
+  "identifier": "test@example.com",
+  "verification_code": "123456"
+}
+```
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| identifier | string | 是 | 登录标识符（邮箱或手机号） |
+| verification_code | string | 是 | 6位数字验证码 |
+
+#### 响应示例
+
+**成功响应** (200):
+```json
+{
+  "success": true,
+  "data": {
+    "user": {
+      "id": "1",
+      "username": "testuser",
+      "nickname": "测试用户",
+      "email": "test@example.com",
+      "phone": "+8613800138000",
+      "avatar_url": "https://example.com/avatar.jpg",
+      "role": 1,
+      "created_at": "2025-12-17T10:00:00.000Z"
+    },
+    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+    "is_new_user": false,
+    "message": "验证码登录成功"
+  },
+  "message": "验证码登录成功"
+}
+```
+
+**失败响应** (401):
+```json
+{
+  "success": false,
+  "message": "验证码错误或已过期",
+  "error_code": "VERIFICATION_CODE_INVALID"
+}
+```
+
+**可能的错误码**:
+- `VERIFICATION_CODE_INVALID`: 验证码错误或已过期
+- `USER_NOT_FOUND`: 用户不存在
+- `EMAIL_NOT_VERIFIED`: 邮箱未验证（邮箱登录时）
+- `INVALID_IDENTIFIER`: 无效的邮箱或手机号格式
+
+#### 1.2 发送登录验证码
+
+**接口地址**: `POST /auth/send-login-verification-code`
+
+**功能描述**: 向用户邮箱或手机发送登录验证码
+
+#### 请求参数
+
+```json
+{
+  "identifier": "test@example.com"
+}
+```
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| identifier | string | 是 | 邮箱或手机号 |
+
+#### 响应示例
+
+**成功响应** (200):
+```json
+{
+  "success": true,
+  "message": "验证码发送成功",
+  "data": {
+    "sent_to": "test@example.com",
+    "expires_in": 300
+  }
+}
+```
+
+**测试模式响应** (206):
+```json
+{
+  "success": false,
+  "message": "测试模式：验证码已生成但未真实发送",
+  "error_code": "TEST_MODE_ONLY",
+  "data": {
+    "verification_code": "123456",
+    "sent_to": "test@example.com",
+    "expires_in": 300,
+    "is_test_mode": true
+  }
+}
+```
+
+**失败响应** (404):
+```json
+{
+  "success": false,
+  "message": "用户不存在",
+  "error_code": "USER_NOT_FOUND"
+}
+```
+
 #### 2. 用户注册

 **接口地址**: `POST /auth/register`
@@ -1565,6 +1684,21 @@ curl -X POST http://localhost:3000/auth/login \
    "password": "password123"
  }'

+# 发送登录验证码
+curl -X POST http://localhost:3000/auth/send-login-verification-code \
+  -H "Content-Type: application/json" \
+  -d '{
+    "identifier": "test@example.com"
+  }'
+
+# 验证码登录
+curl -X POST http://localhost:3000/auth/verification-code-login \
+  -H "Content-Type: application/json" \
+  -d '{
+    "identifier": "test@example.com",
+    "verification_code": "123456"
+  }'
+
 # 发送邮箱验证码
 curl -X POST http://localhost:3000/auth/send-email-verification \
  -H "Content-Type: application/json" \
@@ -1846,7 +1980,42 @@ const testCompleteRegistration = async () => {
 };
 ```

-#### **2. 登录失败处理**
+#### **2. 验证码登录完整流程**
+```javascript
+// 场景：验证码登录完整流程
+const testVerificationCodeLogin = async () => {
+  const email = 'test@example.com';
+  
+  // Step 1: 发送登录验证码
+  const codeResponse = await fetch('/auth/send-login-verification-code', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ identifier: email })
+  });
+  
+  expect(codeResponse.status).toBe(206); // 测试模式
+  const codeData = await codeResponse.json();
+  expect(codeData.success).toBe(false);
+  expect(codeData.error_code).toBe('TEST_MODE_ONLY');
+  
+  // Step 2: 使用验证码登录
+  const loginResponse = await fetch('/auth/verification-code-login', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      identifier: email,
+      verification_code: codeData.data.verification_code
+    })
+  });
+  
+  expect(loginResponse.status).toBe(200);
+  const loginData = await loginResponse.json();
+  expect(loginData.success).toBe(true);
+  expect(loginData.data.access_token).toBeDefined();
+};
+```
+
+#### **3. 登录失败处理**
 ```javascript
 // 场景：各种登录失败情况
 const testLoginFailures = async () => {
@@ -1882,7 +2051,7 @@ const testLoginFailures = async () => {
 };
 ```

-#### **3. 频率限制测试**
+#### **4. 频率限制测试**
 ```javascript
 // 场景：验证码发送频率限制
 const testRateLimit = async () => {
@@ -1909,7 +2078,7 @@ const testRateLimit = async () => {
 };
 ```

-#### **4. 管理员权限测试**
+#### **5. 管理员权限测试**
 ```javascript
 // 场景：管理员权限验证
 const testAdminPermissions = async () => {
@@ -1939,7 +2108,7 @@ const testAdminPermissions = async () => {
 };
 ```

-#### **5. 用户状态影响登录**
+#### **6. 用户状态影响登录**
 ```javascript
 // 场景：不同用户状态的登录测试
 const testUserStatusLogin = async () => {
@@ -2119,7 +2288,7 @@ echo "📈 性能测试完成，请查看上述结果"
    - **更新限流配置**：注册接口限制调整为10次/5分钟（开发环境）
  - **应用状态接口** (1个)
    - `GET /` - 获取应用状态
-  - **用户认证接口** (11个)
+  - **用户认证接口** (13个)
    - 用户登录、注册、GitHub OAuth
    - 密码重置和修改功能
    - 邮箱验证相关接口
@@ -2142,7 +2311,7 @@ echo "📈 性能测试完成，请查看上述结果"
    - 请求超时拦截器 (Request Timeout)
    - 用户状态检查和权限控制
    - **修复**：HTTP状态码现在正确反映业务执行结果
-  - **总计接口数量**: 21个API接口
+  - **总计接口数量**: 23个API接口
  - 完善错误代码和使用示例
  - 修复路由冲突问题
  - 确保文档与实际测试效果一致