# 天猫卡密管理API

<cite>
**本文档引用文件**  
- [account.go](file://api/card_info_t_mall_game/v1/account.go)
- [order.go](file://api/card_info_t_mall_game/v1/order.go)
- [shop.go](file://api/card_info_t_mall_game/v1/shop.go)
- [callback.go](file://api/card_info_t_mall_game/v1/callback.go)
- [workspace.go](file://api/card_info_t_mall_game/v1/workspace.go)
- [card_t_mall_game_account.go](file://internal/model/card_t_mall_game_account.go)
- [card_t_mall_game_order.go](file://internal/model/card_t_mall_game_order.go)
- [card_t_mall_game_work_space.go](file://internal/model/card_t_mall_game_work_space.go)
- [card_recharge_t_mall.go](file://internal/consts/card_recharge_t_mall.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_order_query_order.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_order_query_order.go)
- [card_info_t_mall_game_v1_t_mall_game_stats.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_stats.go)
- [card_t_mall_account.go](file://internal/service/card_t_mall_account.go)
- [card_t_mall_order.go](file://internal/service/card_t_mall_order.go)
</cite>

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

## 简介
本文档详细介绍了天猫卡密管理API，涵盖账户授权、订单处理、店铺管理等核心接口。重点说明了账户创建、OAuth授权、订单提交、店铺信息同步等端点的HTTP方法、URL模式、请求/响应模式和认证机制。文档还解释了天猫卡密特有的Agiso回调机制和workspace管理，提供错误处理策略和安全考虑，并包含客户端实现指南和性能优化建议。

## 项目结构
天猫卡密管理API的代码结构清晰，主要分为API接口层、内部逻辑层和服务层。API接口定义位于`api/card_info_t_mall_game/v1/`目录下，包含账户、订单、店铺、回调和工作空间等模块。内部实现位于`internal/`目录，包括模型定义、常量、控制器、服务和工具类。

```mermaid
graph TD
subgraph "API接口层"
A[account.go]
B[order.go]
C[shop.go]
D[callback.go]
E[workspace.go]
end
subgraph "内部实现层"
F[card_t_mall_game_account.go]
G[card_t_mall_game_order.go]
H[card_t_mall_game_work_space.go]
I[card_recharge_t_mall.go]
end
subgraph "服务层"
J[card_t_mall_account.go]
K[card_t_mall_order.go]
end
subgraph "控制器层"
L[card_info_t_mall_game_v1_*.go]
end
A --> F
B --> G
C --> G
D --> L
E --> H
F --> J
G --> K
H --> K
```

**图示来源**
- [account.go](file://api/card_info_t_mall_game/v1/account.go)
- [order.go](file://api/card_info_t_mall_game/v1/order.go)
- [shop.go](file://api/card_info_t_mall_game/v1/shop.go)
- [callback.go](file://api/card_info_t_mall_game/v1/callback.go)
- [workspace.go](file://api/card_info_t_mall_game/v1/workspace.go)
- [card_t_mall_game_account.go](file://internal/model/card_t_mall_game_account.go)
- [card_t_mall_game_order.go](file://internal/model/card_t_mall_game_order.go)
- [card_t_mall_game_work_space.go](file://internal/model/card_t_mall_game_work_space.go)
- [card_t_mall_account.go](file://internal/service/card_t_mall_account.go)
- [card_t_mall_order.go](file://internal/service/card_t_mall_order.go)

**章节来源**
- [account.go](file://api/card_info_t_mall_game/v1/account.go)
- [order.go](file://api/card_info_t_mall_game/v1/order.go)
- [shop.go](file://api/card_info_t_mall_game/v1/shop.go)
- [callback.go](file://api/card_info_t_mall_game/v1/callback.go)
- [workspace.go](file://api/card_info_t_mall_game/v1/workspace.go)

## 核心组件
天猫卡密管理API的核心组件包括账户管理、订单处理、店铺同步、回调处理和统计分析。账户管理负责天猫游戏账户的创建、查询和状态管理。订单处理模块处理订单的提交、查询和状态更新。店铺同步功能实现与天猫店铺订单的关联和信息同步。回调处理模块接收来自Agiso和天猫的回调通知。统计分析组件提供订单和账户的统计信息。

**章节来源**
- [account.go](file://api/card_info_t_mall_game/v1/account.go)
- [order.go](file://api/card_info_t_mall_game/v1/order.go)
- [shop.go](file://api/card_info_t_mall_game/v1/shop.go)
- [workspace.go](file://api/card_info_t_mall_game/v1/workspace.go)

## 架构概述
天猫卡密管理API采用分层架构设计，包括API接口层、业务逻辑层、服务层和数据访问层。API接口层定义了RESTful端点，业务逻辑层处理具体的业务规则，服务层提供可重用的服务接口，数据访问层负责与数据库交互。

```mermaid
graph TD
A[客户端] --> B[API接口层]
B --> C[业务逻辑层]
C --> D[服务层]
D --> E[数据访问层]
E --> F[数据库]
B --> G[认证中间件]
C --> H[错误处理]
D --> I[事务管理]
style A fill:#f9f,stroke:#333
style F fill:#bbf,stroke:#333
```

**图示来源**
- [account.go](file://api/card_info_t_mall_game/v1/account.go)
- [order.go](file://api/card_info_t_mall_game/v1/order.go)
- [card_t_mall_account.go](file://internal/service/card_t_mall_account.go)
- [card_t_mall_order.go](file://internal/service/card_t_mall_order.go)

## 详细组件分析
### 账户管理分析
账户管理组件提供天猫游戏账户的全生命周期管理功能，包括创建、查询、状态切换和删除。

#### 账户创建
```mermaid
flowchart TD
Start([创建账户请求]) --> Validate["验证请求参数"]
Validate --> Exists{"账户已存在?"}
Exists --> |是| ReturnError["返回错误"]
Exists --> |否| Create["创建账户记录"]
Create --> Enable["启用账户"]
Enable --> ReturnSuccess["返回成功"]
style Start fill:#4CAF50,stroke:#333
style ReturnSuccess fill:#4CAF50,stroke:#333
style ReturnError fill:#F44336,stroke:#333
```

**图示来源**
- [account.go](file://api/card_info_t_mall_game/v1/account.go#L10-L20)
- [card_t_mall_account.go](file://internal/service/card_t_mall_account.go#L15-L25)

#### 账户授权
```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "API服务"
participant Tmall as "天猫平台"
Client->>API : GET /recharge/tMallGame/account/auth/getAuthorizeKey
API-->>Client : 返回授权码和回调地址
Client->>Tmall : 使用授权码访问天猫
Tmall-->>Client : 授权成功，重定向到回调地址
Client->>API : POST /recharge/tMallGame/account/auth/callback
API->>API : 验证渠道和授权码
API->>Tmall : 调用天猫OAuth2登录
Tmall-->>API : 返回授权结果
API-->>Client : 返回授权结果
```

**图示来源**
- [account.go](file://api/card_info_t_mall_game/v1/account.go#L60-L70)
- [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)

**章节来源**
- [account.go](file://api/card_info_t_mall_game/v1/account.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)

### 订单处理分析
订单处理组件管理天猫游戏订单的整个生命周期，从提交到完成。

#### 订单提交
```mermaid
flowchart TD
Start([提交订单]) --> Validate["验证订单参数"]
Validate --> Account{"账户可用?"}
Account --> |否| ReturnError["返回错误"]
Account --> |是| Create["创建订单记录"]
Create --> SetStatus["设置订单状态为创建"]
SetStatus --> ReturnSuccess["返回订单号"]
style Start fill:#4CAF50,stroke:#333
style ReturnSuccess fill:#4CAF50,stroke:#333
style ReturnError fill:#F44336,stroke:#333
```

**图示来源**
- [order.go](file://api/card_info_t_mall_game/v1/order.go#L40-L55)
- [card_t_mall_order.go](file://internal/service/card_t_mall_order.go#L35-L45)

#### 订单状态查询
```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "API服务"
participant DB as "数据库"
Client->>API : GET /recharge/tMallGame/order/list
API->>DB : 查询订单列表
DB-->>API : 返回订单数据
API->>API : 关联账户和店铺信息
API-->>Client : 返回订单列表
```

**图示来源**
- [order.go](file://api/card_info_t_mall_game/v1/order.go#L20-L35)
- [card_t_mall_order.go](file://internal/service/card_t_mall_order.go#L50-L60)

**章节来源**
- [order.go](file://api/card_info_t_mall_game/v1/order.go)
- [card_t_mall_order.go](file://internal/service/card_t_mall_order.go)

### 店铺管理分析
店铺管理组件处理天猫店铺订单的同步和查询。

#### 店铺订单同步
```mermaid
flowchart TD
Start([获取店铺订单]) --> Query["查询店铺订单"]
Query --> Exists{"订单存在?"}
Exists --> |否| Create["创建店铺订单记录"]
Exists --> |是| Update["更新订单状态"]
Update --> Sync["同步到本地订单"]
Sync --> Return["返回订单信息"]
style Start fill:#4CAF50,stroke:#333
style Return fill:#4CAF50,stroke:#333
```

**图示来源**
- [shop.go](file://api/card_info_t_mall_game/v1/shop.go#L10-L25)
- [card_t_mall_order.go](file://internal/service/card_t_mall_order.go#L70-L80)

**章节来源**
- [shop.go](file://api/card_info_t_mall_game/v1/shop.go)
- [card_t_mall_order.go](file://internal/service/card_t_mall_order.go)

## 依赖分析
天猫卡密管理API的组件间存在清晰的依赖关系。API接口层依赖于服务层提供的接口，服务层依赖于数据访问层。各组件通过定义良好的接口进行交互，降低了耦合度。

```mermaid
classDiagram
class AccountAPI {
+createAccount()
+listAccounts()
+toggleAccount()
+deleteAccount()
}
class OrderAPI {
+submitOrder()
+listOrders()
+modifyOrderStatus()
}
class ShopAPI {
+getShopOrderList()
+getShopOrder()
+getShopHistory()
}
class CallbackAPI {
+agisoCallback()
+authorizeCallback()
+manualCallback()
}
class WorkspaceAPI {
+getOrderSummary()
+getStats()
}
class AccountService {
+Add()
+List()
+Toggle()
+Delete()
}
class OrderService {
+Create()
+List()
+ShopList()
+GetOrderStats()
}
AccountAPI --> AccountService : "使用"
OrderAPI --> OrderService : "使用"
ShopAPI --> OrderService : "使用"
CallbackAPI --> OrderService : "使用"
WorkspaceAPI --> OrderService : "使用"
```

**图示来源**
- [card_t_mall_account.go](file://internal/service/card_t_mall_account.go)
- [card_t_mall_order.go](file://internal/service/card_t_mall_order.go)
- [account.go](file://api/card_info_t_mall_game/v1/account.go)
- [order.go](file://api/card_info_t_mall_game/v1/order.go)
- [shop.go](file://api/card_info_t_mall_game/v1/shop.go)
- [callback.go](file://api/card_info_t_mall_game/v1/callback.go)
- [workspace.go](file://api/card_info_t_mall_game/v1/workspace.go)

**章节来源**
- [card_t_mall_account.go](file://internal/service/card_t_mall_account.go)
- [card_t_mall_order.go](file://internal/service/card_t_mall_order.go)

## 性能考虑
天猫卡密管理API在设计时考虑了性能优化。通过使用缓存减少数据库查询，采用批量操作提高效率，实施限流防止系统过载。对于高频访问的统计接口，建议使用缓存策略。订单提交和状态更新操作应使用数据库事务确保数据一致性。

## 故障排除指南
### 常见问题
1. **授权失败**：检查授权码是否正确，回调地址是否匹配，网络连接是否正常。
2. **订单提交失败**：验证账户状态是否正常，订单金额是否符合要求，签名是否正确。
3. **回调接收失败**：确认回调URL是否可访问，防火墙设置是否允许外部请求。

### 错误处理
系统使用统一的错误处理机制，所有错误都通过`errHandler`包进行包装和处理。错误码遵循标准规范，便于客户端识别和处理。

**章节来源**
- [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_order_query_order.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_order_query_order.go)
- [card_info_t_mall_game_v1_t_mall_game_stats.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_stats.go)

## 结论
天猫卡密管理API提供了一套完整的解决方案，用于管理天猫游戏账户和订单。通过清晰的接口设计和分层架构，系统实现了高可用性和可维护性。文档详细介绍了各个组件的功能和使用方法，为开发者提供了全面的参考。