# 认证API接口

<cite>
**本文档引用的文件**
- [totpapi.ts](file://src/api/generated/apis/totpapi.ts)
- [ck-api.ts](file://src/api/generated/apis/ck-api.ts)
- [auth.ts](file://src/utils/auth.ts)
- [interceptor.ts](file://src/api/interceptor.ts)
- [tanstack-query.ts](file://src/plugins/tanstack-query.ts)
</cite>

## 目录

1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概述](#架构概述)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)

## 简介

本文档详细介绍了kami_frontend项目的认证API接口，包括登录、登出、密码重置、TOTP配置等接口的请求/响应格式和使用方式。文档深入解释了每个API的HTTP方法、URL路径、请求参数、请求体结构和响应数据模型。同时，文档还说明了认证令牌在请求头中的传递方式和刷新机制，以及API错误码的含义和处理策略。

## 项目结构

kami_frontend项目是一个前端应用，主要包含配置、部署、源代码等目录。源代码目录（src）包含了API定义、组件、工具函数等。

```mermaid
graph TD
A[src] --> B[api]
A --> C[components]
A --> D[utils]
A --> E[plugins]
B --> F[generated]
B --> G[interceptor.ts]
D --> H[auth.ts]
E --> I[tanstack-query.ts]
```

**图示来源**

- [src/api](file://src/api)
- [src/utils](file://src/utils)
- [src/plugins](file://src/plugins)

**章节来源**

- [src](file://src)

## 核心组件

本项目的核心组件包括认证API、请求拦截器、认证工具函数和查询插件。

**章节来源**

- [totpapi.ts](file://src/api/generated/apis/totpapi.ts)
- [auth.ts](file://src/utils/auth.ts)
- [interceptor.ts](file://src/api/interceptor.ts)
- [tanstack-query.ts](file://src/plugins/tanstack-query.ts)

## 架构概述

kami_frontend项目的认证架构主要包括API调用、请求拦截、认证状态管理和查询管理。

```mermaid
graph LR
A[客户端] --> B[API调用]
B --> C[请求拦截器]
C --> D[认证令牌管理]
D --> E[本地存储]
C --> F[响应处理]
F --> G[错误处理]
B --> H[查询管理]
H --> I[缓存管理]
```

**图示来源**

- [interceptor.ts](file://src/api/interceptor.ts)
- [auth.ts](file://src/utils/auth.ts)
- [tanstack-query.ts](file://src/plugins/tanstack-query.ts)

## 详细组件分析

### TOTP API分析

TOTP API提供了两步验证相关的接口，包括查看两步验证图像、重置两步验证、设置二步验证和确认当前用户是否开启TOTP。

#### TOTP API类图

```mermaid
classDiagram
class TOTPApi {
+apiUserTotpImageGet(requestParameters, options)
+apiUserTotpResetPost(requestParameters, options)
+apiUserTotpSetPost(requestParameters, options)
+apiUserTotpStatusGet(options)
}
class TOTPApiInterface {
+apiUserTotpImageGet(requestParameters, options)
+apiUserTotpResetPost(requestParameters, options)
+apiUserTotpSetPost(requestParameters, options)
+apiUserTotpStatusGet(options)
}
TOTPApi --> TOTPApiInterface : "实现"
```

**图示来源**

- [totpapi.ts](file://src/api/generated/apis/totpapi.ts)

#### TOTP API调用序列图

```mermaid
sequenceDiagram
participant Client as "客户端"
participant TOTPApi as "TOTPApi"
participant Axios as "Axios"
Client->>TOTPApi : apiUserTotpImageGet(code)
TOTPApi->>Axios : 发送GET请求
Axios-->>TOTPApi : 返回响应
TOTPApi-->>Client : 返回图像数据
Client->>TOTPApi : apiUserTotpResetPost(req)
TOTPApi->>Axios : 发送POST请求
Axios-->>TOTPApi : 返回响应
TOTPApi-->>Client : 返回重置结果
```

**图示来源**

- [totpapi.ts](file://src/api/generated/apis/totpapi.ts)

**章节来源**

- [totpapi.ts](file://src/api/generated/apis/totpapi.ts)

### 认证工具函数分析

认证工具函数提供了对认证令牌的管理，包括获取、设置、清除令牌等操作。

#### 认证工具函数流程图

```mermaid
flowchart TD
Start([开始]) --> CheckLogin["检查是否已登录"]
CheckLogin --> IsLoggedIn{"已登录?"}
IsLoggedIn --> |是| GetToken["获取令牌"]
IsLoggedIn --> |否| ReturnNull["返回null"]
GetToken --> End([结束])
ReturnNull --> End
```

**图示来源**

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

**章节来源**

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

### 请求拦截器分析

请求拦截器负责在请求发送前添加认证头，并在响应返回后处理刷新令牌和错误。

#### 请求拦截器流程图

```mermaid
flowchart TD
Start([请求开始]) --> AddAuthHeader["添加认证头"]
AddAuthHeader --> SendRequest["发送请求"]
SendRequest --> ReceiveResponse["接收响应"]
ReceiveResponse --> CheckRefreshToken["检查刷新令牌"]
CheckRefreshToken --> HasRefreshToken{"有刷新令牌?"}
HasRefreshToken --> |是| UpdateToken["更新令牌"]
HasRefreshToken --> |否| CheckBinary["检查二进制文件"]
UpdateToken --> CheckBinary
CheckBinary --> IsBinary{"是二进制文件?"}
IsBinary --> |是| ReturnResponse["直接返回响应"]
IsBinary --> |否| CheckCode["检查响应码"]
ReturnResponse --> End([结束])
CheckCode --> IsSuccess{"成功?"}
IsSuccess --> |是| ReturnData["返回数据"]
IsSuccess --> |否| HandleError["处理错误"]
ReturnData --> End
HandleError --> End
```

**图示来源**

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

**章节来源**

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

## 依赖分析

kami_frontend项目的认证功能依赖于多个组件和外部库。

```mermaid
graph TD
A[TOTP API] --> B[Axios]
C[请求拦截器] --> B
D[认证工具函数] --> E[localStorage]
F[查询管理] --> G[@tanstack/vue-query]
C --> D
A --> C
```

**图示来源**

- [totpapi.ts](file://src/api/generated/apis/totpapi.ts)
- [interceptor.ts](file://src/api/interceptor.ts)
- [auth.ts](file://src/utils/auth.ts)
- [tanstack-query.ts](file://src/plugins/tanstack-query.ts)

**章节来源**

- [package.json](file://package.json)

## 性能考虑

1. 认证令牌存储在localStorage中，读写速度快。
2. 使用@tanstack/vue-query进行查询管理，支持缓存和去重。
3. 请求拦截器中对二进制文件进行特殊处理，避免不必要的数据解析。
4. 错误处理集中管理，减少重复代码。

## 故障排除指南

1. **登录过期**: 当收到5001、5002、5003错误码时，表示登录已过期，需要重新登录。
2. **令牌未添加**: 检查请求拦截器是否正确添加了Authorization头。
3. **令牌刷新失败**: 检查响应头中是否包含refresh-token。
4. **跨域问题**: 确保后端正确配置了CORS，允许前端域名访问。

**章节来源**

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

## 结论

kami_frontend项目的认证API接口设计合理，功能完整。通过请求拦截器统一处理认证相关逻辑，提高了代码的可维护性。使用@tanstack/vue-query进行查询管理，提升了用户体验。整体架构清晰，便于扩展和维护。
