备份

2026-03-25 20:48:00 +08:00
parent 40447f86f6
commit e379f9dee6
8 changed files with 626 additions and 11 deletions
@@ -0,0 +1,154 @@
+# 忘记密码接口文档
+
+## 概述
+
+本文档描述用户侧忘记密码功能的 API 接口，供前端对接使用。
+
+---
+
+## 接口列表
+
+| 接口 | 方法 | 路径 | 说明 |
+|------|------|------|------|
+| 发送验证码 | POST | `/api/auth/forgot-password/send-code` | 发送密码重置验证码到邮箱 |
+| 重置密码 | POST | `/api/auth/forgot-password/reset` | 验证验证码并重置密码 |
+
+---
+
+## 1. 发送密码重置验证码
+
+### 请求
+
+```
+POST /api/auth/forgot-password/send-code
+Content-Type: application/json
+```
+
+### 入参
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| email | string | 是 | 注册时使用的邮箱地址 |
+
+### 请求示例
+
+```json
+{
+    "email": "user@example.com"
+}
+```
+
+### 出参
+
+#### 成功响应 (200)
+
+```json
+{
+    "success": true,
+    "data": null,
+    "message": "验证码已发送到您的邮箱，请查收"
+}
+```
+
+#### 错误响应
+
+| HTTP 状态码 | 错误信息 | 说明 |
+|-------------|----------|------|
+| 404 | 该邮箱未注册 | 邮箱不存在 |
+| 429 | 请等待X秒后再重新发送验证码 | 发送频率限制（60秒内只能发送一次） |
+| 500 | 验证码发送失败，请稍后重试 | 服务器错误 |
+
+---
+
+## 2. 重置密码
+
+### 请求
+
+```
+POST /api/auth/forgot-password/reset
+Content-Type: application/json
+```
+
+### 入参
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| email | string | 是 | 注册时使用的邮箱地址 |
+| verification_code | string | 是 | 6位数字验证码 |
+| new_password | string | 是 | 新密码，至少8个字符 |
+
+### 请求示例
+
+```json
+{
+    "email": "user@example.com",
+    "verification_code": "123456",
+    "new_password": "newPassword123"
+}
+```
+
+### 出参
+
+#### 成功响应 (200)
+
+```json
+{
+    "success": true,
+    "data": null,
+    "message": "密码重置成功，请使用新密码登录"
+}
+```
+
+#### 错误响应
+
+| HTTP 状态码 | 错误信息 | 说明 |
+|-------------|----------|------|
+| 400 | 验证码错误或已过期 | 验证码无效 |
+| 404 | 该邮箱未注册 | 邮箱不存在 |
+| 422 | 验证错误 | 参数格式不正确（如密码少于8位） |
+
+---
+
+## 前端对接流程
+
+```
+┌─────────────────┐
+│  忘记密码页面    │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  输入邮箱地址    │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐     POST /api/auth/forgot-password/send-code
+│  点击发送验证码  │ ──────────────────────────────────────────────►
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  输入验证码      │
+│  输入新密码      │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐     POST /api/auth/forgot-password/reset
+│  点击重置密码    │ ──────────────────────────────────────────────►
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  跳转到登录页面  │
+└─────────────────┘
+```
+
+---
+
+## 注意事项
+
+1. **验证码有效期**: 10 分钟
+2. **发送频率限制**: 同一邮箱 60 秒内只能发送一次
+3. **密码要求**: 至少 8 个字符
+4. **验证码格式**: 6 位数字
+5. **验证码使用后自动失效**: 重置成功后验证码立即失效，无法重复使用