# 天猫卡密账户管理

<cite>
**本文档引用文件**  
- [account.go](file://api/card_info_t_mall_game/v1/account.go)
- [callback.go](file://api/card_info_t_mall_game/v1/callback.go)
- [card_info_t_mall_game_v1_t_mall_game_account_create.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_account_create.go)
- [card_info_t_mall_game_v1_t_mall_game_account_authorize_callback.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_account_authorize_callback.go)
- [card_info_t_mall_game_v1_t_mall_game_account_t_mall_auth_status.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_account_t_mall_auth_status.go)
- [card_t_mall_account.go](file://internal/service/card_t_mall_account.go)
- [account.go](file://internal/logic/card_t_mall_account/account.go)
- [oauth.go](file://utility/integration/tmall/api/oauth.go)
- [tmall.go](file://utility/integration/tmall/utils.go)
- [card_recharge_t_mall.go](file://internal/consts/card_recharge_t_mall.go)
- [v_1_recharge_t_mall_account.go](file://internal/model/entity/v_1_recharge_t_mall_account.go)
</cite>

## 目录
1. [简介](#简介)
2. [核心接口说明](#核心接口说明)
3. [OAuth授权流程](#oauth授权流程)
4. [账户状态管理](#账户状态管理)
5. [实际使用示例](#实际使用示例)
6. [错误处理与安全考虑](#错误处理与安全考虑)
7. [客户端实现指南](#客户端实现指南)
8. [性能优化建议](#性能优化建议)

## 简介
本文档详细说明天猫卡密账户管理API的使用方法，涵盖账户创建、OAuth授权、状态查询等核心功能。系统通过天猫游戏平台对接，实现卡密账户的自动化管理，支持多渠道授权与订单回调机制。

## 核心接口说明

### 账户创建接口
- **HTTP方法**: POST
- **URL模式**: `/recharge/tMallGame/account/create`
- **认证机制**: JWT Token
- **请求体**:
  - `count`: 创建账户数量（1-100）
- **响应**:
  - 成功返回空对象，批量创建指定数量的随机邮箱账户

### 账户列表查询接口
- **HTTP方法**: GET
- **URL模式**: `/recharge/tMallGame/account/list`
- **参数**:
  - `accountNumber`: 账户账号（模糊匹配）
  - `current`: 当前页码
  - `pageSize`: 每页数量
- **响应结构**:
  - 分页数据，包含账户ID、账号、余额、状态、创建时间等信息

### 授权回调接口
- **HTTP方法**: POST
- **URL模式**: `/recharge/tMallGame/account/auth/callback`
- **请求体**:
  - `code`: 天猫回调授权码
  - `channel`: 渠道标识（12351:天猫，12352:阿奇索）

**Section sources**
- [account.go](file://api/card_info_t_mall_game/v1/account.go#L10-L71)
- [callback.go](file://api/card_info_t_mall_game/v1/callback.go#L18-L36)

## OAuth授权流程

```mermaid
sequenceDiagram
participant 用户
participant 前端
participant 后端
participant 天猫平台
用户->>前端 : 发起授权请求
前端->>后端 : GET /recharge/tMallGame/account/auth/getAuthorizeKey
后端-->>前端 : 返回授权码和回调地址
前端->>天猫平台 : 重定向到天猫授权页面
天猫平台->>用户 : 用户登录并授权
天猫平台->>后端 : POST 回调接口携带授权码
后端->>后端 : 调用淘宝API换取access token
后端->>后端 : 缓存OAuth响应信息
后端-->>前端 : 授权完成通知
```

**Diagram sources**
- [card_info_t_mall_game_v1_t_mall_game_account_authorize_callback.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_account_authorize_callback.go#L1-L30)
- [oauth.go](file://utility/integration/tmall/api/oauth.go#L13-L73)

### 授权状态检查
- **HTTP方法**: GET
- **URL模式**: `/recharge/tMallGame/account/auth/getTMallAuthStatus`
- **响应**:
  - `status`: 授权状态（true/false）
  - `expiredAt`: 过期时间

**Section sources**
- [account.go](file://api/card_info_t_mall_game/v1/account.go#L60-L71)
- [card_info_t_mall_game_v1_t_mall_game_account_t_mall_auth_status.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_account_t_mall_auth_status.go#L1-L32)

## 账户状态管理

### 状态切换接口
- **HTTP方法**: POST
- **URL模式**: `/recharge/tMallGame/account/toggle`
- **请求体**:
  - `id`: 账户ID
- **功能**: 在启用和禁用状态间切换

### 随机获取账户
- **HTTP方法**: GET
- **URL模式**: `/recharge/tMallGame/account/getOneByRandom`
- **参数**:
  - `timeStamp`: 时间戳
  - `orderNo`: 订单号
- **行为**: 若可用账户不足，自动创建新账户

```mermaid
flowchart TD
Start([开始]) --> CheckCount["检查可用账户数量"]
CheckCount --> LowCount{"数量<10?"}
LowCount --> |是| CreateBatch["异步创建100个新账户"]
LowCount --> |否| GetRandom["随机获取一个启用状态账户"]
GetRandom --> HasAccount{"获取到账户?"}
HasAccount --> |是| ReturnAccount["返回账户信息"]
HasAccount --> |否| CreateOne["创建单个新账户"]
CreateOne --> ReturnNew["返回新账户"]
ReturnAccount --> End([结束])
ReturnNew --> End
```

**Diagram sources**
- [account.go](file://api/card_info_t_mall_game/v1/account.go#L45-L59)
- [account.go](file://internal/logic/card_t_mall_account/account.go#L130-L180)

**Section sources**
- [account.go](file://api/card_info_t_mall_game/v1/account.go#L30-L44)
- [card_info_t_mall_game_v1_t_mall_game_account_create.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_account_create.go#L1-L21)

## 实际使用示例

### 天猫游戏账户创建
1. 调用 `/recharge/tMallGame/account/create` 接口
2. 传入 `count=10` 创建10个新账户
3. 系统自动生成随机邮箱格式的账户名

### OAuth2.0授权流程
1. 前端获取授权key和回调地址
2. 重定向用户到天猫授权页面
3. 用户授权后，天猫回调后端指定接口
4. 后端使用code换取access token并缓存

### 账户状态检测
定期调用 `/recharge/tMallGame/account/auth/getTMallAuthStatus` 接口检查授权有效性，确保API调用的连续性。

## 错误处理与安全考虑

### 常见错误码
- `CodeNotAuthorized (401)`: 授权失败，access token无效
- `CodeInternalError (500)`: 服务器内部错误
- `CodeNotSupported (400)`: 不支持的渠道类型

### 安全措施
1. 所有敏感接口需JWT认证
2. OAuth回调需验证签名
3. access token缓存设置合理过期时间
4. 数据库操作使用事务保证一致性

**Section sources**
- [card_info_t_mall_game_v1_t_mall_game_account_authorize_callback.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_account_authorize_callback.go#L1-L30)
- [errHandler](file://internal/errHandler/handler.go)

## 客户端实现指南

### 授权流程实现
1. 先调用获取授权key接口
2. 构造天猫授权URL
3. 处理回调，发送code到后端
4. 定期检查授权状态

### API调用最佳实践
- 使用连接池管理HTTP客户端
- 实现重试机制（最多5次）
- 缓存access token状态
- 处理速率限制

## 性能优化建议

### 批量操作
- 账户创建建议批量进行，减少数据库事务开销
- 查询接口合理使用分页，避免大数据量加载

### 缓存策略
- OAuth token信息缓存有效期与token一致
- 频繁查询的账户状态可做短期缓存

### 异步处理
- 账户不足时的自动创建使用异步处理
- 避免阻塞主请求流程

```mermaid
graph TB
subgraph "API层"
A[账户创建]
B[状态查询]
C[授权回调]
end
subgraph "服务层"
D[账户服务]
E[授权服务]
end
subgraph "数据层"
F[MySQL数据库]
G[Redis缓存]
end
A --> D
B --> D
C --> E
D --> F
E --> G
E --> F
```

**Diagram sources**
- [card_t_mall_account.go](file://internal/service/card_t_mall_account.go#L1-L50)
- [account.go](file://internal/logic/card_t_mall_account/account.go)

**Section sources**
- [card_recharge_t_mall.go](file://internal/consts/card_recharge_t_mall.go#L1-L90)
- [v_1_recharge_t_mall_account.go](file://internal/model/entity/v_1_recharge_t_mall_account.go#L1-L21)