# 生成的API接口

<cite>
**本文档中引用的文件**  
- [ck-api.ts](file://src/api/generated/apis/ck-api.ts)
- [totpapi.ts](file://src/api/generated/apis/totpapi.ts)
- [interceptor.ts](file://src/api/interceptor.ts)
- [configuration.ts](file://src/api/generated/configuration.ts)
- [base.ts](file://src/api/generated/base.ts)
- [common.ts](file://src/api/generated/common.ts)
- [CkApi.md](file://src/api/generated/docs/CkApi.md)
- [TOTPApi.md](file://src/api/generated/docs/TOTPApi.md)
</cite>

## 目录

1. [简介](#简介)
2. [CK API接口](#ck-api接口)
3. [TOTP API接口](#totp-api接口)
4. [API客户端调用模式](#api客户端调用模式)
5. [请求拦截器集成](#请求拦截器集成)
6. [API版本管理与向后兼容性](#api版本管理与向后兼容性)
7. [常见问题解决方案](#常见问题解决方案)
8. [结论](#结论)

## 简介

本文档详细说明了kami_frontend项目中基于OpenAPI规范生成的API接口架构。文档重点介绍了CK API和TOTP API的具体实现，包括每个API端点的HTTP方法、URL路径、请求参数和响应格式。同时，文档还提供了API客户端的调用模式、请求拦截器集成方式以及API版本管理策略。

**Section sources**

- [ck-api.ts](file://src/api/generated/apis/ck-api.ts#L1-L50)
- [totpapi.ts](file://src/api/generated/apis/totpapi.ts#L1-L50)

## CK API接口

CK API接口主要用于管理京东等平台的卡券信息，包括添加、删除、更新和查询京东CK（Cookie）以及下单操作。

### 添加京东CK

- **HTTP方法**: POST
- **URL路径**: /api/cookieInfo/jd/account/add
- **请求参数**: KamiApiCardRedeemJdV1AccountAddReq
  - name: 用户名（字符串）
  - cookie: Cookie（字符串）
  - status: 状态（字符串）
  - notes: 备注（可选，字符串）
- **响应格式**: object

### 删除京东CK

- **HTTP方法**: DELETE
- **URL路径**: /api/cookieInfo/jd/account/delete
- **请求参数**: id（数字）
- **响应格式**: object

### 获取京东CK

- **HTTP方法**: GET
- **URL路径**: /api/cookieInfo/jd/account/get
- **请求参数**: id（数字）
- **响应格式**: KamiApiCardRedeemJdV1AccountGetRes

### 获取京东CK列表

- **HTTP方法**: GET
- **URL路径**: /api/cookieInfo/jd/account/list
- **请求参数**:
  - current: 页数（数字）
  - pageSize: 页码（5 | 10 | 15 | 20 | 50 | 100）
  - status: 状态（可选，'dailyDisable' | 'disable' | 'expired' | 'normal' | 'tmpDisable'）
  - name: 昵称（可选，字符串）
  - cookie: CK（可选，字符串）
- **响应格式**: KamiApiCardRedeemJdV1AccountListRes

### 修改京东CK状态

- **HTTP方法**: PUT
- **URL路径**: /api/cookieInfo/jd/account/status
- **请求参数**: KamiApiCardRedeemJdV1AccountStatusReq
- **响应格式**: object

### 更新京东CK

- **HTTP方法**: PUT
- **URL路径**: /api/cookieInfo/jd/account/update
- **请求参数**: KamiApiCardRedeemJdV1AccountUpdateReq
- **响应格式**: object

### 获取订单列表

- **HTTP方法**: GET
- **URL路径**: /api/cookieInfo/jd/order/list
- **请求参数**:
  - current: 页数（数字）
  - pageSize: 页码（5 | 10 | 15 | 20 | 50 | 100）
  - cookieId: Cookie ID（可选，数字）
  - cookie: Cookie（可选，字符串）
  - status: 状态（可选，'init' | 'placeFail' | 'placeSuccess'）
- **响应格式**: KamiApiCardRedeemJdV1OrderListRes

### 下单

- **HTTP方法**: POST
- **URL路径**: /api/cookieInfo/jd/order/placeOrder
- **请求参数**: KamiApiCardRedeemJdV1PlaceOrderReq
- **响应格式**: KamiApiCardRedeemJdV1PlaceOrderRes

**Section sources**

- [ck-api.ts](file://src/api/generated/apis/ck-api.ts#L1236-L1398)
- [CkApi.md](file://src/api/generated/docs/CkApi.md#L1-L420)

## TOTP API接口

TOTP API接口用于管理用户的两步验证功能，包括查看两步验证图像、重置两步验证、设置二步验证和确认当前用户是否开启TOTP。

### 查看两步验证图像

- **HTTP方法**: GET
- **URL路径**: /api/user/totp/image
- **请求参数**: code（字符串）
- **响应格式**: KamiApiSysUserV1TotpImageGetRes
  - image: 图像（可选，字符串）

### 重置两步验证

- **HTTP方法**: POST
- **URL路径**: /api/user/totp/reset
- **请求参数**: KamiApiSysUserV1TotpResetReq
- **响应格式**: KamiApiSysUserV1TotpResetRes

### 设置二步验证

- **HTTP方法**: POST
- **URL路径**: /api/user/totp/set
- **请求参数**: KamiApiSysUserV1TotpSetReq
- **响应格式**: object

### 确认当前用户是否开启TOTP

- **HTTP方法**: GET
- **URL路径**: /api/user/totp/status
- **请求参数**: 无
- **响应格式**: KamiApiSysUserV1TotpStatusGetRes

**Section sources**

- [totpapi.ts](file://src/api/generated/apis/totpapi.ts#L561-L628)
- [TOTPApi.md](file://src/api/generated/docs/TOTPApi.md#L1-L187)

## API客户端调用模式

API客户端的调用模式基于生成的API类，通过配置和实例化API类来调用具体的API方法。客户端支持异步处理、错误处理和超时机制。

```mermaid
flowchart TD
Start([开始]) --> CreateConfig["创建配置实例"]
CreateConfig --> CreateApiInstance["创建API实例"]
CreateApiInstance --> CallApi["调用API方法"]
CallApi --> CheckResponse{"响应成功?"}
CheckResponse --> |是| ReturnSuccess["返回成功结果"]
CheckResponse --> |否| HandleError["处理错误"]
HandleError --> Retry{"是否重试?"}
Retry --> |是| CallApi
Retry --> |否| ReturnError["返回错误结果"]
ReturnSuccess --> End([结束])
ReturnError --> End
```

**Diagram sources**

- [ck-api.ts](file://src/api/generated/apis/ck-api.ts#L1236-L1398)
- [totpapi.ts](file://src/api/generated/apis/totpapi.ts#L561-L628)

**Section sources**

- [configuration.ts](file://src/api/generated/configuration.ts#L1-L138)
- [base.ts](file://src/api/generated/base.ts#L1-L92)
- [common.ts](file://src/api/generated/common.ts#L1-L203)

## 请求拦截器集成

API接口通过请求拦截器实现统一的请求/响应处理。拦截器在请求发送前添加认证信息，并在响应接收后处理认证过期和错误情况。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Interceptor as "请求拦截器"
participant Server as "服务器"
Client->>Interceptor : 发起请求
Interceptor->>Interceptor : 添加认证头
Interceptor->>Interceptor : 添加tokenFrom头
Interceptor->>Server : 发送请求
Server-->>Interceptor : 返回响应
Interceptor->>Interceptor : 检查刷新令牌
Interceptor->>Interceptor : 更新令牌
Interceptor->>Interceptor : 检查响应状态
Interceptor->>Client : 返回处理后的响应
```

**Diagram sources**

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

**Section sources**

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

## API版本管理与向后兼容性

API版本管理通过OpenAPI规范生成的代码实现，确保向后兼容性。当API接口发生变化时，通过生成新的API代码并保留旧版本的兼容性处理。

**Section sources**

- [configuration.ts](file://src/api/generated/configuration.ts#L1-L138)
- [base.ts](file://src/api/generated/base.ts#L1-L92)

## 常见问题解决方案

### 网络错误

- 检查网络连接是否正常
- 确认API服务器是否可用
- 重试请求

### 认证失败

- 检查令牌是否过期
- 重新登录获取新令牌
- 确认认证信息是否正确

### 数据格式不匹配

- 检查请求参数是否符合API文档要求
- 确认响应数据格式是否与预期一致
- 更新API客户端代码以匹配最新API版本

**Section sources**

- [interceptor.ts](file://src/api/interceptor.ts#L1-L90)
- [common.ts](file://src/api/generated/common.ts#L1-L203)

## 结论

本文档详细介绍了kami_frontend项目中生成的API接口，包括CK API和TOTP API的具体实现。通过本文档，开发者可以了解如何调用这些API接口，并处理常见的问题。API客户端的调用模式和请求拦截器集成方式确保了请求的统一处理和错误处理的可靠性。
