96ed936079
- 新增API端点参考文档，涵盖权限、卡密、订单、商户、监控、限制等模块 - 详细说明Apple卡密充值处理流程，包括提交、查询、回调和轮询接口 - 描述充值订单状态机及生命周期，支持超时重试和状态迁移 - 介绍签名验证、幂等控制及重复卡密防刷单策略 - 增加商户配置管理、历史记录查询和错误处理机制说明 - 提供API使用示例代码及客户端实现指导 - 删除过时的.drone.yml.bak文件，清理无用配置 - 添加.dockerignore忽略指定目录和文件
13 KiB
13 KiB
天猫卡密管理API
**本文档引用文件** - [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)目录
简介
本文档详细介绍了天猫卡密管理API，涵盖账户授权、订单处理、店铺管理等核心接口。重点说明了账户创建、OAuth授权、订单提交、店铺信息同步等端点的HTTP方法、URL模式、请求/响应模式和认证机制。文档还解释了天猫卡密特有的Agiso回调机制和workspace管理，提供错误处理策略和安全考虑，并包含客户端实现指南和性能优化建议。
项目结构
天猫卡密管理API的代码结构清晰，主要分为API接口层、内部逻辑层和服务层。API接口定义位于api/card_info_t_mall_game/v1/目录下，包含账户、订单、店铺、回调和工作空间等模块。内部实现位于internal/目录，包括模型定义、常量、控制器、服务和工具类。
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
- order.go
- shop.go
- callback.go
- workspace.go
- card_t_mall_game_account.go
- card_t_mall_game_order.go
- card_t_mall_game_work_space.go
- card_t_mall_account.go
- card_t_mall_order.go
章节来源
核心组件
天猫卡密管理API的核心组件包括账户管理、订单处理、店铺同步、回调处理和统计分析。账户管理负责天猫游戏账户的创建、查询和状态管理。订单处理模块处理订单的提交、查询和状态更新。店铺同步功能实现与天猫店铺订单的关联和信息同步。回调处理模块接收来自Agiso和天猫的回调通知。统计分析组件提供订单和账户的统计信息。
章节来源
架构概述
天猫卡密管理API采用分层架构设计，包括API接口层、业务逻辑层、服务层和数据访问层。API接口层定义了RESTful端点，业务逻辑层处理具体的业务规则，服务层提供可重用的服务接口，数据访问层负责与数据库交互。
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
图示来源
详细组件分析
账户管理分析
账户管理组件提供天猫游戏账户的全生命周期管理功能，包括创建、查询、状态切换和删除。
账户创建
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
图示来源
账户授权
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 : 返回授权结果
图示来源
章节来源
订单处理分析
订单处理组件管理天猫游戏订单的整个生命周期，从提交到完成。
订单提交
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
图示来源
订单状态查询
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 : 返回订单列表
图示来源
章节来源
店铺管理分析
店铺管理组件处理天猫店铺订单的同步和查询。
店铺订单同步
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
图示来源
章节来源
依赖分析
天猫卡密管理API的组件间存在清晰的依赖关系。API接口层依赖于服务层提供的接口，服务层依赖于数据访问层。各组件通过定义良好的接口进行交互，降低了耦合度。
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 : "使用"
图示来源
章节来源
性能考虑
天猫卡密管理API在设计时考虑了性能优化。通过使用缓存减少数据库查询，采用批量操作提高效率，实施限流防止系统过载。对于高频访问的统计接口，建议使用缓存策略。订单提交和状态更新操作应使用数据库事务确保数据一致性。
故障排除指南
常见问题
- 授权失败：检查授权码是否正确，回调地址是否匹配，网络连接是否正常。
- 订单提交失败：验证账户状态是否正常，订单金额是否符合要求，签名是否正确。
- 回调接收失败：确认回调URL是否可访问，防火墙设置是否允许外部请求。
错误处理
系统使用统一的错误处理机制，所有错误都通过errHandler包进行包装和处理。错误码遵循标准规范，便于客户端识别和处理。
章节来源
- 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
- card_info_t_mall_game_v1_t_mall_game_stats.go
结论
天猫卡密管理API提供了一套完整的解决方案，用于管理天猫游戏账户和订单。通过清晰的接口设计和分层架构，系统实现了高可用性和可维护性。文档详细介绍了各个组件的功能和使用方法，为开发者提供了全面的参考。