lty/qy_lty/docs/user_authentication_api.md

# 用户认证API文档

本文档详细说明了系统提供的用户认证相关API，包括注册、登录、密码重置等功能。

## 基础URL

所有用户认证相关的API都在以下基础路径下：

```
/api/user/auth/
```

## API概览

| 接口路径 | 方法 | 描述 |
|---------|------|------|
| `/api/user/auth/register/` | POST | 用户名注册 |
| `/api/user/auth/username/login/` | POST | 用户名密码登录 |
| `/api/user/auth/email/login/` | POST | 邮箱密码登录 |
| `/api/user/auth/phone/login/` | POST | 手机验证码登录 |
| `/api/user/auth/phone/verify/` | POST | 发送手机验证码 |
| `/api/user/auth/login/` | POST | 标准登录接口(dj_rest_auth) |
| `/api/user/auth/logout/` | POST | 登出 |
| `/api/user/auth/password/reset/` | POST | 密码重置 |
| `/api/user/auth/password/reset/confirm/` | POST | 密码重置确认 |
| `/api/user/auth/user/` | GET | 获取当前用户信息 |
| `/api/user/info/` | GET | 获取当前用户详细信息 |

## 详细API说明

### 用户名注册

```
POST /api/user/auth/register/
```

使用用户名和密码创建新用户账号。

**请求参数：**

| 参数名 | 类型 | 必填 | 描述 |
|-------|-----|------|-----|
| username | string | 是 | 用户名 |
| password1 | string | 是 | 密码 |
| password2 | string | 是 | 确认密码 |
| email | string | 否 | 邮箱 |
| phone_number | string | 否 | 手机号码 |

**响应示例：**

```json
{
  "status": "success",
  "code": 200,
  "message": "User registered successfully"
}
```

### 用户名密码登录

```
POST /api/user/auth/username/login/
```

使用用户名和密码进行登录。

**请求参数：**

| 参数名 | 类型 | 必填 | 描述 |
|-------|-----|------|-----|
| username | string | 是 | 用户名 |
| password | string | 是 | 密码 |

**响应示例：**

```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

### 邮箱密码登录

```
POST /api/user/auth/email/login/
```

使用邮箱和密码进行登录。

**请求参数：**

| 参数名 | 类型 | 必填 | 描述 |
|-------|-----|------|-----|
| email | string | 是 | 邮箱 |
| password | string | 是 | 密码 |

**响应示例：**

```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

### 手机验证码登录

```
POST /api/user/auth/phone/login/
```

使用手机号和验证码进行登录。

**请求参数：**

| 参数名 | 类型 | 必填 | 描述 |
|-------|-----|------|-----|
| phone_number | string | 是 | 手机号码 |
| code | string | 是 | 验证码 |

**响应示例：**

```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

### 发送手机验证码

```
POST /api/user/auth/phone/verify/
```

向指定手机号发送验证码。

**请求参数：**

| 参数名 | 类型 | 必填 | 描述 |
|-------|-----|------|-----|
| phone_number | string | 是 | 手机号码 |

**响应示例：**

```json
{
  "message": "Verification code sent."
}
```

### 获取用户信息（标准）

```
GET /api/user/auth/user/
```

获取当前登录用户的基本信息。

**安全说明：**
- 不返回密码和敏感权限信息
- 只有经过认证的用户可以访问

**请求头：**

需要包含认证令牌：

```
Authorization: Bearer {token}
```

**响应示例：**

```json
{
  "id": 1,
  "username": "example_user",
  "email": "user@example.com",
  "phone_number": "13800138000",
  "first_name": "",
  "last_name": ""
}
```

### 获取用户详细信息

```
GET /api/user/info/
```

返回当前登录用户的详细信息。

**安全说明：**
- 不返回密码和敏感权限信息
- 只有经过认证的用户可以访问

**请求头：**

需要包含认证令牌：

```
Authorization: Bearer {token}
```

**响应示例：**

```json
{
  "status": "success",
  "code": 200,
  "data": {
    "id": 1,
    "username": "example_user",
    "email": "user@example.com",
    "phone_number": "13800138000",
    "date_joined": "2023-01-01T00:00:00Z",
    "last_login": "2023-01-02T10:30:00Z",
    "first_name": "",
    "last_name": "",
    "is_active": true
  }
}
```

## 错误响应

所有API可能返回以下错误：

**400 Bad Request**

```json
{
  "error": "具体错误信息"
}
```

**401 Unauthorized**

```json
{
  "detail": "认证失败信息"
}
```

**403 Forbidden**

```json
{
  "detail": "权限错误信息"
}
```

## 认证方式

系统支持以下认证方式：

1. **Token认证**：在请求头中添加 `Authorization: Bearer {token}`
2. **Session认证**：适用于浏览器访问