# 天猫游戏账户管理API

<cite>
**Referenced Files in This Document**  
- [t-mall-game-account.ts](file://src/api/t-mall-game-account.ts)
- [kami-api-card-info-tmall-game-v1-tmall-game-account-create-req.ts](file://src/api/generated/models/kami-api-card-info-tmall-game-v1-tmall-game-account-create-req.ts)
- [kami-api-card-info-tmall-game-v1-tmall-game-account-delete-req.ts](file://src/api/generated/models/kami-api-card-info-tmall-game-v1-tmall-game-account-delete-req.ts)
- [kami-api-card-info-tmall-game-v1-tmall-game-account-tmall-auth-status-res.ts](file://src/api/generated/models/kami-api-card-info-tmall-game-v1-tmall-game-account-tmall-auth-status-res.ts)
- [kami-api-card-info-tmall-game-v1-tmall-game-account-get-one-random-req.ts](file://src/api/generated/models/kami-api-card-info-tmall-game-v1-tmall-game-account-get-one-random-req.ts)
- [kami-api-card-info-tmall-game-v1-tmall-game-account-authorize-callback-req.ts](file://src/api/generated/models/kami-api-card-info-tmall-game-v1-tmall-game-account-authorize-callback-req.ts)
- [callback.vue](file://src/views/t-mall-game/account-info/callback/callback.vue)
</cite>

## 目录

1. [简介](#简介)
2. [核心接口](#核心接口)
3. [请求模型详解](#请求模型详解)
4. [账户授权机制](#账户授权机制)
5. [随机获取账户与负载均衡](#随机获取账户与负载均衡)
6. [账户状态检测与切换](#账户状态检测与切换)
7. [代码示例](#代码示例)
8. [最佳实践与错误处理](#最佳实践与错误处理)

## 简介

天猫游戏账户管理API提供了一套完整的账户管理解决方案，涵盖了账户的创建、删除、查询、状态管理以及授权等核心功能。该API通过RESTful接口设计，为开发者提供了高效、可靠的账户管理能力，支持批量操作和实时状态检测，满足游戏账户管理的各种业务需求。

## 核心接口

天猫游戏账户管理API提供了以下核心接口：

- **账户创建**: `POST /api/recharge/tMallGame/account/create`
- **账户删除**: `DELETE /api/recharge/tMallGame/account/delete`
- **账户列表查询**: `GET /api/recharge/tMallGame/account/list`
- **随机获取账户**: `GET /api/recharge/tMallGame/account/getOneByRandom`
- **账户状态切换**: `POST /api/recharge/tMallGame/account/toggle`
- **授权回调**: `POST /api/recharge/tMallGame/account/auth/callback`
- **授权状态检测**: `GET /api/recharge/tMallGame/account/auth/getTMallAuthStatus`

这些接口构成了账户管理的核心功能体系，通过组合使用可以实现完整的账户生命周期管理。

**Section sources**

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

## 请求模型详解

### KamiApiCardInfoTMallGameV1TMallGameAccountCreateReq

该请求模型用于创建天猫游戏账户，其核心字段如下：

- **count**: 账户数量，指定需要创建的账户数量，数据类型为数字。

此模型通过`count`字段控制批量创建的账户数量，是批量账户创建操作的基础。

**Section sources**

- [kami-api-card-info-tmall-game-v1-tmall-game-account-create-req.ts](file://src/api/generated/models/kami-api-card-info-tmall-game-v1-tmall-game-account-create-req.ts#L19-L26)

### KamiApiCardInfoTMallGameV1TMallGameAccountDeleteReq

该请求模型用于删除天猫游戏账户，其核心字段如下：

- **id**: 账户ID，指定需要删除的账户的唯一标识符，数据类型为字符串。

通过提供账户ID，可以精确删除指定的账户，确保账户管理的精确性。

**Section sources**

- [kami-api-card-info-tmall-game-v1-tmall-game-account-delete-req.ts](file://src/api/generated/models/kami-api-card-info-tmall-game-v1-tmall-game-account-delete-req.ts#L19-L26)

### TMallAuthStatusRes响应模型

该响应模型用于返回天猫游戏账户的授权状态信息，包含以下字段：

- **status**: 授权状态，布尔值，表示账户当前的授权状态。
- **expiredAt**: 过期时间，字符串格式，表示授权的过期时间戳。

该模型为账户授权状态的检测提供了完整的状态信息，帮助开发者实时掌握账户的授权情况。

**Section sources**

- [kami-api-card-info-tmall-game-v1-tmall-game-account-tmall-auth-status-res.ts](file://src/api/generated/models/kami-api-card-info-tmall-game-v1-tmall-game-account-tmall-auth-status-res.ts#L19-L32)

## 账户授权机制

天猫游戏账户的授权机制通过OAuth2.0流程实现，包含授权码获取、回调处理和状态检测三个核心环节。

### 授权流程

1. **获取授权Key**: 通过`getTMallAuthorizeAppKey`接口获取授权所需的appKey和重定向URI。
2. **用户授权**: 将用户重定向到天猫授权页面，用户完成授权后，天猫会回调指定的URI并附带授权码。
3. **回调处理**: 在回调页面接收授权码，并通过`authorizeTMAllGameLogin`接口将授权码发送到后端进行验证和处理。

### 授权回调实现

授权回调功能在`callback.vue`组件中实现，该组件作为天猫游戏账户授权的回调页面，主要功能包括：

- 解析URL中的授权码和错误信息
- 根据授权结果显示相应的状态信息
- 调用`authorizeTMAllGameLogin`接口将授权码发送到后端

该实现确保了授权流程的完整性和安全性，为账户授权提供了可靠的前端支持。

```mermaid
sequenceDiagram
participant User as 用户
participant Frontend as 前端应用
participant Backend as 后端服务
participant TMall as 天猫平台
User->>Frontend : 访问授权页面
Frontend->>TMall : 重定向到天猫授权
TMall->>User : 显示授权界面
User->>TMall : 同意授权
TMall->>Frontend : 回调并附带授权码
Frontend->>Backend : 发送授权码
Backend->>TMall : 验证授权码
TMall->>Backend : 返回授权结果
Backend->>Frontend : 返回处理结果
Frontend->>User : 显示授权成功
```

**Diagram sources**

- [callback.vue](file://src/views/t-mall-game/account-info/callback/callback.vue#L0-L54)
- [t-mall-game-account.ts](file://src/api/t-mall-game-account.ts#L59-L64)

**Section sources**

- [callback.vue](file://src/views/t-mall-game/account-info/callback/callback.vue#L0-L54)
- [t-mall-game-account.ts](file://src/api/t-mall-game-account.ts#L59-L64)

## 随机获取账户与负载均衡

### get-one-random接口

`get-one-random`接口用于随机获取一个可用的天猫游戏账户，支持以下参数：

- **timeStamp**: 时间戳，用于请求的时效性验证。
- **orderNo**: 订单号，用于关联特定的业务订单。

该接口通过随机选择策略，从可用账户池中选择一个账户，实现了基本的负载均衡功能。

### 负载均衡策略

虽然当前实现主要基于随机选择，但系统具备扩展为更复杂负载均衡策略的基础，如：

- 基于账户使用频率的加权随机
- 基于账户状态的优先级选择
- 基于地理位置的就近分配

这些策略可以通过扩展`get-one-random`接口的逻辑来实现，以满足不同场景下的负载均衡需求。

**Section sources**

- [kami-api-card-info-tmall-game-v1-tmall-game-account-get-one-random-req.ts](file://src/api/generated/models/kami-api-card-info-tmall-game-v1-tmall-game-account-get-one-random-req.ts#L19-L32)
- [t-mall-game-account.ts](file://src/api/t-mall-game-account.ts#L19-L29)

## 账户状态检测与切换

### 状态检测功能

账户状态检测通过`checkTMallAuthStatus`接口实现，该接口向后端发起请求，获取账户的当前授权状态和过期时间。返回的`TMallAuthStatusRes`模型包含了完整的状态信息，使开发者能够实时监控账户的授权情况。

### 状态切换功能

账户状态切换通过`stopTMallAccountItem`接口实现，该接口接收账户ID作为参数，向后端发送状态切换请求。此功能允许开发者在需要时暂停或恢复账户的使用状态，实现灵活的账户管理。

```mermaid
flowchart TD
Start([开始]) --> CheckStatus["检查账户状态"]
CheckStatus --> StatusValid{"状态有效?"}
StatusValid --> |是| UseAccount["使用账户"]
StatusValid --> |否| HandleInvalid["处理无效状态"]
HandleInvalid --> RefreshAuth["刷新授权"]
RefreshAuth --> VerifyAuth["验证授权结果"]
VerifyAuth --> AuthSuccess{"授权成功?"}
AuthSuccess --> |是| UpdateStatus["更新账户状态"]
AuthSuccess --> |否| NotifyError["通知错误"]
UpdateStatus --> UseAccount
NotifyError --> End([结束])
UseAccount --> End
```

**Diagram sources**

- [t-mall-game-account.ts](file://src/api/t-mall-game-account.ts#L53-L57)
- [t-mall-game-account.ts](file://src/api/t-mall-game-account.ts#L31-L33)

**Section sources**

- [t-mall-game-account.ts](file://src/api/t-mall-game-account.ts#L53-L57)
- [t-mall-game-account.ts](file://src/api/t-mall-game-account.ts#L31-L33)

## 代码示例

以下代码示例展示了如何使用`t-mall-game-account.ts`中的封装方法进行账户管理操作：

```typescript
// 查询账户列表
const params = { page: 1, pageSize: 10 };
const accountList = await queryTMallAccountList(params);

// 创建随机账户
const createParams = { count: 5 };
await addRandomAccountList(createParams);

// 检查授权状态
const authStatus = await checkTMallAuthStatus();

// 处理授权回调
await authorizeTMAllGameLogin({ code: 'auth_code', channel: 'tMall' });
```

这些封装方法简化了API调用，提供了类型安全的接口，使开发者能够更高效地进行账户管理操作。

**Section sources**

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

## 最佳实践与错误处理

### 最佳实践

1. **批量操作**: 对于大量账户的创建或管理，优先使用批量接口以提高效率。
2. **状态缓存**: 对于频繁查询的账户状态，建议在客户端进行适当缓存，减少不必要的API调用。
3. **错误重试**: 对于临时性错误，实现适当的重试机制，提高系统的稳定性。

### 错误处理建议

1. **授权失败**: 当授权回调失败时，应记录错误信息并提示用户重新授权。
2. **账户不存在**: 在删除或操作账户时，应先验证账户是否存在，避免操作无效账户。
3. **状态不一致**: 当检测到账户状态与预期不符时，应触发状态同步流程，确保数据一致性。

通过遵循这些最佳实践和错误处理建议，可以构建更加稳定和可靠的账户管理系统。
