docs: 更新API文档，反映HTTP状态码修复

文档更新内容： - 更新注册接口响应示例，区分400和409状态码 - 添加资源冲突响应示例（用户名、邮箱、手机号已存在） - 完善OpenAPI文档，添加详细的响应示例 - 更新错误码表格，明确不同错误的状态码 - 添加HTTP状态码测试场景修复说明： - 409 Conflict：用户名/邮箱/手机号已存在 - 400 Bad Request：验证码错误/参数格式错误 - 符合RESTful API规范测试验证： - 邮箱冲突：HTTP 409 - 用户名冲突：HTTP 409 - 验证码错误：HTTP 400 前端开发者现在可以： - 根据HTTP状态码进行精确的错误处理 - 移除临时解决方案，使用标准状态码判断 - 提供更好的用户体验和错误提示
2025-12-25 16:32:51 +08:00
parent 8a19bb7daa
commit aae77866ac
2 changed files with 137 additions and 7 deletions
--- a/docs/api/api-documentation.md
+++ b/docs/api/api-documentation.md
@@ -339,6 +339,26 @@

 **失败响应** (400):

+**验证码错误**:
+```json
+{
+  "success": false,
+  "message": "验证码不存在或已过期",
+  "error_code": "REGISTER_FAILED"
+}
+```
+
+**参数格式错误**:
+```json
+{
+  "success": false,
+  "message": "密码必须包含字母和数字，长度8-128字符",
+  "error_code": "REGISTER_FAILED"
+}
+```
+
+**冲突响应** (409):
+
 **用户名已存在**:
 ```json
 {
@@ -366,6 +386,15 @@
 }
 ```

+**手机号已存在**:
+```json
+{
+  "success": false,
+  "message": "手机号已存在",
+  "error_code": "REGISTER_FAILED"
+}
+```
+
 **邮箱验证码相关错误**:
 ```json
 {
@@ -1455,7 +1484,7 @@ const cleanupTestData = async () => {
 | 错误代码 | HTTP状态码 | 说明 | 触发条件 |
 |----------|------------|------|----------|
 | LOGIN_FAILED | 401 | 登录失败 | 用户名不存在、密码错误、账户被锁定 |
-| REGISTER_FAILED | 400/409 | 注册失败 | 用户名已存在、密码强度不足、验证码错误 |
+| REGISTER_FAILED | 400/409 | 注册失败 | 验证码错误(400)、用户名已存在(409)、邮箱已存在(409) |
 | GITHUB_OAUTH_FAILED | 401 | GitHub OAuth失败 | GitHub认证信息无效 |
 | SEND_CODE_FAILED | 400 | 发送验证码失败 | 邮箱格式错误、发送服务异常 |
 | RESET_PASSWORD_FAILED | 400 | 重置密码失败 | 验证码无效、密码强度不足 |
@@ -1929,6 +1958,9 @@ MAINTENANCE_RETRY_AFTER=1800
   - 调试接口：`POST /auth/debug-verification-code` 可获取验证码详情
 4. **用户ID**: 修改密码接口中的user_id应从JWT令牌中获取，而不是从请求体中传递
 5. **错误处理**: 建议在客户端实现适当的错误处理和用户提示
+   - 409 Conflict：资源冲突（用户名、邮箱、手机号已存在）
+   - 400 Bad Request：请求参数错误（验证码错误、格式错误）
+   - 根据HTTP状态码进行不同的错误处理逻辑
 6. **限流**: 建议对登录、注册等接口实施限流策略
 7. **管理员权限**: 
   - 管理员接口需要 role=9 的用户权限
@@ -2060,7 +2092,67 @@ const testLoginFailures = async () => {
 };
 ```

-#### **4. 频率限制测试**
+#### **4. 注册冲突HTTP状态码测试**
+```javascript
+// 场景：测试注册冲突的正确HTTP状态码
+const testRegistrationConflicts = async () => {
+  // 用户名冲突 - 应返回409
+  try {
+    await fetch('/auth/register', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        username: 'existinguser',
+        password: 'Test123456',
+        nickname: '测试用户',
+        email: 'newemail@example.com',
+        email_verification_code: '123456'
+      })
+    });
+  } catch (error) {
+    expect(error.status).toBe(409); // Conflict
+    expect(error.message).toContain('用户名已存在');
+  }
+  
+  // 邮箱冲突 - 应返回409
+  try {
+    await fetch('/auth/register', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        username: 'newuser',
+        password: 'Test123456',
+        nickname: '测试用户',
+        email: 'existing@example.com',
+        email_verification_code: '123456'
+      })
+    });
+  } catch (error) {
+    expect(error.status).toBe(409); // Conflict
+    expect(error.message).toContain('邮箱已存在');
+  }
+  
+  // 验证码错误 - 应返回400
+  try {
+    await fetch('/auth/register', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        username: 'newuser',
+        password: 'Test123456',
+        nickname: '测试用户',
+        email: 'new@example.com',
+        email_verification_code: '999999'
+      })
+    });
+  } catch (error) {
+    expect(error.status).toBe(400); // Bad Request
+    expect(error.message).toContain('验证码');
+  }
+};
+```
+
+#### **5. 频率限制测试**
 ```javascript
 // 场景：验证码发送频率限制
 const testRateLimit = async () => {
@@ -2087,7 +2179,7 @@ const testRateLimit = async () => {
 };
 ```

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

-#### **6. 用户状态影响登录**
+#### **7. 用户状态影响登录**
 ```javascript
 // 场景：不同用户状态的登录测试
 const testUserStatusLogin = async () => {
@@ -2294,11 +2386,17 @@ echo "📈 性能测试完成，请查看上述结果"
    - 添加发送登录验证码接口 (POST /auth/send-login-verification-code)
    - 支持邮箱和手机号验证码登录
    - 完善验证码相关错误处理和限流机制
+  - **修复HTTP状态码问题**
+    - 用户注册冲突错误：400 → 409 Conflict
+    - 用户名已存在：返回409状态码
+    - 邮箱已存在：返回409状态码
+    - 手机号已存在：返回409状态码
+    - 符合RESTful API规范
  - **文档完善**
    - 更新API文档，新增验证码登录相关说明
    - 修正错误码与实际响应的一致性
    - 添加验证码登录测试场景和使用示例
-    - 更新OpenAPI规范文档
+    - 更新OpenAPI规范文档，完善响应示例
  - **接口数量更新**：21个 → 23个API接口
  - **用户认证接口**：11个 → 13个接口
 - **v1.0.0** (2025-12-24):