# 忘记密码接口文档

## 概述

本文档描述用户侧忘记密码功能的 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. **验证码使用后自动失效**: 重置成功后验证码立即失效，无法重复使用