danial/kami_backend
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Files
96ed936079e5e9da79410aefaf8bd7728771eaff
kami_backend/.qoder/repowiki/zh/content/API端点参考/卡密信息管理API/天猫卡密管理API/天猫卡密账户管理.md
danial 96ed936079 docs(api): 添加详细Apple卡密管理API文档 
- 新增API端点参考文档，涵盖权限、卡密、订单、商户、监控、限制等模块
- 详细说明Apple卡密充值处理流程，包括提交、查询、回调和轮询接口
- 描述充值订单状态机及生命周期，支持超时重试和状态迁移
- 介绍签名验证、幂等控制及重复卡密防刷单策略
- 增加商户配置管理、历史记录查询和错误处理机制说明
- 提供API使用示例代码及客户端实现指导
- 删除过时的.drone.yml.bak文件，清理无用配置
- 添加.dockerignore忽略指定目录和文件
2025-10-08 20:13:40 +08:00

7.9 KiB
Raw Blame History

天猫卡密账户管理

**本文档引用文件** - [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)

目录

  1. 简介
  2. 核心接口说明
  3. 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

OAuth授权流程

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

Diagram sources

授权状态检查

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

Section sources

账户状态管理

状态切换接口

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

随机获取账户

  • HTTP方法: GET
  • URL模式: /recharge/tMallGame/account/getOneByRandom
  • 参数:
    • timeStamp: 时间戳
    • orderNo: 订单号
  • 行为: 若可用账户不足，自动创建新账户
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

Section sources

实际使用示例

天猫游戏账户创建

  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

客户端实现指南

授权流程实现

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

API调用最佳实践

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

性能优化建议

批量操作

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

缓存策略

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

异步处理

  • 账户不足时的自动创建使用异步处理
  • 避免阻塞主请求流程
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

Section sources