# 天猫游戏API

<cite>
**本文档引用的文件**   
- [t-mall-game-account.ts](file://src/api/t-mall-game-account.ts)
- [t-mall-game-order.ts](file://src/api/t-mall-game-order.ts)
- [t-mall-game-shop-order.ts](file://src/api/t-mall-game-shop-order.ts)
- [list.vue](file://src/views/t-mall-game/account-info/list.vue)
- [index.vue](file://src/views/t-mall-game/order-info/index.vue)
- [callback.vue](file://src/views/t-mall-game/account-info/callback/callback.vue)
- [iframe.ts](file://src/router/routes/modules/iframe.ts)
- [DefaultApi.md](file://src/api/generated/docs/DefaultApi.md)
</cite>

## 目录

1. [简介](#简介)
2. [账户管理API](#账户管理api)
3. [订单处理API](#订单处理api)
4. [店铺订单API](#店铺订单api)
5. [账户授权回调机制](#账户授权回调机制)
6. [数据同步API](#数据同步api)
7. [安全调用建议](#安全调用建议)
8. [性能优化技巧](#性能优化技巧)

## 简介

天猫游戏API提供了一套完整的接口，用于管理天猫游戏账户、处理订单以及查询店铺订单。该API系统支持账户授权、状态切换、随机获取账户等操作，同时涵盖了订单提交、状态修改、分类查询等功能。通过这些API，开发者可以高效地管理天猫游戏卡券，实现自动化操作和数据同步。

## 账户管理API

账户管理API提供了对天猫游戏账户的全面控制，包括创建、删除、查询和状态切换等操作。

### 账户授权

通过`getTMallAuthorizeAppKey`函数获取授权appKey，用于后续的账户授权操作。此函数向`/api/recharge/tMallGame/account/auth/getAuthorizeKey`端点发送GET请求，返回授权所需的appKey和重定向URI。

### 状态切换

使用`stopTMallAccountItem`函数可以改变游戏账户的状态。该函数向`/api/recharge/tMallGame/account/toggle`端点发送POST请求，接收账户ID作为参数，实现账户的启用或禁用。

### 随机获取账户

`addRandomAccountList`函数允许随机创建游戏账户。该函数向`/api/recharge/tMallGame/account/create`端点发送POST请求，接收包含数量参数的对象，返回新创建的账户信息。

### 账户列表查询

`queryTMallAccountList`函数用于获取游戏账户列表。该函数向`/api/recharge/tMallGame/account/list`端点发送GET请求，支持分页和过滤条件，返回账户列表数据。

**Section sources**

- [t-mall-game-account.ts](file://src/api/t-mall-game-account.ts#L47-L90)

## 订单处理API

订单处理API设计用于处理天猫游戏订单的提交、状态修改和分类查询。

### 订单提交

`queryTMallOrderList`函数用于提交订单。该函数向`/api/recharge/tMallGame/order/list`端点发送GET请求，接收订单参数，返回订单处理结果。

### 状态修改

`callBackOrderManualAPI`函数用于手动回调订单状态。该函数向`/api/recharge/tMallGame/shopOrder/callbackByManual`端点发送POST请求，接收订单号和充值ID，更新订单状态。

### 分类查询

`getOrderSummary`函数用于获取订单统计摘要。该函数向`/api/recharge/tMallGame/workspace/orderSummary`端点发送GET请求，返回订单数量、成功数量、金额等统计信息。

**Section sources**

- [t-mall-game-order.ts](file://src/api/t-mall-game-order.ts#L100-L250)

## 店铺订单API

店铺订单API实现了对天猫店铺订单的查询和历史记录获取。

### 店铺订单查询

`queryTMallShopOrderList`函数用于获取淘宝订单详情。该函数向`/api/recharge/tMallGame/shopOrder/getList`端点发送GET请求，支持分页和日期范围过滤，返回店铺订单列表。

### 历史记录获取

`queryTMallOrderOrderHistory`函数用于获取淘宝订单历史。该函数向`/api/recharge/tMallGame/shopOrder/getShopHistoryList`端点发送GET请求，接收店铺ID，返回订单历史记录。

**Section sources**

- [t-mall-game-shop-order.ts](file://src/api/t-mall-game-shop-order.ts#L50-L90)

## 账户授权回调机制

账户授权回调机制通过OAuth2.0协议实现，确保账户授权的安全性和可靠性。

### 回调流程

1. 用户在天猫平台完成授权后，天猫会重定向到指定的回调URL。
2. 前端页面`callback.vue`捕获授权码（code）和状态（state）参数。
3. 前端调用`authorizeTMAllGameLogin`函数，将授权码和渠道信息发送到后端。
4. 后端验证授权码并完成账户绑定。

### 回调实现

`authorizeTMAllGameLogin`函数向`/api/recharge/tMallGame/account/auth/callback`端点发送POST请求，接收包含授权码和渠道信息的对象，完成账户授权回调。

**Section sources**

- [callback.vue](file://src/views/t-mall-game/account-info/callback/callback.vue#L1-L54)
- [t-mall-game-account.ts](file://src/api/t-mall-game-account.ts#L85-L90)

## 数据同步API

数据同步API用于同步订单数据，确保前后端数据的一致性。

### 同步操作

`apiRechargeTMallGameDataSyncPost`函数用于同步订单数据。该函数向`/api/recharge/tMallGame/data/sync`端点发送POST请求，接收包含渠道名称和同步时长的请求体，返回同步结果。

### 请求参数

- `channelName`: 渠道名称
- `duration`: 同步时长（秒）

### 响应示例

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "syncedCount": 100,
    "failedCount": 0
  }
}
```

**Section sources**

- [DefaultApi.md](file://src/api/generated/docs/DefaultApi.md#L8067-L8115)

## 安全调用建议

为确保API调用的安全性，建议采取以下措施：

1. **使用HTTPS**: 所有API调用应通过HTTPS协议进行，确保数据传输的安全性。
2. **验证回调**: 在处理授权回调时，应验证回调URL的来源，防止恶意请求。
3. **限制请求频率**: 对API调用进行频率限制，防止滥用和DDoS攻击。
4. **数据加密**: 敏感数据（如账户信息）在传输过程中应进行加密处理。
5. **错误处理**: 实现完善的错误处理机制，及时发现和处理异常情况。

## 性能优化技巧

为提高API调用的性能，建议采取以下优化措施：

1. **批量操作**: 尽量使用批量操作接口，减少HTTP请求次数。
2. **缓存机制**: 对频繁查询的数据实施缓存，减少数据库访问。
3. **异步处理**: 对耗时操作采用异步处理方式，提高响应速度。
4. **分页查询**: 对大数据量的查询使用分页，避免一次性加载过多数据。
5. **连接复用**: 使用HTTP连接复用技术，减少TCP连接建立的开销。
