# 认证管理模块 API 文档

> **文档版本**: v1.0
> **创建日期**: 2026-06-16
> **作者**: 张翔
> **状态**: 正式发布

---

## 目录

1. [概述](#概述)
2. [基础路径](#基础路径)
3. [认证接口](#认证接口)
   - [用户名+密码登录](#用户名密码登录)
   - [获取用户信息](#获取用户信息)
4. [数据模型](#数据模型)
   - [LoginRequest](#loginrequest)
   - [LoginResponse](#loginresponse)
   - [UserInfo](#userinfo)
5. [响应码说明](#响应码说明)

---

## 概述

认证管理模块提供用户登录认证和用户信息查询功能。采用 Spring WebFlux 响应式编程，支持高并发场景。

## 基础路径

所有接口的基础路径为: `http://{host}:{port}/api/auth`

---

## 认证接口

### 用户名+密码登录

| 属性 | 值 |
|------|-----|
| **HTTP方法** | POST |
| **接口路径** | `/api/auth/login` |
| **所属文件** | `AuthHandler.java` |

**请求参数**:

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| username | string | 是 | - | 用户名 |
| password | string | 是 | - | 密码 |

**成功响应** (200 OK):

```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 7200,
    "userInfo": {
      "id": 1,
      "username": "admin",
      "email": "admin@example.com",
      "phone": "13800138000",
      "nickname": "超级管理员",
      "status": 1,
      "roleId": 1
    }
  }
}
```

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

```json
{
  "code": 400,
  "message": "用户名或密码错误"
}
```

---

### 获取用户信息

| 属性 | 值 |
|------|-----|
| **HTTP方法** | GET |
| **接口路径** | `/api/auth/users/{id}` |
| **所属文件** | `AuthHandler.java` |

**路径参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Long | 是 | 用户ID |

**成功响应** (200 OK):

```json
{
  "code": 200,
  "message": "获取用户信息成功",
  "data": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "phone": "13800138000",
    "nickname": "超级管理员",
    "status": 1,
    "roleId": 1
  }
}
```

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

```json
{
  "code": 400,
  "message": "无效的用户ID"
}
```

---

## 数据模型

### LoginRequest

用户登录请求对象。

| 字段 | 类型 | 必填 | 说明 | 示例 |
|------|------|------|------|------|
| username | string | 是 | 用户名 | admin |
| password | string | 是 | 密码 | Test@123 |

### LoginResponse

用户登录响应对象。

| 字段 | 类型 | 说明 | 示例 |
|------|------|------|------|
| accessToken | string | 访问令牌 | eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... |
| refreshToken | string | 刷新令牌 | eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... |
| tokenType | string | 令牌类型 | Bearer |
| expiresIn | Long | 过期时间（秒） | 7200 |
| userInfo | UserInfo | 用户信息 | - |

### UserInfo

用户信息对象。

| 字段 | 类型 | 说明 | 示例 |
|------|------|------|------|
| id | Long | 用户ID | 1 |
| username | string | 用户名 | admin |
| email | string | 邮箱 | admin@example.com |
| phone | string | 手机号 | 13800138000 |
| nickname | string | 昵称 | 超级管理员 |
| status | Integer | 状态：0-禁用，1-正常 | 1 |
| roleId | Long | 角色ID | 1 |

---

## 响应码说明

| 响应码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误（如用户名密码错误、无效的用户ID） |
| 401 | 未授权（认证失败） |
| 403 | 禁止访问 |
| 404 | 资源未找到 |
| 409 | 冲突（如重复数据） |
| 500 | 服务器内部错误 |

---

## 业务规则

1. 登录成功后返回的 `accessToken` 用于后续接口的身份认证
2. `accessToken` 有效期为 2 小时（7200 秒）
3. `refreshToken` 用于刷新 `accessToken`，有效期为 7 天
4. 用户状态 `status` 为 0 时表示禁用，无法登录
5. 所有需要认证的接口需要在请求头中携带 `Authorization: Bearer {accessToken}`