# 登录API

<cite>
**Referenced Files in This Document**   
- [kami-api-sys-user-login-v1-user-login-req.ts](file://src/api/generated/models/kami-api-sys-user-login-v1-user-login-req.ts)
- [kami-api-sys-user-login-v1-user-login-res.ts](file://src/api/generated/models/kami-api-sys-user-login-v1-user-login-res.ts)
- [default-api.ts](file://src/api/generated/apis/default-api.ts)
- [user.ts](file://src/api/user.ts)
- [interceptor.ts](file://src/api/interceptor.ts)
- [auth.ts](file://src/utils/auth.ts)
</cite>

## 目录

1. [简介](#简介)
2. [API端点详情](#api端点详情)
3. [请求参数和结构](#请求参数和结构)
4. [响应数据模型](#响应数据模型)
5. [成功和失败响应示例](#成功和失败响应示例)
6. [请求拦截器集成](#请求拦截器集成)
7. [API调用示例](#api调用示例)
8. [登录安全机制](#登录安全机制)
9. [结论](#结论)

## 简介

本文档详细介绍了kami_frontend项目中的用户登录API。该API是系统身份验证的核心组件，负责处理用户认证流程，包括用户名和密码验证、验证码检查以及双因素认证（2FA）支持。登录成功后，API返回认证令牌，用于后续的授权请求。本文档将全面介绍登录API的HTTP方法、URL路径、请求参数、响应数据模型、错误处理机制以及与前端请求拦截器的集成方式。

**Section sources**

- [kami-api-sys-user-login-v1-user-login-req.ts](file://src/api/generated/models/kami-api-sys-user-login-v1-user-login-req.ts)
- [kami-api-sys-user-login-v1-user-login-res.ts](file://src/api/generated/models/kami-api-sys-user-login-v1-user-login-res.ts)

## API端点详情

用户登录API通过HTTP POST请求访问，其端点路径为`/api/user/login`。该端点是无状态的，每次请求都需要提供完整的认证信息。API设计遵循RESTful原则，使用标准的HTTP状态码来指示请求结果。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "登录API"
participant Auth as "认证服务"
Client->>API : POST /api/user/login
API->>Auth : 验证凭据
Auth-->>API : 认证结果
API->>Client : 返回认证令牌
```

**Diagram sources**

- [user.ts](file://src/api/user.ts#L15-L20)
- [default-api.ts](file://src/api/generated/apis/default-api.ts#L27370-L27377)

**Section sources**

- [user.ts](file://src/api/user.ts#L15-L20)
- [default-api.ts](file://src/api/generated/apis/default-api.ts#L27370-L27377)

## 请求参数和结构

登录API的请求体采用JSON格式，包含以下字段：

| 字段名       | 类型   | 必需 | 描述                 |
| :----------- | :----- | :--- | :------------------- |
| `username`   | 字符串 | 是   | 用户名               |
| `password`   | 字符串 | 是   | 密码（已Base64加密） |
| `verifyCode` | 字符串 | 是   | 图形验证码           |
| `verifyKey`  | 字符串 | 是   | 验证码密钥           |
| `totpCode`   | 字符串 | 否   | TOTP双因素认证码     |

请求体结构由`KamiApiSysUserLoginV1UserLoginReq`接口定义，确保了类型安全和数据完整性。

```mermaid
classDiagram
class KamiApiSysUserLoginV1UserLoginReq {
+string username
+string password
+string verifyCode
+string verifyKey
+string? totpCode
}
```

**Diagram sources**

- [kami-api-sys-user-login-v1-user-login-req.ts](file://src/api/generated/models/kami-api-sys-user-login-v1-user-login-req.ts#L19-L50)

**Section sources**

- [kami-api-sys-user-login-v1-user-login-req.ts](file://src/api/generated/models/kami-api-sys-user-login-v1-user-login-req.ts#L19-L50)

## 响应数据模型

登录成功时，API返回一个包含认证令牌的JSON对象。响应数据模型由`KamiApiSysUserLoginV1UserLoginRes`接口定义，其主要包含一个可选的`token`字段。

| 字段名  | 类型   | 描述        |
| :------ | :----- | :---------- |
| `token` | 字符串 | JWT认证令牌 |

```mermaid
classDiagram
class KamiApiSysUserLoginV1UserLoginRes {
+string? token
}
```

**Diagram sources**

- [kami-api-sys-user-login-v1-user-login-res.ts](file://src/api/generated/models/kami-api-sys-user-login-v1-user-login-res.ts#L19-L26)

**Section sources**

- [kami-api-sys-user-login-v1-user-login-res.ts](file://src/api/generated/models/kami-api-sys-user-login-v1-user-login-res.ts#L19-L26)

## 成功和失败响应示例

### 成功响应示例

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

### 失败响应示例

当登录失败时，API返回标准的错误响应格式，包含错误码和消息：

```json
{
  "status": 401,
  "message": "用户名或密码错误",
  "code": 5001,
  "data": null
}
```

常见的错误码包括：

- `5001`: 用户名或密码错误
- `5002`: 验证码错误
- `5003`: 账户被禁用

**Section sources**

- [interceptor.ts](file://src/api/interceptor.ts#L60-L80)

## 请求拦截器集成

登录API与前端请求拦截器紧密集成，实现了认证令牌的自动管理。在`interceptor.ts`文件中，axios拦截器被配置为在每个请求的头部自动添加`Authorization`字段。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Interceptor as "请求拦截器"
participant API as "API服务"
Client->>Interceptor : 发起API请求
Interceptor->>Interceptor : 从localStorage获取令牌
Interceptor->>API : 添加Authorization头部并发送请求
API-->>Client : 返回响应
```

**Diagram sources**

- [interceptor.ts](file://src/api/interceptor.ts#L25-L45)

**Section sources**

- [interceptor.ts](file://src/api/interceptor.ts#L25-L45)

## API调用示例

### 使用axios调用

```typescript
import { login } from '@/api/user';

const loginData = {
  username: 'example_user',
  password: 'example_password',
  verifyCode: '1234',
  verifyKey: 'captcha_key',
  totpCode: '654321'
};

try {
  const response = await login(loginData);
  console.log('登录成功:', response.token);
} catch (error) {
  console.error('登录失败:', error);
}
```

### 使用@tanstack/vue-query调用

```typescript
import { useMutation } from '@tanstack/vue-query';
import { login } from '@/api/user';

const loginMutation = useMutation({
  mutationFn: login,
  onSuccess: data => {
    console.log('登录成功:', data.token);
  },
  onError: error => {
    console.error('登录失败:', error);
  }
});

// 执行登录
loginMutation.mutate(loginData);
```

**Section sources**

- [user.ts](file://src/api/user.ts#L15-L20)
- [interceptor.ts](file://src/api/interceptor.ts#L25-L45)

## 登录安全机制

### 密码加密传输

为确保密码在传输过程中的安全性，前端在发送请求前使用Base64对密码进行加密。这一过程在`user.ts`文件的`login`函数中实现。

```mermaid
flowchart TD
A[用户输入密码] --> B[Base64加密]
B --> C[发送加密密码]
C --> D[后端解密验证]
```

**Diagram sources**

- [user.ts](file://src/api/user.ts#L17-L18)
- [encrypt.ts](file://src/utils/encrypt.ts)

**Section sources**

- [user.ts](file://src/api/user.ts#L17-L18)
- [encrypt.ts](file://src/utils/encrypt.ts)

### 防止暴力破解

系统通过多种机制防止暴力破解攻击：

1. **验证码机制**：每次登录都需要输入图形验证码，有效防止自动化脚本攻击。
2. **账户锁定**：连续多次登录失败后，账户将被暂时锁定。
3. **双因素认证**：支持TOTP双因素认证，增加额外的安全层。

认证令牌的存储和管理由`auth.ts`文件中的工具函数处理，确保令牌安全地存储在localStorage中。

```mermaid
classDiagram
class AuthUtils {
+isLogin()
+getToken()
+setToken(token)
+clearToken()
}
```

**Diagram sources**

- [auth.ts](file://src/utils/auth.ts#L1-L50)

**Section sources**

- [auth.ts](file://src/utils/auth.ts#L1-L50)

## 结论

kami_frontend项目的登录API设计完善，提供了安全可靠的用户认证机制。通过结合密码加密、验证码验证和双因素认证，API有效保护了用户账户安全。与请求拦截器的集成确保了认证令牌的无缝管理，为前端应用提供了流畅的用户体验。开发者在使用此API时，应遵循文档中的最佳实践，确保应用的安全性和稳定性。
